From 4bfd29dfd916e8c894e655456660994dd5680eca Mon Sep 17 00:00:00 2001 From: sebi Date: Thu, 19 Nov 2026 08:54:42 -0500 Subject: [PATCH 1/9] wip: r9 sweep 1 fixes (pre-gate) --- .dz/briefs/release-due.md | 2 +- .github/workflows/bench.yml | 9 +- .github/workflows/next-sync.yml | 22 +- .github/workflows/release-tag.yml | 14 +- .github/workflows/release.yml | 41 +++- .github/workflows/security-channel.yml | 9 +- CLAUDE.md | 2 +- packages/action/CLAUDE.md | 4 +- packages/action/README.md | 11 +- packages/action/src/action-stream.test.ts | 31 ++- packages/action/src/action.ts | 3 +- packages/action/src/http-dates.test.ts | 136 +++++++++++ packages/action/src/http-stream.test.ts | 66 ++++- packages/action/src/http-stream.ts | 57 ++++- packages/action/src/http.ts | 10 +- .../action/src/idempotency-memory-tx.test.ts | 55 +++++ packages/action/src/idempotency-memory.ts | 12 +- .../action/src/idempotency-undefined.test.ts | 63 +++++ packages/action/src/invoke.ts | 14 +- packages/action/src/record-wire.ts | 34 ++- packages/action/src/tx-scope.ts | 34 ++- packages/action/src/validate.ts | 20 ++ packages/ai/src/wire.ts | 4 +- packages/auth/CLAUDE.md | 4 + packages/auth/README.md | 38 +++ .../auth/src/grant-authorization-code.test.ts | 45 ++++ packages/auth/src/grant-authorization-code.ts | 10 +- .../auth/src/identity-provider-route-core.ts | 29 ++- packages/auth/src/identity-provider-routes.ts | 1 + packages/auth/src/index.ts | 1 + packages/auth/src/mfa-handoff.test.ts | 231 ++++++++++++++++++ packages/auth/src/mfa-handoff.ts | 86 +++++++ packages/auth/src/oauth-route.ts | 9 + packages/cache/CLAUDE.md | 15 +- packages/cache/README.md | 16 +- packages/cache/src/broadcast.test.ts | 34 +++ packages/cache/src/errors.ts | 15 +- packages/cache/src/invalidate.ts | 10 +- packages/cache/src/lru.test.ts | 16 ++ packages/cache/src/redis-buckets.ts | 88 +++++-- packages/cache/src/redis-ordering.test.ts | 47 +++- packages/cache/src/redis.ts | 64 +++-- packages/cache/src/semantic.test.ts | 16 ++ packages/cache/src/semantic.ts | 23 +- packages/cli/CLAUDE.md | 7 +- packages/cli/README.md | 2 +- .../e2e/client-navigation-modal-fixture.ts | 19 +- .../e2e/client-navigation-modal.e2e.test.ts | 20 ++ packages/cli/src/app-root.ts | 8 +- packages/cli/src/cmd-db-recount.ts | 17 +- packages/cli/src/cmd-db-status.ts | 15 +- packages/cli/src/cmd-db.ts | 15 +- packages/cli/src/cmd-merge-driver.ts | 7 +- packages/cli/src/cmd-stop.test.ts | 42 +++- packages/cli/src/cmd-stop.ts | 22 +- packages/cli/src/db-diagnostics.ts | 15 +- packages/cli/src/db-reset-lock.test.ts | 30 +++ packages/cli/src/dev-lock-live.ts | 24 ++ packages/cli/src/dev-lock.ts | 24 ++ packages/cli/src/dispatch.test.ts | 32 ++- packages/cli/src/dispatch.ts | 21 +- packages/cli/src/errors.ts | 13 +- packages/cli/src/mcp-host.ts | 4 +- packages/cli/src/merge-driver-lines.test.ts | 35 ++- packages/cli/src/merge-driver-lines.ts | 29 ++- packages/cli/src/parse.test.ts | 41 +++- packages/cli/src/parse.ts | 31 ++- packages/cli/src/role-select.ts | 57 +++++ packages/cli/src/role-start.test.ts | 10 + packages/cli/src/role-start.ts | 54 +--- packages/cli/src/runtime-cache-limits.test.ts | 37 +++ packages/cli/src/runtime-cache-ttl.ts | 23 ++ packages/cli/src/runtime-cache.ts | 12 +- packages/cli/src/runtime-database-ssl.test.ts | 124 ++++++++++ packages/cli/src/runtime-database-ssl.ts | 41 ++++ packages/cli/src/runtime-jobs.test.ts | 57 ++++- packages/cli/src/runtime-jobs.ts | 19 +- packages/cli/src/runtime-pooler.test.ts | 18 +- packages/cli/src/runtime-queue.test.ts | 18 +- packages/cli/src/runtime-queue.ts | 15 +- packages/cli/src/serve-boot.ts | 11 +- packages/cli/src/serve-env.ts | 26 +- .../cli/src/serve-graph-ceilings-fixture.ts | 7 +- .../serve-graph-serving-ceiling-fixture.ts | 7 +- .../src/serve-graph-web-ceiling-fixture.ts | 4 +- packages/cli/src/serve.test.ts | 44 ++++ packages/cli/src/serve.ts | 1 + packages/core/src/client-stream.test.ts | 29 +++ packages/core/src/client-stream.ts | 14 +- packages/core/src/config-defaults.ts | 4 +- packages/core/src/config-sections.test.ts | 4 +- packages/core/src/config.test.ts | 4 +- packages/core/src/config.ts | 5 +- packages/core/src/locale-direction.test.ts | 37 +++ packages/core/src/locale-direction.ts | 28 ++- packages/db/README.md | 2 +- packages/db/src/migrate.ts | 18 +- packages/db/src/migration-ledger.ts | 20 ++ .../db/src/rollback-order-embedded.test.ts | 82 +++++++ packages/entity/CLAUDE.md | 5 + packages/entity/README.md | 8 +- packages/entity/src/aggregate.ts | 7 +- .../entity/src/batch-key-spelling.test.ts | 11 + packages/entity/src/batch-read.ts | 61 ++++- packages/entity/src/coalesce.test.ts | 60 ++++- packages/entity/src/coalesce.ts | 5 +- packages/entity/src/columns.ts | 7 +- packages/entity/src/entity-patch.ts | 3 + packages/entity/src/instant-range.test.ts | 95 +++++++ packages/entity/src/instant-range.ts | 38 +++ packages/entity/src/instant.ts | 14 ++ packages/entity/src/jit-preload.ts | 5 +- packages/entity/src/pg-aggregate.live.test.ts | 4 +- .../entity/src/pg-driver-filtered.test.ts | 7 +- packages/entity/src/pg-sql-aggregate.ts | 30 ++- packages/entity/src/pg-sql-in.ts | 44 ++++ packages/entity/src/pg-sql-measures.ts | 4 +- packages/entity/src/pg-sql.test.ts | 18 +- packages/entity/src/pg-sql.ts | 30 +-- .../entity/src/predicate-operand.live.test.ts | 133 ++++++++++ packages/entity/src/predicate-operand.test.ts | 137 ++++++++++- packages/entity/src/predicate-operand.ts | 108 +++++++- packages/entity/src/refuse.test.ts | 6 + packages/entity/src/search-sql.test.ts | 4 +- packages/entity/src/uuid-text.test.ts | 59 +++++ packages/entity/src/uuid-text.ts | 22 ++ packages/i18n/README.md | 3 +- packages/i18n/src/subset.test.ts | 36 ++- packages/i18n/src/subset.ts | 29 ++- packages/i18n/src/translator.test.ts | 27 ++ packages/i18n/src/translator.ts | 14 +- packages/jobs/CLAUDE.md | 12 +- packages/jobs/README.md | 15 ++ packages/jobs/src/adapter.ts | 4 +- packages/jobs/src/driver-pg-operator-sql.ts | 11 +- packages/jobs/src/driver-pg-wake-sql.ts | 8 + packages/jobs/src/enqueue-signal.ts | 5 +- packages/jobs/src/job.ts | 7 +- packages/jobs/src/queue-wake.live.test.ts | 29 ++- packages/jobs/src/queue-wake.test.ts | 87 ++++++- packages/jobs/src/queue-wake.ts | 89 ++++++- packages/jobs/src/retry-default.test.ts | 92 +++++++ packages/jobs/src/retry-default.ts | 45 ++++ packages/jobs/src/scheduler-dispatch.ts | 4 + .../jobs/src/scheduler-pg-fire.job.test.ts | 39 +++ packages/jobs/src/scheduler-pg.ts | 4 + packages/jobs/src/scheduler-tenant.test.ts | 116 +++++++++ packages/mail/src/driver-ses.test.ts | 22 ++ packages/mail/src/driver-ses.ts | 14 +- packages/mail/src/smtp-socket.test.ts | 30 +++ packages/mail/src/smtp-socket.ts | 56 ++++- packages/manifest/src/build.test.ts | 25 ++ packages/manifest/src/build.ts | 8 +- packages/mcp/README.md | 2 +- packages/mcp/src/remote-client.test.ts | 151 ++++++++++++ packages/mcp/src/remote-client.ts | 91 +++++-- packages/money/src/arithmetic.test.ts | 27 ++ packages/money/src/arithmetic.ts | 6 +- packages/money/src/format.test.ts | 25 +- packages/money/src/money.ts | 9 +- packages/money/src/parse-input.test.ts | 3 + packages/money/src/parse-numerals.ts | 6 +- packages/money/src/rescale.ts | 4 +- packages/money/src/scale.ts | 14 +- packages/pwa/CLAUDE.md | 2 +- packages/pwa/src/pages-cache-source.ts | 5 +- .../pwa/src/service-worker-activate.test.ts | 18 +- .../pwa/src/service-worker-harness-fixture.ts | 20 ++ .../pwa/src/service-worker-runtime.test.ts | 18 +- packages/pwa/src/service-worker.ts | 8 +- packages/query/src/download-http.test.ts | 35 ++- packages/query/src/download-http.ts | 5 +- packages/query/src/download.test.ts | 55 +++++ packages/query/src/download.ts | 28 ++- packages/realtime/CLAUDE.md | 3 +- packages/realtime/src/channel-authz.ts | 15 +- packages/realtime/src/channel-decl.ts | 4 +- packages/realtime/src/channel-logs.ts | 38 ++- packages/realtime/src/channel-records.ts | 9 +- packages/realtime/src/channel-render.ts | 4 +- packages/realtime/src/channel-ring.ts | 7 + packages/realtime/src/channel-tenant.test.ts | 115 ++++++++- packages/realtime/src/channel-tenant.ts | 57 ++++- packages/realtime/src/fanout.ts | 32 ++- packages/realtime/src/live-definition.test.ts | 24 ++ packages/realtime/src/policy-gate.ts | 39 ++- packages/realtime/src/presence.test.ts | 18 ++ packages/realtime/src/socket-channel-drops.ts | 21 ++ packages/realtime/src/socket.ts | 34 +-- packages/render/CLAUDE.md | 4 +- packages/render/src/asset.test.ts | 14 ++ packages/render/src/asset.ts | 2 +- packages/render/src/head.ts | 20 +- packages/render/src/html.ts | 15 ++ packages/render/src/hydrate-replay.test.ts | 5 + packages/render/src/hydrate-runtime.test.ts | 135 ++++++++++ packages/render/src/hydrate.ts | 9 +- packages/render/src/island-budget.test.ts | 9 +- .../render/src/island-hold-replay.test.ts | 1 + packages/render/src/island-hold.test.ts | 1 + packages/render/src/modes.ts | 6 +- packages/render/src/render-html.test.ts | 32 +++ packages/render/src/render-walk.ts | 38 ++- packages/schema/src/json-schema.test.ts | 38 +++ packages/schema/src/json-schema.ts | 19 +- packages/schema/src/sample-draw.ts | 11 + packages/schema/src/sample.test.ts | 16 ++ packages/schema/src/sample.ts | 15 +- packages/scraping/src/cdp-connection.test.ts | 44 +++- packages/scraping/src/cdp-connection.ts | 40 ++- .../src/entity-conformance-aggregates.ts | 46 +++- packages/ui/src/components/Menu.tsx | 6 +- packages/ui/src/components/Popover.tsx | 6 +- packages/ui/src/components/overlays.test.ts | 33 +++ .../ui/src/content/markdown-inline.test.ts | 25 ++ packages/ui/src/content/markdown-inline.ts | 3 +- scripts/ci-workflow-token-push.test.ts | 118 +++++++++ scripts/config-readers.test.ts | 68 +++--- scripts/config-readers.ts | 24 +- scripts/lib/config-leaves.ts | 17 +- scripts/lib/config-read-evidence.test.ts | 79 ++++++ scripts/lib/config-read-evidence.ts | 52 +++- scripts/lib/config-reader-pins.ts | 6 +- scripts/lib/major-window.test.ts | 18 ++ scripts/next-sync-workflow-run.test.ts | 20 +- scripts/next-sync-workflow-shape.test.ts | 11 +- scripts/release-tag-workflow-shape.test.ts | 12 +- scripts/release-workflow-publish-run.test.ts | 134 ++++++++++ .../security-channel-workflow-shape.test.ts | 7 +- wiki/Auth.md | 6 + wiki/Configuration.md | 10 +- wiki/Realtime.md | 9 + 232 files changed, 6000 insertions(+), 648 deletions(-) create mode 100644 packages/action/src/http-dates.test.ts create mode 100644 packages/action/src/idempotency-memory-tx.test.ts create mode 100644 packages/action/src/idempotency-undefined.test.ts create mode 100644 packages/auth/src/mfa-handoff.test.ts create mode 100644 packages/auth/src/mfa-handoff.ts create mode 100644 packages/cli/src/dev-lock-live.ts create mode 100644 packages/cli/src/role-select.ts create mode 100644 packages/cli/src/runtime-cache-ttl.ts create mode 100644 packages/cli/src/runtime-database-ssl.test.ts create mode 100644 packages/cli/src/runtime-database-ssl.ts create mode 100644 packages/core/src/locale-direction.test.ts create mode 100644 packages/db/src/rollback-order-embedded.test.ts create mode 100644 packages/entity/src/instant-range.test.ts create mode 100644 packages/entity/src/instant-range.ts create mode 100644 packages/entity/src/pg-sql-in.ts create mode 100644 packages/entity/src/predicate-operand.live.test.ts create mode 100644 packages/entity/src/uuid-text.test.ts create mode 100644 packages/entity/src/uuid-text.ts create mode 100644 packages/jobs/src/retry-default.test.ts create mode 100644 packages/jobs/src/retry-default.ts create mode 100644 packages/jobs/src/scheduler-tenant.test.ts create mode 100644 packages/realtime/src/socket-channel-drops.ts create mode 100644 packages/ui/src/content/markdown-inline.test.ts create mode 100644 scripts/ci-workflow-token-push.test.ts create mode 100644 scripts/lib/config-read-evidence.test.ts create mode 100644 scripts/release-workflow-publish-run.test.ts diff --git a/.dz/briefs/release-due.md b/.dz/briefs/release-due.md index 176e5c55a..4894b6460 100644 --- a/.dz/briefs/release-due.md +++ b/.dz/briefs/release-due.md @@ -49,7 +49,7 @@ it and stop: this session cannot fetch or switch branches. The envelope is input, and `data.due` is the script's count, not the verdict. Some reasons do settle it: `nothing_ships` leaves nothing to release, `awaiting_tag` is one already cutting, and a major -stays a maintainer's — inside the major window: from v30, at most one major per 90 days +stays a maintainer's — inside the major window: from v31, at most one major per 90 days ([`wiki/Stability.md`](../../wiki/Stability.md)), and only a security fix that cannot be non-breaking takes the exception (`--security `). diff --git a/.github/workflows/bench.yml b/.github/workflows/bench.yml index 6507c187c..9fdedf9eb 100644 --- a/.github/workflows/bench.yml +++ b/.github/workflows/bench.yml @@ -19,11 +19,13 @@ on: # the cadence; a figure wanted sooner is `gh workflow run bench.yml --ref main`. workflow_dispatch: -# `contents: write` + `pull-requests: write`: the branch and the pull request with the new JSON. No -# `id-token` and no new secret — the job's own token is all it holds. +# `contents: write` + `pull-requests: write`: the branch and the pull request with the new JSON; +# `actions: write`: the ci.yml dispatch that gates that branch. No `id-token` and no new secret — +# the job's own token is all it holds. permissions: contents: write pull-requests: write + actions: write concurrency: group: bench @@ -89,6 +91,9 @@ jobs: # Forced: the branch is always one commit of figures on today's `main`, and last week's # figures are what this run supersedes. The replaced commit stays on the pull request. git push --force "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" "$BRANCH" + # A push made with the job token starts no workflow, so the pull request would wait on a + # `verify` check that never reports; a dispatch is GitHub's exception, as next-sync.yml's. + gh workflow run ci.yml --ref "$BRANCH" OPEN="$(gh pr list --head "$BRANCH" --state open --json number --jq '.[0].number // empty')" if [ -n "$OPEN" ]; then gh pr edit "$OPEN" --body "$BODY" diff --git a/.github/workflows/next-sync.yml b/.github/workflows/next-sync.yml index fe896407f..b36fbabb0 100644 --- a/.github/workflows/next-sync.yml +++ b/.github/workflows/next-sync.yml @@ -105,8 +105,9 @@ jobs: report: needs: merge - # On the merge's answer only: a red `merge` job filed nothing to report. - if: ${{ !cancelled() && needs.merge.result == 'success' }} + # On the merge's answer AND on its failure: a red `merge` job (no `next`, a refused push, a merge + # that failed with no conflict) is a week `next` fell behind, and it files the same issue. + if: ${{ !cancelled() }} runs-on: ubuntu-latest timeout-minutes: 5 permissions: @@ -117,6 +118,7 @@ jobs: GH_TOKEN: ${{ github.token }} GH_REPO: ${{ github.repository }} BLOCKED: ${{ needs.merge.outputs.blocked }} + MERGE_RESULT: ${{ needs.merge.result }} FILES: ${{ needs.merge.outputs.files }} RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} shell: bash @@ -127,6 +129,10 @@ jobs: # Only this workflow's own issue: anyone may open one with the same title. open="$(gh issue list --state open --author 'app/github-actions' --search "$TITLE in:title" \ --json number,title | jq -r --arg t "$TITLE" 'map(select(.title == $t)) | .[0].number // empty')" + # A merge job that went red handed nothing on: never read as a clean week, never closing. + if [ "$MERGE_RESULT" != 'success' ]; then + BLOCKED='failed' + fi if [ -z "$BLOCKED" ]; then if [ -n "$open" ]; then gh issue close "$open" --comment "main merged cleanly into next: $RUN_URL" @@ -134,7 +140,17 @@ jobs: exit 0 fi body="$RUNNER_TEMP/next-sync.md" - if [ "$BLOCKED" = 'workflows' ]; then + if [ "$BLOCKED" = 'failed' ]; then + { + echo "The weekly merge of \`main\` into \`next\` failed (merge job: $MERGE_RESULT), so \`next\` may be behind \`main\`: $RUN_URL" + echo + echo 'The merge job log at that run names the cause on its ::error:: line. Fix it, then re-run; the next clean run closes this issue:' + echo + echo '```bash' + echo 'gh workflow run next-sync.yml' + echo '```' + } > "$body" + elif [ "$BLOCKED" = 'workflows' ]; then { echo "The weekly merge of \`main\` into \`next\` is clean but changes workflow files, which the job token may not push, so it was not pushed: $RUN_URL" echo diff --git a/.github/workflows/release-tag.yml b/.github/workflows/release-tag.yml index 3bf011ca4..8db7173d3 100644 --- a/.github/workflows/release-tag.yml +++ b/.github/workflows/release-tag.yml @@ -37,11 +37,10 @@ on: # a bump branch named `release/31.1.0` was tagged off main's history (#1054). branches: [main, 'release/[0-9]+.x'] -# One release cut at a time, and never cancelled: a tag without its Release, or a Release without -# its dispatch, is a half-cut release a human then has to finish. -concurrency: - group: release-tag - cancel-in-progress: false +# No workflow-level concurrency: every ci.yml completion on main starts this workflow, and a group +# keeps ONE pending run — a third arrival cancels the pending one whatever `cancel-in-progress` +# says, so a release commit's run waiting behind an ordinary commit's could be dropped. The queue +# is on `cut`, which only a release cut ever reaches. permissions: contents: read @@ -168,6 +167,11 @@ jobs: cut: needs: prepare if: needs.prepare.outputs.cut == 'true' + # One release cut at a time, and never cancelled: a tag without its Release, or a Release + # without its dispatch, is a half-cut release a human then has to finish. + concurrency: + group: release-tag + cancel-in-progress: false runs-on: ubuntu-latest timeout-minutes: 10 permissions: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 36465d12d..ab3ad447b 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -306,25 +306,40 @@ jobs: # then died `E401 … token is invalid` on schema 71 s later while the registry was slow # to stage — and every re-run lost the rest of its tier the same way. for name in $names; do - held="$(npm view "${name}@${VERSION}" version 2>/dev/null || true)" - if [ "$held" = "$VERSION" ]; then - echo "::notice::skipping ${name}@${VERSION} — npm already holds it, published by an earlier attempt of this release" - continue - fi - echo "::group::npm publish — tier $tier: $name" - if ! out="$(npm publish -w "$name" --tag "$DIST_TAG" 2>&1)"; then + # BOUNDED RETRY: the weekly bot release has nobody on call, and a transient failure — a + # Sigstore TLOG 409, an E401 from a slow token exchange, a registry 5xx — killed the + # whole run. Three attempts, a pause between, and npm asked AGAIN before each one: an + # attempt that died after the registry took the tarball is this release's, never a + # re-publish into E403. Provenance is untouched: each attempt is the same command. + attempt=1 + while :; do + held="$(npm view "${name}@${VERSION}" version 2>/dev/null || true)" + if [ "$held" = "$VERSION" ]; then + echo "::notice::skipping ${name}@${VERSION} — npm already holds it, published by an earlier attempt of this release" + break + fi + echo "::group::npm publish — tier $tier: $name (attempt $attempt)" + if out="$(npm publish -w "$name" --tag "$DIST_TAG" 2>&1)"; then + echo "$out" + echo "::endgroup::" + break + fi echo "$out" + echo "::endgroup::" # npm STAGES a publish before `npm view` can see it, so an attempt that raced a # previous one meets its own staged copy. That version is already this release's. if printf '%s' "$out" | grep -q 'previously staged version'; then echo "::notice::${name}@${VERSION} is staged by an earlier attempt — npm will publish it" - echo "::endgroup::" - continue + break fi - exit 1 - fi - echo "$out" - echo "::endgroup::" + if [ "$attempt" -ge 3 ]; then + echo "::error::npm publish of ${name}@${VERSION} failed 3 times — read the npm error above. The run resumes where it stopped: gh workflow run release.yml --ref v${VERSION} -f version=${VERSION}" + exit 1 + fi + echo "::warning::npm publish of ${name}@${VERSION} failed (attempt ${attempt} of 3) — asking npm again in $((attempt * 30)) s" + sleep "$((attempt * 30))" + attempt=$((attempt + 1)) + done done done <<< "$plan" diff --git a/.github/workflows/security-channel.yml b/.github/workflows/security-channel.yml index 28be5adf9..bc4bce87f 100644 --- a/.github/workflows/security-channel.yml +++ b/.github/workflows/security-channel.yml @@ -63,11 +63,13 @@ jobs: floors: # `contents: write` + `pull-requests: write`: the branch and the pull request with the raised - # ranges, as bench.yml opens one. `issues: write`: the alarm for an advisory no floor closes. No - # `id-token`: this job can never publish, only propose; a release ships the raise. + # ranges, as bench.yml opens one. `actions: write`: the ci.yml dispatch that gates that branch. + # `issues: write`: the alarm for an advisory no floor closes. No `id-token`: this job can never + # publish, only propose; a release ships the raise. permissions: contents: write pull-requests: write + actions: write issues: write runs-on: ubuntu-latest # One packument and one advisory query per dependency, a few dozen in all, measured well under a @@ -122,6 +124,9 @@ jobs: BRANCH='security/advisory-floors' # One branch, force-pushed: tomorrow's run refreshes today's pull request, never a second. git push --force "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" "$BRANCH" + # A push made with the job token starts no workflow, so the pull request would wait on a + # `verify` check that never reports; a dispatch is GitHub's exception, as next-sync.yml's. + gh workflow run ci.yml --ref "$BRANCH" body="$(jq -r '"**" + .summary + "**\n\n" + ([.data.raises[] | "- `" + .manifest + "` " + .field + "." + .name + ": `" + .from + "` -> `" + .to + "` (" + ([.advisories[].advisory] | unique | join(", ")) + ")"] | join("\n")) + "\n\nThe root `package.json`, the scaffold pin and the tracked apps may pin the old version: CI on this branch names them."' floors.json)" existing="$(gh pr list --head "$BRANCH" --state open --limit 1 --json number --jq '.[0].number // empty')" if [ -n "$existing" ]; then diff --git a/CLAUDE.md b/CLAUDE.md index 4ac0d1f6f..a28017359 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,7 +16,7 @@ tracked apps — the reference app (`examples/dummy`), the deployed demo `@ultimat3`, imports `@ultimat3/`. **Status:** released, every package in lockstep. Semver covers the primitive shapes, the `x` CLI, -the tier table and the `X_*` codes; from v30 one major per 90 days (`X_RELEASE_MAJOR_WINDOW`), +the tier table and the `X_*` codes; from v31 one major per 90 days (`X_RELEASE_MAJOR_WINDOW`), breaks wait on `next` (`X_BREAKING_ON_MAIN`): [`wiki/Stability.md`](wiki/Stability.md). **This page states no version number, on purpose.** Every fact below is a command. What each diff --git a/packages/action/CLAUDE.md b/packages/action/CLAUDE.md index 17626995b..a2064b7b6 100644 --- a/packages/action/CLAUDE.md +++ b/packages/action/CLAUDE.md @@ -31,10 +31,10 @@ Owns the `action` + `mutator` primitives and five projections. Tier 3. The MCP t | `errors-http.ts` | the three HTTP-declaration refusals | | `error-titles.ts` | every code's title, the one `registerErrorCodes` | | `client.ts` | typed RPC client (browser-safe: no server imports) — dispatches through core's `clientTransport` | -| `record-wire.ts` | the record envelope on the HTTP projection: `carriesRecords` (from the output schema), the enveloped 200, and its OpenAPI shape. Server-only — `client.ts` never imports it | +| `record-wire.ts` | the action's 200 on the HTTP projection: `carriesRecords` (from the output schema), either body + `x-ultimate-dates`. Server-only — `client.ts` never imports it | | `wire-issues.ts` | the ONE reader of a problem document's `issues` member — an untrusted array back into `@ultimat3/schema`'s `ValidationIssue` shape | | `action-stream.ts` | `streamingDef`: a `stream`-declaring `handle` (an async generator) DRAINED, each chunk parsed by `stream` (`X_ACTION_STREAM_INVALID`, `errors-stream.ts`); `chunksRead()` | -| `http-stream.ts` | `accept: text/event-stream` → `event: chunk`… then ONE `done` or `error`; a refusal before the handler is the ordinary problem response | +| `http-stream.ts` | `accept: text/event-stream` → `event: chunk`… then ONE `done` (+ `dates:`) or `error` (a 5xx reported); a refusal before the handler is the plain problem | | `audit-subject-target.ts` | `auditSubjectTarget()`: `x_audit` as a subject-erase target — overwrites who acted and the input, never deletes the row | | `transition.ts` | `transition()`: a MUTATOR factory over one entity column's state machine. Declares no error code — entity's three propagate | | `upload-flow.ts` | `uploadFlow()`: an ACTION factory, `{ request, confirm }` over storage's `grantUpload` (pending only) and `promoteAttachment`. No code of its own | diff --git a/packages/action/README.md b/packages/action/README.md index 5f5b76b50..9c0853245 100644 --- a/packages/action/README.md +++ b/packages/action/README.md @@ -168,6 +168,15 @@ returned none, so one operation has one wire shape. Every other action's body is what it was before the envelope existed, and its OpenAPI operation is unchanged; an enveloped one documents `data`, `records` and `removed`, and the header, generated from the declaration. +### Instants — a `Date` output is a `Date` on the client + +An output holding a `Date` (`t.date`, an entity `timestamp()` row) names each one by path in +`x-ultimate-dates`, on the plain and the enveloped 200 alike — `@ultimat3/query`'s rule — and the +typed client hands back the `Date` the output type promises (`As of 2026-11`). The body and the +OpenAPI document are unchanged: a client that ignores the header reads the ISO string it always +read. A streamed `done` frame carries the same paths on a `dates:` field, which an SSE reader that +does not know it ignores. + ### Flight control — `clientFlight`, opt-in Same object as `@ultimat3/query`'s, installed the same way (`rpc({ baseUrl, flight })`), and the @@ -208,7 +217,7 @@ An action may answer in pieces before it answers. `stream: ` besid | Caller | Gets | |---|---| -| `accept: text/event-stream` on its route | `event: chunk` per yield (each parsed by `stream` first), then one `done` (the output) or `error` (the problem document); `x-accel-buffering: no`, never compressed | +| `accept: text/event-stream` on its route | `event: chunk` per yield (each parsed by `stream` first), then one `done` (the output, its instants on a `dates:` field) or `error` (the problem document; a 5xx is reported as the JSON path's is); `x-accel-buffering: no`, never compressed | | JSON, MCP, `.job()`, `.as()`, a direct call | the generator drained: the output alone, one contract | | the typed client | `api.sayWords.stream(input)` — an `AsyncGenerator` of chunks whose return is the output, through core's `clientStream` (POST, the page's credentials, the same problem decode). Typed on a stream-declaring method only (`StreamClientMethod`); never retried | | the handler itself | `chunksRead()` — `true` only while a caller reads the chunks; `llm()` streams its one-attempt turn then, and is the repairing call otherwise | diff --git a/packages/action/src/action-stream.test.ts b/packages/action/src/action-stream.test.ts index 776183d7a..dbbce275f 100644 --- a/packages/action/src/action-stream.test.ts +++ b/packages/action/src/action-stream.test.ts @@ -7,7 +7,7 @@ import { defineHttpConfig, httpServer } from '@ultimat3/http'; import { allow } from '@ultimat3/policy'; import { t } from '@ultimat3/schema'; import type { AnyAction } from './action'; -import { action } from './action'; +import { action, nameAction } from './action'; import { chunksRead } from './action-stream'; import { toRoute } from './http'; @@ -78,3 +78,32 @@ describe('chunksRead', () => { expect(chunksRead()).toBe(false); }); }); + +describe('the name a stream refusal carries', () => { + test('a stream action named by registerAction names itself in X_ACTION_STREAM_INVALID', async () => { + // Unnamed at declaration, named in place — `registerAction`'s path (`nameAction`). + const broken = nameAction( + action({ + input: t.object({}), + output: t.object({ ok: t.boolean }), + stream: Chunk, + policy: allow('probe:broken'), + async *handle() { + yield { read: 'no' } as unknown as { read: boolean }; + return { ok: true }; + }, + }), + 'brokenProbe', + ); + const refused = await runWithContext(ctxOf({ actor: userActor({ id: 'u1' }) }), () => + broken({}).then( + () => undefined, + (error: unknown) => error, + ), + ); + expect(refused).toMatchObject({ + code: 'X_ACTION_STREAM_INVALID', + meta: { action: 'brokenProbe' }, + }); + }); +}); diff --git a/packages/action/src/action.ts b/packages/action/src/action.ts index 9498f5cec..c5ec269b9 100644 --- a/packages/action/src/action.ts +++ b/packages/action/src/action.ts @@ -417,7 +417,8 @@ function build & StreamFields, () => name), + // `self.name`, read per refusal: `nameAction` names in place after this line has run. + streamingDef(def as ActionDef & StreamFields, () => self.name), ); return self; } diff --git a/packages/action/src/http-dates.test.ts b/packages/action/src/http-dates.test.ts new file mode 100644 index 000000000..81fbefaae --- /dev/null +++ b/packages/action/src/http-dates.test.ts @@ -0,0 +1,136 @@ +// An action's `Date` output over the real pipeline: the plain 200, the enveloped 200 and the +// streamed `done` frame each name their instants (`x-ultimate-dates`, the read projection's rule), +// so the typed client hands back the `Date` the output type promises. The body stays the ISO text. + +import { afterAll, describe, expect, test } from 'bun:test'; +import { DATES_HEADER, RECORDS_HEADER, reviveWireDates, userActor } from '@ultimat3/core'; +import { clearRegistry, entity, timestamp, uuid } from '@ultimat3/entity'; +import { defineHttpConfig, httpServer } from '@ultimat3/http'; +import { allow } from '@ultimat3/policy'; +import { t } from '@ultimat3/schema'; +import type { AnyAction } from './action'; +import { action } from './action'; +import type { FetchLike } from './client'; +import { toRoute } from './http'; + +const AT = new Date('2026-03-04T05:06:07.089Z'); +const ID = '00000000-0000-7000-8000-0000000000aa'; + +const events = entity('http_dates_events', { + columns: { id: uuid().primaryKey(), at: timestamp() }, +}); + +afterAll(() => { + clearRegistry(); +}); + +const stamp = action({ + input: t.object({}), + output: t.object({ at: t.date, note: t.string }), + policy: allow(), + handle: () => ({ at: AT, note: AT.toISOString() }), +}).named('stampDate'); + +const record = action({ + input: t.object({}), + output: events.$schema, + policy: allow(), + handle: () => ({ id: ID, at: AT }), +}).named('recordEvent'); + +const plain = action({ + input: t.object({}), + output: t.object({ note: t.string }), + policy: allow(), + handle: () => ({ note: 'n' }), +}).named('plainNote'); + +const streamed = action({ + input: t.object({}), + output: t.object({ at: t.date }), + stream: t.object({ n: t.number }), + policy: allow(), + async *handle() { + yield { n: 1 }; + return { at: AT }; + }, +}).named('streamDate'); + +function fetchOf(target: AnyAction): FetchLike { + const server = httpServer({ + routes: [toRoute(target)], + config: defineHttpConfig({ rateLimit: { scope: 'process' } }), + hooks: { authenticate: () => userActor({ id: 'u1' }) }, + }); + return (url, init) => + server.fetch( + new Request(url, { + ...init, + headers: { ...Object.fromEntries(new Headers(init.headers)), origin: 'http://dev.test' }, + }), + ); +} + +const post = (target: AnyAction, accept = 'application/json'): Promise => + fetchOf(target)(`http://dev.test${toRoute(target).path}`, { + method: 'POST', + headers: { 'content-type': 'application/json', accept }, + body: '{}', + }); + +describe('an action whose output holds a Date', () => { + test('an output Date is named in x-ultimate-dates and the typed client hands back a Date', async () => { + const response = await post(stamp); + expect(response.headers.get(DATES_HEADER)).not.toBeNull(); + // The body is what it always was: an old client reads the ISO string it always read. + expect(await response.json()).toEqual({ at: AT.toISOString(), note: AT.toISOString() }); + + const call = stamp.client({ baseUrl: 'http://dev.test', fetch: fetchOf(stamp) }); + const out = await call({}); + expect(out.at).toBeInstanceOf(Date); + expect(out.at).toEqual(AT); + expect(out.note).toBe(AT.toISOString()); + }); + + test('the enveloped 200 names the instants of its data, beside x-ultimate-records', async () => { + const response = await post(record); + expect(response.headers.get(RECORDS_HEADER)).toBe('1'); + expect(response.headers.get(DATES_HEADER)).not.toBeNull(); + + const call = record.client({ baseUrl: 'http://dev.test', fetch: fetchOf(record) }); + expect(await call({})).toEqual({ id: ID, at: AT }); + }); + + test('an output with no Date sends no header', async () => { + const response = await post(plain); + expect(response.headers.get(DATES_HEADER)).toBeNull(); + }); + + test("the streamed done frame names its output's instants on a field old clients ignore", async () => { + const text = await (await post(streamed, 'text/event-stream')).text(); + const done = text.split('\n\n').find((block) => block.startsWith('event: done')); + const lines = done?.split('\n') ?? []; + const dates = lines.find((line) => line.startsWith('dates: '))?.slice(7) ?? null; + const data = lines.find((line) => line.startsWith('data: '))?.slice(6) ?? 'null'; + expect(dates).not.toBeNull(); + // The data line is unchanged; the paths revive it exactly as the header revives a JSON body. + expect(JSON.parse(data)).toEqual({ at: AT.toISOString() }); + expect(reviveWireDates(JSON.parse(data) as unknown, dates)).toEqual({ at: AT }); + }); + + test('a done frame with no instant carries no dates field', async () => { + const quiet = action({ + input: t.object({}), + output: t.object({ n: t.number }), + stream: t.object({ n: t.number }), + policy: allow(), + async *handle() { + yield { n: 1 }; + return { n: 2 }; + }, + }).named('streamQuiet'); + expect(await (await post(quiet, 'text/event-stream')).text()).toBe( + 'event: chunk\ndata: {"n":1}\n\nevent: done\ndata: {"n":2}\n\n', + ); + }); +}); diff --git a/packages/action/src/http-stream.test.ts b/packages/action/src/http-stream.test.ts index 84e7c3732..b4b7cc21b 100644 --- a/packages/action/src/http-stream.test.ts +++ b/packages/action/src/http-stream.test.ts @@ -1,14 +1,24 @@ // The streamed projection over the real pipeline: frames in order, a refusal before the handler is // the plain problem, a cancelled body aborts `ctx.signal`, a refused chunk is ONE error frame. -import { describe, expect, test } from 'bun:test'; +import { afterEach, describe, expect, test } from 'bun:test'; import type { Actor } from '@ultimat3/core'; -import { ctxOf, runWithContext, useContext, userActor } from '@ultimat3/core'; +import { + ctxOf, + InternalError, + memoryErrorReporter, + resetErrorReporting, + runWithContext, + useContext, + userActor, +} from '@ultimat3/core'; +import { installErrorReporter } from '@ultimat3/core/adapter'; import { defineHttpConfig, httpServer } from '@ultimat3/http'; import { allow, can } from '@ultimat3/policy'; import { t } from '@ultimat3/schema'; import type { AnyAction } from './action'; import { action } from './action'; +import { InputInvalidError } from './errors'; import { toOpenApiOperation, toRoute } from './http'; import { wantsEventStream } from './http-stream'; @@ -49,6 +59,10 @@ const sayWords = () => }).named('sayWords'); describe('a stream-declaring action over HTTP', () => { + afterEach(() => { + resetErrorReporting(); + }); + test('accept: text/event-stream answers chunk frames, then one done frame', async () => { const response = await call(serve(sayWords()), 'text/event-stream'); expect(response.status).toBe(200); @@ -105,6 +119,54 @@ describe('a stream-declaring action over HTTP', () => { expect(frames[1]).toContain('X_ACTION_STREAM_INVALID'); }); + test('a handler that throws after its first chunk is reported once, like the JSON path', async () => { + const reporter = memoryErrorReporter(); + installErrorReporter(reporter); + const fault = () => + action({ + input: t.object({ n: t.number }), + output: Out, + stream: Chunk, + policy: allow('words:say'), + async *handle() { + yield { text: 'first' }; + throw new InternalError({ cause: 'the store went away', fix: 'bun run x -- doctor' }); + }, + }).named('sayWords'); + const json = await call(serve(fault()), 'application/json'); + expect(json.status).toBe(500); + expect(reporter.events).toHaveLength(1); + const viaJson = reporter.events[0]; + reporter.reset(); + + const text = await (await call(serve(fault()), 'text/event-stream')).text(); + expect(text).toContain('event: error\n'); + expect(reporter.events).toHaveLength(1); + const viaStream = reporter.events[0]; + expect(viaStream?.source).toBe('http'); + expect(viaStream?.code).toBe(viaJson?.code); + expect(viaStream?.scope.operation).toBe(viaJson?.scope.operation); + expect(viaStream?.scope.requestId).not.toBeUndefined(); + }); + + test("a 4xx thrown after the first chunk is the caller's and is not reported", async () => { + const reporter = memoryErrorReporter(); + installErrorReporter(reporter); + const broken = action({ + input: t.object({ n: t.number }), + output: Out, + stream: Chunk, + policy: allow('words:say'), + async *handle() { + yield { text: 'first' }; + throw new InputInvalidError('sayWords', 'n ran past the words there are'); + }, + }).named('sayWords'); + const text = await (await call(serve(broken), 'text/event-stream')).text(); + expect(text).toContain('X_INPUT_INVALID'); + expect(reporter.events).toEqual([]); + }); + test('cancelling the body aborts ctx.signal inside the handler', async () => { let release: () => void = () => undefined; const held = new Promise((resolve) => { diff --git a/packages/action/src/http-stream.ts b/packages/action/src/http-stream.ts index 7998cda08..9df1d3545 100644 --- a/packages/action/src/http-stream.ts +++ b/packages/action/src/http-stream.ts @@ -5,8 +5,15 @@ * handler starts — the policy, the input, the rate limit — is the ordinary problem response. */ -import { useContext, withChildContext } from '@ultimat3/core'; -import { toProblem } from '@ultimat3/http'; +import type { Ctx } from '@ultimat3/core'; +import { + isAnonymous, + reportError, + useContext, + wireDatePaths, + withChildContext, +} from '@ultimat3/core'; +import { factsOf, toProblem } from '@ultimat3/http'; import type { ChunkSink } from './action-stream'; export const EVENT_STREAM = 'text/event-stream'; @@ -25,9 +32,37 @@ export function wantsEventStream(accept: string | null): boolean { const encoder = new TextEncoder(); const STARTED: unique symbol = Symbol('started'); -/** One SSE frame. JSON never holds a raw newline, so `data:` is always one line. */ -export function sseFrame(event: 'chunk' | 'done' | 'error', data: unknown): Uint8Array { - return encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data ?? null)}\n\n`); +/** + * One SSE frame. JSON never holds a raw newline, so `data:` is always one line. `dates` is the + * `x-ultimate-dates` value for THIS frame's data (core's `wire-dates.ts`, URI-encoded, so one line + * too): a field the SSE format tells every reader that does not know it to ignore, so a client from + * before it reads the frame it always read. + */ +export function sseFrame( + event: 'chunk' | 'done' | 'error', + data: unknown, + dates?: string, +): Uint8Array { + const named = dates === undefined ? '' : `dates: ${dates}\n`; + return encoder.encode(`event: ${event}\n${named}data: ${JSON.stringify(data ?? null)}\n\n`); +} + +/** + * A fault after the first byte never reaches the pipeline's `error-map` stage — the 200 has gone — + * so the stream reports it the way that stage does: a 5xx only, the route PATTERN as operation. + */ +function reportStreamFault(error: unknown, operation: string, ctx: Ctx): void { + if (factsOf(error).status < 500) return; + reportError(error, { + source: 'http', + scope: { + requestId: ctx.requestId, + traceId: ctx.traceId, + role: ctx.role, + operation, + actorId: isAnonymous(ctx.actor) ? undefined : ctx.actor.id, + }, + }); } /** Runs the invocation with `sink` receiving its chunks; resolves the output. */ @@ -40,9 +75,12 @@ export type StreamRun = (sink: ChunkSink) => Promise; export async function streamAnswer( owner: object, run: StreamRun, + operation: string, heartbeatMs: number = HEARTBEAT_MS, ): Promise { - const requestId = useContext().requestId; + // Read here, in the request's frame: the settle below runs on a later turn. + const ctx = useContext(); + const requestId = ctx.requestId; // The client leaving cancels the body; that aborts this signal, added to the request's own. const left = new AbortController(); let out: ReadableStreamDefaultController | undefined; @@ -77,8 +115,11 @@ export async function streamAnswer( } }; settled.then( - (output) => finish(sseFrame('done', output)), - (error: unknown) => finish(sseFrame('error', toProblem(error, { requestId }))), + (output) => finish(sseFrame('done', output, wireDatePaths(output))), + (error: unknown) => { + reportStreamFault(error, operation, ctx); + finish(sseFrame('error', toProblem(error, { requestId }))); + }, ); }, cancel() { diff --git a/packages/action/src/http.ts b/packages/action/src/http.ts index cd221f401..504012260 100644 --- a/packages/action/src/http.ts +++ b/packages/action/src/http.ts @@ -22,7 +22,7 @@ import { writeDigest, } from '@ultimat3/core'; import type { Route, RouteMeta, UltimateRequest } from '@ultimat3/http'; -import { jsonResponse, publishRateLimit, redirect, takeRedirect } from '@ultimat3/http'; +import { publishRateLimit, redirect, takeRedirect } from '@ultimat3/http'; import { admitsAnonymous, policyCapability, policyPermissions } from '@ultimat3/policy'; import type { ActionRateLimit, AnyAction } from './action'; import { withChunkSink } from './action-stream'; @@ -43,7 +43,7 @@ import { import { answerNatively, isNativeFormPost } from './native-answer'; import { withDeclaredErrors } from './openapi-errors'; import { assertActionRateLimit, fixedRateLimit } from './rate-limit-gate'; -import { carriesRecords, recordResponse } from './record-wire'; +import { carriesRecords, plainResponse, recordResponse } from './record-wire'; import { assertReplayPrincipal, REPLAY_REFUSAL } from './replay-scope'; /** The digest a request's idempotency key names its write by; none for a missing or blank one. */ @@ -153,7 +153,9 @@ function projectRoute( ); // The same invocation, its chunks sent as they are yielded: one route, chosen by `accept`. if (streams && wantsEventStream(req.header('accept'))) { - return streamAnswer(def, (sink) => withChunkSink(sink, call)); + // The route PATTERN, as the `error-map` stage names a fault this stream reports itself. + const operation = `${req.ctx.method} ${req.ctx.route?.path ?? path}`; + return streamAnswer(def, (sink) => withChunkSink(sink, call), operation); } // A browser's own form, to an action that declared where it lands: a 303 and a flash, the // refusal included. Everything above — the policy, the idempotency, the write — is the same. @@ -174,7 +176,7 @@ function projectRoute( ? redirect(to.location, to.status) : enveloped ? recordResponse(target.output, result) - : jsonResponse(result); + : plainResponse(result); if (key !== null) response.headers.set(REPLAYED_HEADER, replayed ? '1' : '0'); return response; }; diff --git a/packages/action/src/idempotency-memory-tx.test.ts b/packages/action/src/idempotency-memory-tx.test.ts new file mode 100644 index 000000000..ca43f06b2 --- /dev/null +++ b/packages/action/src/idempotency-memory-tx.test.ts @@ -0,0 +1,55 @@ +// The memory store's settle inside a MEMORY transaction, as inside a SQL one: settled BY the +// commit, so a rollback leaves the record in flight rather than replaying a success for rows the +// memory store never kept. A scope that has already ended is no transaction — the settle is its own. + +import { describe, expect, test } from 'bun:test'; +import { memoryTransactor } from '@ultimat3/entity'; +import { memoryIdempotencyStore } from './idempotency-memory'; + +const KEY = '["chargeCard","user","u1",null,"k1"]'; +const ROLL_BACK = new TypeError('roll it back'); + +const statusOf = async (store: ReturnType) => + (await store.get(KEY))?.status; + +describe('a memory store settle inside a memory transaction', () => { + test('a settle inside a rolled-back memory transaction leaves the record in flight', async () => { + const store = memoryIdempotencyStore(); + const thrown = await memoryTransactor() + .run(async () => { + const { record } = await store.reserve(KEY, 'h'); + await store.settle(KEY, { charged: 'ch_1' }, record.id, false); + throw ROLL_BACK; + }) + .catch((error: unknown) => error); + expect(thrown).toBe(ROLL_BACK); + expect(await statusOf(store)).toBe('in-flight'); + }); + + test('a settle inside a committed memory transaction lands with the commit', async () => { + const store = memoryIdempotencyStore(); + let during: string | undefined; + await memoryTransactor().run(async () => { + const { record } = await store.reserve(KEY, 'h'); + await store.settle(KEY, { charged: 'ch_1' }, record.id, false); + during = await statusOf(store); + }); + expect(during).toBe('in-flight'); + expect(await statusOf(store)).toBe('settled'); + }); + + test('a settle on a scope that already ended settles as its own unit of work', async () => { + const store = memoryIdempotencyStore(); + let late: Promise | undefined; + await memoryTransactor().run(async () => { + const { record } = await store.reserve(KEY, 'h'); + // Not awaited inside: it runs after the root committed, still on the scope's async chain. + late = Promise.resolve().then(async () => { + await new Promise((resolve) => setTimeout(resolve, 1)); + await store.settle(KEY, { charged: 'ch_1' }, record.id, false); + }); + }); + await late; + expect(await statusOf(store)).toBe('settled'); + }); +}); diff --git a/packages/action/src/idempotency-memory.ts b/packages/action/src/idempotency-memory.ts index 2f7df2ada..e10e1df71 100644 --- a/packages/action/src/idempotency-memory.ts +++ b/packages/action/src/idempotency-memory.ts @@ -13,7 +13,7 @@ import type { IdempotencyStore, } from './idempotency'; import { requestDeadlineMs } from './request-deadline'; -import { liveTransaction } from './tx-scope'; +import { settleScope } from './tx-scope'; /** * How long a key is remembered. A day is the window every payment API this shape exists to serve @@ -118,7 +118,7 @@ export class MemoryIdempotencyStore implements IdempotencyStore { createdAt: nowMs, }; this.#records.set(key, record); - this.#flights.set(record, { bound: liveTransaction() !== undefined, settling: false }); + this.#flights.set(record, { bound: settleScope() !== undefined, settling: false }); this.#maintain(nowMs); return Promise.resolve({ record, created: true }); } @@ -158,15 +158,15 @@ export class MemoryIdempotencyStore implements IdempotencyStore { value, ...(redacted ? { redacted: true } : {}), }); - const tx = liveTransaction(); + const tx = settleScope(); if (tx === undefined) { if (existing !== undefined) this.#records.set(key, settled(existing)); else fenced(key, reservationId, 'settle'); return Promise.resolve(); } - // Inside a transaction the record is settled BY the commit, as the Postgres store's is: a - // rollback leaves it in flight rather than replaying a success for rows nobody stored. And a - // settle that lost its reservation is thrown, because nothing has committed yet and the throw + // Inside a transaction — SQL or memory — the record is settled BY the commit, as the Postgres + // store's is: a rollback leaves it in flight rather than replaying a success for rows nobody + // stored. And a settle that lost its reservation is thrown, because nothing has committed yet and the throw // is what rolls this attempt back beside the retry that replaced it. if (existing === undefined) { return Promise.reject(new IdempotencyReservationLostError(key)); diff --git a/packages/action/src/idempotency-undefined.test.ts b/packages/action/src/idempotency-undefined.test.ts new file mode 100644 index 000000000..e5fbd2ae8 --- /dev/null +++ b/packages/action/src/idempotency-undefined.test.ts @@ -0,0 +1,63 @@ +// An action whose output is `undefined`, retried under a key. A store that keeps the answer as JSON +// (the Postgres store, `JSON.stringify(value ?? null)`) hands a replay back `null` — JSON has no +// `undefined` — and the output schema that accepted the first answer refused its replay. + +import { describe, expect, test } from 'bun:test'; +import { ctxOf, userActor } from '@ultimat3/core'; +import { allow } from '@ultimat3/policy'; +import { t } from '@ultimat3/schema'; +import { action } from './action'; +import type { IdempotencyStore } from './idempotency'; +import { memoryIdempotencyStore } from './idempotency-memory'; +import { invoke } from './invoke'; + +/** The memory store with the Postgres store's resting form: the answer as JSON, `undefined` null. */ +function jsonStore(): IdempotencyStore { + const inner = memoryIdempotencyStore(); + return { + scope: inner.scope, + keepsRedaction: true, + reserve: (key, hash) => inner.reserve(key, hash), + settle: (key, value, id, redacted) => + inner.settle(key, JSON.parse(JSON.stringify(value ?? null)) as unknown, id, redacted), + fail: (key, failure, id) => inner.fail(key, failure, id), + release: (key, id) => inner.release(key, id), + get: (key) => inner.get(key), + }; +} + +let runs = 0; +const touch = (output: Parameters[0]['output']) => + action({ + input: t.object({ id: t.string }), + output, + policy: allow(), + idempotent: true, + handle: () => { + runs += 1; + return undefined; + }, + }).named('touchDoc'); + +const options = (store: IdempotencyStore) => + ({ ctx: ctxOf({ actor: userActor({ id: 'u1' }) }), store, idempotencyKey: 'K' }) as const; + +describe('an undefined answer, replayed from a JSON store', () => { + test('an undefined answer replays as undefined', async () => { + runs = 0; + const target = touch(t.object({ ok: t.boolean }).optional()); + const store = jsonStore(); + expect(await invoke(target, { id: 'd1' }, options(store))).toBeUndefined(); + expect(await invoke(target, { id: 'd1' }, options(store))).toBeUndefined(); + expect(runs).toBe(1); + }); + + test('a schema that accepts null still replays the stored null', async () => { + runs = 0; + const target = touch(t.object({ ok: t.boolean }).nullable().optional()); + const store = jsonStore(); + await invoke(target, { id: 'd1' }, options(store)); + expect(await invoke(target, { id: 'd1' }, options(store))).toBeNull(); + expect(runs).toBe(1); + }); +}); diff --git a/packages/action/src/invoke.ts b/packages/action/src/invoke.ts index 2ffd8662d..7cd924e83 100644 --- a/packages/action/src/invoke.ts +++ b/packages/action/src/invoke.ts @@ -50,7 +50,12 @@ import { idempotencyKeyFor } from './idempotency-key'; import { drawMeter } from './meter-gate'; import { guardAction, guardActionBeforeInput } from './policy-gate'; import { spendActionLimit, withCallerAddress, withJobFrame } from './rate-limit-gate'; -import { parseActionInput, parsedOrNothing, validateOutput } from './validate'; +import { + parseActionInput, + parsedOrNothing, + validateOutput, + validateReplayedOutput, +} from './validate'; /** * Private on purpose. `@ultimat3/action` exports no way to read this back, which @@ -403,8 +408,11 @@ async function perform( trace.replayed = outcome.replayed; // A replay is parsed like a first call. The memory store hands back the live value and the // postgres store `JSON.parse(JSON.stringify(v))` — a `Date` on the first call and a `string` - // on every retry served from Postgres — so the output schema is the one answer to its shape. - return outcome.replayed ? validateOutput(def.output, outcome.value, name) : outcome.value; + // on every retry served from Postgres — so the output schema is the one answer to its shape, + // and a stored `null` it refuses is the `undefined` JSON could not keep. + return outcome.replayed + ? validateReplayedOutput(def.output, outcome.value, name) + : outcome.value; } finally { // Only for a handler that actually started, and only through the gate. A replay ran no handler // and changed nothing the first call had not already busted — re-busting per retry re-purges diff --git a/packages/action/src/record-wire.ts b/packages/action/src/record-wire.ts index 273c02733..9dd284b6f 100644 --- a/packages/action/src/record-wire.ts +++ b/packages/action/src/record-wire.ts @@ -1,10 +1,10 @@ /** - * The record envelope, on the action's HTTP projection only. Derived from the output schema — an - * action whose output references an entity row answers `{ data, records }` under - * `x-ultimate-records: 1`; every other action's body is byte-identical to what it always was. + * The action's 200 on the HTTP projection. Derived from the output schema — an action whose output + * references an entity row answers `{ data, records }` under `x-ultimate-records: 1`; every other + * action's body is byte-identical to what it always was. Either names its instants by path. */ -import { encodeRecordEnvelope, RECORDS_HEADER } from '@ultimat3/core'; +import { DATES_HEADER, encodeRecordEnvelope, RECORDS_HEADER, wireDatePaths } from '@ultimat3/core'; import { hasEntityRows, rowsOf } from '@ultimat3/entity'; import { jsonResponse } from '@ultimat3/http'; import type { StandardSchemaV1 } from '@ultimat3/schema'; @@ -24,9 +24,27 @@ export function carriesRecords(output: StandardSchemaV1): boolean { return hasEntityRows(output); } -/** The 200 for an action that carries records: the envelope, and the header that names it. */ +/** + * The output's instants — `@ultimat3/core`'s `wire-dates.ts`, the rule `@ultimat3/query`'s + * `record-answer.ts` follows — so the typed client hands back the `Date` the output type promises. + * A header, never the body: an old client reads the ISO string it always read. + */ +function datesOf(result: unknown): { readonly headers: Record } { + const dates = wireDatePaths(result); + return { headers: dates === undefined ? {} : { [DATES_HEADER]: dates } }; +} + +/** The 200 for an action that carries no records: the output itself. */ +export function plainResponse(result: unknown): Response { + return jsonResponse(result, datesOf(result)); +} + +/** + * The 200 for an action that carries records: the envelope, and the header that names it. The + * paths are the DATA's, as on a read: the client revives the envelope's `data`, never `records`. + */ export function recordResponse(output: StandardSchemaV1, result: unknown): Response { - const response = jsonResponse(encodeRecordEnvelope(result, rowsOf(output, result))); - response.headers.set(RECORDS_HEADER, ENVELOPED); - return response; + return jsonResponse(encodeRecordEnvelope(result, rowsOf(output, result)), { + headers: { [RECORDS_HEADER]: ENVELOPED, ...datesOf(result).headers }, + }); } diff --git a/packages/action/src/tx-scope.ts b/packages/action/src/tx-scope.ts index c456da59e..26ed720aa 100644 --- a/packages/action/src/tx-scope.ts +++ b/packages/action/src/tx-scope.ts @@ -6,7 +6,7 @@ // Type-only: `idempotency-postgres.ts` imports this module, and a runtime edge would be a cycle. import type { PgExecutor } from '@ultimat3/core'; -import { storeMode } from '@ultimat3/core'; +import { isUltimateError, storeMode } from '@ultimat3/core'; import { completeTransaction, currentTx, @@ -82,6 +82,38 @@ export function liveTransaction(): LiveTransaction | undefined { }; } +/** The half of an open transaction a settle bound to it needs: its commit and its rollback. */ +export type SettleScope = Pick; + +/** + * The OPEN transaction a settle rides — the SQL one (`liveTransaction`), else the open MEMORY one, + * the answer `openCommitScope` gives the bust. `undefined` outside both and for an ended scope, so + * a settle the body forgot to await is its own unit of work on either store, never a dropped one. + */ +export function settleScope(): SettleScope | undefined { + const sql = liveTransaction(); + if (sql !== undefined) return sql; + const memory = memoryJournal(); + const onCommit = memory?.onCommit?.bind(memory); + if (memory === undefined || onCommit === undefined || !memoryOpen(memory)) return undefined; + return { onCommit, onRollback: (undo) => memory.onRollback(undo) }; +} + +/** + * Whether the memory transaction is still open. `@ultimat3/entity` exports no outcome, and its + * `onRollback` is the one call that refuses an ended scope (`X_DB_TRANSACTION_CLOSED`), so a no-op + * undo asks it: open, the undo is kept and does nothing; ended, the refusal is the answer. + */ +function memoryOpen(memory: { onRollback(undo: () => void): void }): boolean { + try { + memory.onRollback(() => undefined); + return true; + } catch (error) { + if (isUltimateError(error) && error.code === 'X_DB_TRANSACTION_CLOSED') return false; + throw error; + } +} + /** * Thrown inside the scope only to end it, and caught right outside: the one way a `withTransaction` * body asks for ROLLBACK. Never an `UltimateError`, because nothing but `inRolledBackScope` ever diff --git a/packages/action/src/validate.ts b/packages/action/src/validate.ts index c16cd7704..6fb0893e8 100644 --- a/packages/action/src/validate.ts +++ b/packages/action/src/validate.ts @@ -65,3 +65,23 @@ export async function validateOutput( } return result.value; } + +/** + * A REPLAYED answer's parse. JSON has no `undefined`, so a store that keeps the answer as JSON (the + * Postgres store) hands back `null` for a handler that returned nothing — and an output schema + * that accepted `undefined` refused its own replay. A stored `null` the schema refuses is read as + * the `undefined` it stood for, when the schema takes that; any other refusal is the first one. + */ +export async function validateReplayedOutput( + schema: S, + stored: unknown, + actionName: string, +): Promise> { + const result = await validateAsync(schema, stored); + if (result.issues === undefined) return result.value; + if (stored === null) { + const absent = await validateAsync(schema, undefined); + if (absent.issues === undefined) return absent.value; + } + throw new OutputInvalidError(actionName, formatIssues(result.issues).join('; ')); +} diff --git a/packages/ai/src/wire.ts b/packages/ai/src/wire.ts index 2d46cdcff..f79cffb3e 100644 --- a/packages/ai/src/wire.ts +++ b/packages/ai/src/wire.ts @@ -223,8 +223,8 @@ export class MessageStream { toolCalls: [...this.toolCalls], malformed: [...this.malformed], // A refusal detail is a refusal whatever the stop reason says. `parseStopReason` answers - // `end_turn` for a spelling this build has never seen, and every consumer branches on the - // REASON, so the pair would read as a complete answer that happens to be empty. + // `max_tokens` for a spelling this build has never seen, and every consumer branches on the + // REASON, so the pair would read as a cut-off answer to continue rather than a refusal. stopReason: this.stopDetails === undefined ? this.stopReason : 'refusal', stopDetails: this.stopDetails, usage: this.usage, diff --git a/packages/auth/CLAUDE.md b/packages/auth/CLAUDE.md index 93d5ae0b2..e1a142388 100644 --- a/packages/auth/CLAUDE.md +++ b/packages/auth/CLAUDE.md @@ -99,6 +99,9 @@ A rule marked `†` has its full text in [`docs/history/auth-rules.md`](../../do (`link: 'verified-email'`, default; `'never'` is the only other value). - **One sign-in route implementation** (`identity-provider-route-core.ts`) at `/auth/sso/:provider[/callback]` (the callback movable only by `callbackPath`); failure is coded JSON, success a 303 to `successPath`. † +- **A built-in callback hands `X_MFA_REQUIRED` on by `mfaPath` only**: 303 + the challenge in + `__Host-x_mfa` (`mfa-handoff.ts`), read by `readMfaChallenge(request)`. Never a URL, body or log + line. No `mfaPath` → 401 with the `mfaPath` fix; a non-local path is `X_CONFIG_INVALID`. - Refresh is **not implemented**, so the framework **stores no provider token**: `accountFor` (`oauth-login.ts`) writes `accessToken: null, refreshToken: null`. The columns and `AuthAccount` fields stay; an app that stores tokens implements `linkAccount` itself. @@ -189,6 +192,7 @@ A rule marked `†` has its full text in [`docs/history/auth-rules.md`](../../do | `revocation.ts` | per-user, per-org and before-an-instant sweeps; `disableUser` (sessions and api keys) | | `member-invite.ts` / `member-invite-marks.ts` | `defineMemberInvite`: a verification purpose keyed on (tenant, address), accept into `orgId` via `updatePrivileges`; revoke = link, plus membership + sessions only where a `joined` mark proves an invite granted it. The `joined`/`revoked` marks make a racing revoke win without a transaction | | `mfa-challenge.ts` | the sealed challenge `X_MFA_REQUIRED` carries, and `completeMfa` | +| `mfa-handoff.ts` | `mfaPath`: the challenge from a built-in callback to the app's page — path check, `__Host-x_mfa` cookie, reader | | `mfa-replay-postgres.ts` | the shared replay guard: the claim and the sweep. Its DDL is in `tables.ts` | | `mfa-secret.ts` | the TOTP secret at rest: seal on write, open on read, the one-shot that seals older rows | | `directory.ts` | `describeUser` (allow-list projection), `listOrgUsers`, external-id lookup | diff --git a/packages/auth/README.md b/packages/auth/README.md index 1baa2bb26..55e9be9a4 100644 --- a/packages/auth/README.md +++ b/packages/auth/README.md @@ -566,6 +566,43 @@ export const secondFactor = (challenge: string, code: string, ip: string) => completeMfa(auth, challenge, code, { ip }); // what `login()` answers: actor, session, cookie ``` +**The built-in sign-in routes carry it for you: `mfaPath`, `As of 2026-11`.** `oauthLogin(auth)` +and `identityProviderRoutes(auth, …)` own the callback, so there is no handler of yours to catch +`X_MFA_REQUIRED` in. Give them the path of your second-factor page: + +```ts +import { + type Auth, + clearMfaChallengeCookie, + completeMfa, + oauthLogin, + readMfaChallenge, +} from '@ultimat3/auth'; + +declare const auth: Auth; + +export const sso = oauthLogin(auth, { successPath: '/app', mfaPath: '/sign-in/mfa' }); + +/** The POST behind `/sign-in/mfa`: the challenge arrives in the cookie the callback set. */ +export async function finishSso(request: Request, code: string): Promise { + const result = await completeMfa(auth, readMfaChallenge(request) ?? '', code); + const headers = new Headers({ location: '/app' }); + headers.append('set-cookie', result.cookie); + headers.append('set-cookie', clearMfaChallengeCookie()); + return new Response(null, { status: 303, headers }); +} +``` + +| `mfaPath` | An enrolled user's callback (OIDC redirect or SAML ACS) answers | +|---|---| +| set | `303` to `mfaPath`, `Set-Cookie: __Host-x_mfa=` — `HttpOnly; Secure; Path=/; SameSite=Lax; Max-Age=300` — and the state cookie cleared. No session yet | +| omitted | `401 X_MFA_REQUIRED`, no challenge anywhere; the `auth..refused` log line's `fix` is the `mfaPath` call above. That user cannot finish through these routes | +| not one normalised absolute path on this origin (`//host`, a scheme, `?`, `#`, `\`, `..`) | `X_CONFIG_INVALID`, at the call | + +The challenge travels in that cookie and nowhere else: never the redirect URL, a response body or a +log line. An absent or stale cookie is `readMfaChallenge(request) === null`, and `completeMfa` +refuses it like any other bad challenge. + | `completeMfa` is given | Answer | |---|---| | a live challenge and the current code, or an unused recovery code | `{ actor, session, token, cookie }`, `mfaSatisfied: true` | @@ -927,6 +964,7 @@ export const runtime: NonNullable = { |---|---|---| | path | `/auth/sso/:provider` | `/auth/sso/:provider/callback` | | success | `302` to the provider, `Set-Cookie: __Host-x_sso_` | `303` to `successPath`, `Set-Cookie: __Host-x_session` **and** the handshake cleared | +| second factor owed | — | `303` to `mfaPath`, `Set-Cookie: __Host-x_mfa`, handshake cleared; with no `mfaPath`, `401 X_MFA_REQUIRED` ([MFA](#mfa--totp-and-recovery-codes)) | | failure | coded JSON, status per code: `code` + `title` + `docs`, one fixed `cause`, `fix: x errors explain --json` | the same, handshake cleared either way | A **descriptor**, never a mounted handler — the same category as `mcpHttpRoute()`. `@ultimat3/http` diff --git a/packages/auth/src/grant-authorization-code.test.ts b/packages/auth/src/grant-authorization-code.test.ts index 75de6fe9f..76aa29c71 100644 --- a/packages/auth/src/grant-authorization-code.test.ts +++ b/packages/auth/src/grant-authorization-code.test.ts @@ -9,6 +9,7 @@ import { REDIRECT, type ServerFixture, serverFixture, + tokensFor, } from './authorization-server-fixture'; const redeem = ( @@ -77,3 +78,47 @@ describe('authorization-code grant · a refused request does not burn the code', expect(await fixture.server.resolve(String(real.body['access_token']))).toBeNull(); }); }); + +describe('refresh grant · a retired token is a replay only from the client it was issued to', () => { + const refresh = (fixture: ServerFixture, token: string, clientId: string) => + post(fixture.server, '/oauth/token', { + grant_type: 'refresh_token', + refresh_token: token, + client_id: clientId, + }); + + test('a retired refresh token presented by another client revokes nothing', async () => { + const fixture = await serverFixture(); + const { client: other } = await fixture.server.registerClient({ + name: 'Other app', + redirectUris: [REDIRECT], + grantTypes: ['authorization_code', 'refresh_token'], + scopes: ['read'], + }); + const first = await tokensFor(fixture); + const retired = String(first.body['refresh_token']); + const rotated = await refresh(fixture, retired, fixture.client.clientId); + expect(rotated.status).toBe(200); + + const foreign = await refresh(fixture, retired, other.clientId); + expect(foreign.body['error']).toBe('invalid_grant'); + expect(await fixture.server.resolve(String(rotated.body['access_token']))).not.toBeNull(); + const next = await refresh( + fixture, + String(rotated.body['refresh_token']), + fixture.client.clientId, + ); + expect(next.status).toBe(200); + }); + + test('the same retired token from its own client still revokes the grant', async () => { + const fixture = await serverFixture(); + const first = await tokensFor(fixture); + const retired = String(first.body['refresh_token']); + const rotated = await refresh(fixture, retired, fixture.client.clientId); + expect((await refresh(fixture, retired, fixture.client.clientId)).body['error']).toBe( + 'invalid_grant', + ); + expect(await fixture.server.resolve(String(rotated.body['access_token']))).toBeNull(); + }); +}); diff --git a/packages/auth/src/grant-authorization-code.ts b/packages/auth/src/grant-authorization-code.ts index 96e15fb87..be0b86211 100644 --- a/packages/auth/src/grant-authorization-code.ts +++ b/packages/auth/src/grant-authorization-code.ts @@ -79,11 +79,15 @@ export async function exchangeRefresh( const token = await config.store.getToken(hash); if (token === null || token.kind !== 'refresh') return invalidGrant('the refresh token is unknown'); - if (token.retiredAt !== null) return replayed(config, token.grantId, client.clientId); const grant = await config.store.getGrant(token.grantId); + // Asked BEFORE the replay branch: a retired token is a replay only from the client it was issued + // to. Presented by any other client it would otherwise revoke a grant that client never held. + const foreign = grant !== null && grant.clientId !== client.clientId; + if (token.retiredAt !== null && !foreign) { + return replayed(config, token.grantId, client.clientId); + } if (grant === null || grant.revokedAt !== null) return invalidGrant('the grant is revoked'); - if (grant.clientId !== client.clientId) - return invalidGrant('the token was issued to another client'); + if (foreign) return invalidGrant('the token was issued to another client'); if (grant.refreshedAt.getTime() + config.refreshIdleMs <= now.getTime()) { return invalidGrant('the grant sat idle past its refresh window'); } diff --git a/packages/auth/src/identity-provider-route-core.ts b/packages/auth/src/identity-provider-route-core.ts index 76877866c..56e5be368 100644 --- a/packages/auth/src/identity-provider-route-core.ts +++ b/packages/auth/src/identity-provider-route-core.ts @@ -23,6 +23,13 @@ import { readIdentityState, } from './identity-provider-cookie'; import { oauthRouteStatus } from './identity-provider-status'; +import { + mfaChallengeCookie, + mfaChallengeOf, + mfaHandoffMissing, + mfaLandingPath, + type SignInFactory, +} from './mfa-handoff'; import { oauthStateInvalid } from './oauth-errors'; import type { OAuthGrants } from './oauth-login'; import { OAUTH_START_ROUTE_PATH } from './oauth-paths'; @@ -66,6 +73,14 @@ export interface SignInRouteOptions { readonly secret?: string | undefined; /** A fixed landing path, never `?next=`: `nextAfterSignIn` in `@ultimat3/http` is the one check. */ readonly successPath?: string | undefined; + /** + * The app's own second-factor page. A user with TOTP enrolled is sent there (303) instead of to + * `successPath`, with the sealed challenge in the `__Host-x_mfa` cookie — HttpOnly, and living + * `MFA_CHALLENGE_TTL_MS`: `completeMfa(auth, readMfaChallenge(request) ?? '', code)` finishes. + * Omit it and that user's callback is refused `X_MFA_REQUIRED` (401): they cannot finish here. + * One absolute path on this origin, or `X_CONFIG_INVALID` at the call. + */ + readonly mfaPath?: string | undefined; /** The client address recorded on the session; `@ultimat3/http` knows the proxy chain. */ readonly clientIp?: ((request: Request) => string | null | undefined) | undefined; readonly env?: Readonly> | undefined; @@ -79,6 +94,8 @@ export interface SignInRoutePolicy { unknown(segment: string): UltimateError; /** `auth.sso` / `auth.oauth`: the log event prefix (`.refused`). */ readonly event: string; + /** The call an operator edits: what a `fix:` line about these routes' options names. */ + readonly factory: SignInFactory; readonly names: { readonly start: string; readonly callback: string; readonly acs: string }; /** A throw with no code, logged and turned into the refusal served. Its text never is. */ uncoded(error: unknown): UltimateError; @@ -170,6 +187,8 @@ export function signInRoutes( policy: SignInRoutePolicy, ): SignInRoutes { const back = policy.callbackPath ?? callbackPath(); + const mfaPath = + options.mfaPath === undefined ? undefined : mfaLandingPath(policy.factory, options.mfaPath); const seal = { clock: auth.clock, ...(options.secret === undefined ? {} : { secret: options.secret }), @@ -230,7 +249,15 @@ export function signInRoutes( // 303: the answer may arrive as a POST, and the destination is a GET either way. return new Response(null, { status: 303, headers }); } catch (error) { - return problem(policy, error, clear); + // Identity proven, second factor owed. The challenge goes to the app's page in a cookie + // only this origin's server reads — never the URL, a body or the log line `problem` writes. + const challenge = mfaChallengeOf(error); + if (challenge === null) return problem(policy, error, clear); + if (mfaPath === undefined) return problem(policy, mfaHandoffMissing(policy.factory), clear); + const headers = new Headers({ location: mfaPath }); + headers.append('set-cookie', mfaChallengeCookie(challenge)); + for (const cookie of clear) headers.append('set-cookie', cookie); + return new Response(null, { status: 303, headers }); } }; diff --git a/packages/auth/src/identity-provider-routes.ts b/packages/auth/src/identity-provider-routes.ts index a8b008de7..0f25872f3 100644 --- a/packages/auth/src/identity-provider-routes.ts +++ b/packages/auth/src/identity-provider-routes.ts @@ -71,6 +71,7 @@ export function identityProviderRoutes( }, unknown: identityProviderUnknown, event: 'auth.sso', + factory: 'identityProviderRoutes', names: { start: 'auth.sso.start', callback: 'auth.sso.callback', acs: 'auth.sso.acs' }, uncoded, grants: (identity) => options.resolveGrants?.(identity), diff --git a/packages/auth/src/index.ts b/packages/auth/src/index.ts index 6285e5828..a5d3b9ab0 100644 --- a/packages/auth/src/index.ts +++ b/packages/auth/src/index.ts @@ -217,6 +217,7 @@ export { MFA_CHALLENGE_TTL_MS, mfaChallengeRequired, } from './mfa-challenge'; +export { clearMfaChallengeCookie, readMfaChallenge } from './mfa-handoff'; export type { PostgresTotpReplayGuard, PostgresTotpReplayGuardOptions, diff --git a/packages/auth/src/mfa-handoff.test.ts b/packages/auth/src/mfa-handoff.test.ts new file mode 100644 index 000000000..92cdcea19 --- /dev/null +++ b/packages/auth/src/mfa-handoff.test.ts @@ -0,0 +1,231 @@ +// An MFA-enrolled user through the BUILT-IN sign-in routes. The failure first: the callback caught +// `X_MFA_REQUIRED`, served a 401 that drops `meta`, and the challenge was gone — so nobody with a +// second factor could finish SSO. With `mfaPath` the challenge travels in a `__Host-` cookie, and +// the proof is that `completeMfa` accepts the one that travelled. + +import { afterEach, beforeEach, describe, expect, test } from 'bun:test'; +import { frozenClock, installLogSink } from '@ultimat3/core'; +import { type Auth, defineAuth } from './auth'; +import { oidcIdentityProvider } from './identity-provider-oidc'; +import { identityProviderRoutes } from './identity-provider-routes'; +import { type MemoryAuthAdapter, memoryAuthAdapter } from './memory-adapter'; +import { totpCode, totpStep } from './mfa'; +import { completeMfa } from './mfa-challenge'; +import { clearMfaChallengeCookie, MFA_CHALLENGE_COOKIE, readMfaChallenge } from './mfa-handoff'; +import { saveTotpSecret } from './mfa-secret'; +import type { OAuthFetch } from './oauth-exchange'; +import { credentials, json } from './oauth-login-fixture'; +import { oauthLogin } from './oauth-route'; +import { samlIdentityProvider } from './saml-provider'; +import { encodeResponse, readAuthnRequest, samlTestIdp } from './saml-test-idp'; +import { ACS_URL, SAML_NOW, SP_ENTITY_ID } from './saml-test-support-fixture'; + +const BASE = 'https://app.example.test'; +const SECRET = 's'.repeat(40); +const TOTP = 'JBSWY3DPEHPK3PXP'; +const MFA_PATH = '/sign-in/mfa'; + +const githubFetch: OAuthFetch = async (url) => { + if (url === 'https://github.com/login/oauth/access_token') + return json({ access_token: 'gho_x', token_type: 'bearer' }); + if (url === 'https://api.github.com/user') return json({ id: 583231, login: 'octocat' }); + if (url === 'https://api.github.com/user/emails') { + return json([{ email: 'octo@example.com', primary: true, verified: true }]); + } + return expect.unreachable(`unexpected endpoint: ${url}`); +}; + +let adapter: MemoryAuthAdapter; +let auth: Auth; +let logged: string[]; +let releaseLogSink: () => void; + +beforeEach(() => { + adapter = memoryAuthAdapter(); + auth = defineAuth({ adapter, clock: frozenClock(SAML_NOW), providers: ['corp', 'github'] }); + logged = []; + releaseLogSink = installLogSink((line) => { + logged.push(line); + }); +}); + +afterEach(() => { + releaseLogSink(); +}); + +/** A verified user the IdP's answer links to, with a second factor enrolled. */ +async function enrol(email: string): Promise { + const user = await adapter.createUser({ + id: '00000000-0000-7000-8000-0000000000aa', + email, + passwordHash: null, + orgId: null, + roles: [], + scopes: [], + externalId: null, + createdAt: SAML_NOW, + }); + await adapter.updateUser(user.id, { emailVerifiedAt: SAML_NOW }); + await saveTotpSecret(auth, user.id, TOTP); + return user.id; +} + +const pairOf = (setCookie: string | null | undefined): string => + (setCookie ?? '').split(';')[0] ?? ''; + +type Callback = (options: { readonly mfaPath?: string }) => Promise; + +/** The three built-in callbacks, each driven start → IdP → callback for an enrolled user. */ +const DOORS: Readonly> = { + 'oauthLogin(auth).callback': { + email: 'octo@example.com', + event: 'auth.oauth.refused', + async call(options) { + const routes = oauthLogin(auth, { + credentials, + fetch: githubFetch, + secret: SECRET, + baseUrl: BASE, + ...options, + }); + const out = await routes.start.handle(new Request(`${BASE}/auth/sso/github`)); + const state = new URL(out.headers.get('location') ?? '').searchParams.get('state') ?? ''; + return routes.callback.handle( + new Request(`${BASE}/auth/sso/github/callback?state=${state}&code=c0de`, { + headers: { cookie: pairOf(out.headers.get('set-cookie')) }, + }), + ); + }, + }, + 'identityProviderRoutes OIDC callback': { + email: 'octo@example.com', + event: 'auth.sso.refused', + async call(options) { + const github = oidcIdentityProvider({ provider: 'github', credentials, fetch: githubFetch }); + const routes = identityProviderRoutes(auth, { + providers: [github], + baseUrl: BASE, + secret: SECRET, + ...options, + }); + const out = await routes.start.handle(new Request(`${BASE}/auth/sso/github`)); + const state = new URL(out.headers.get('location') ?? '').searchParams.get('state') ?? ''; + return routes.callback.handle( + new Request(`${BASE}/auth/sso/github/callback?state=${state}&code=c0de`, { + headers: { cookie: pairOf(out.headers.get('set-cookie')) }, + }), + ); + }, + }, + 'identityProviderRoutes SAML ACS': { + email: 'ada@corp.example', + event: 'auth.sso.refused', + async call(options) { + const idp = await samlTestIdp(); + const corp = samlIdentityProvider({ + id: 'corp', + idp: idp.idp, + spEntityId: SP_ENTITY_ID, + trustEmail: true, + emailDomains: ['corp.example'], + }); + const routes = identityProviderRoutes(auth, { + providers: [corp], + baseUrl: BASE, + secret: SECRET, + ...options, + }); + const out = await routes.start.handle(new Request(`${BASE}/auth/sso/corp`)); + const request = readAuthnRequest(out.headers.get('location') ?? ''); + const xml = await idp.responseXml({ + requestId: request.id, + acsUrl: ACS_URL, + audience: SP_ENTITY_ID, + now: SAML_NOW, + }); + return routes.acs.handle( + new Request(`${BASE}/auth/sso/corp/callback`, { + method: 'POST', + headers: { + cookie: pairOf(out.headers.get('set-cookie')), + 'content-type': 'application/x-www-form-urlencoded', + }, + body: new URLSearchParams({ + SAMLResponse: encodeResponse(xml), + RelayState: request.relayState, + }), + }), + ); + }, + }, +}; + +for (const [door, { email, event, call }] of Object.entries(DOORS)) { + describe(`${door}: an MFA-enrolled user`, () => { + test("an MFA-enrolled user's callback hands over a challenge completeMfa accepts", async () => { + const userId = await enrol(email); + const answer = await call({ mfaPath: MFA_PATH }); + + expect(answer.status).toBe(303); + expect(answer.headers.get('location')).toBe(MFA_PATH); + const cookies = answer.headers.getSetCookie(); + expect(cookies.some((c) => c.startsWith('__Host-x_session='))).toBe(false); + // The spent state cookie is still cleared: the IdP's answer was this browser's. + expect(cookies.some((c) => c.startsWith('__Host-x_sso_'))).toBe(true); + const set = cookies.find((c) => c.startsWith(`${MFA_CHALLENGE_COOKIE}=`)) ?? ''; + for (const attribute of ['HttpOnly', 'Secure', 'Path=/', 'SameSite=Lax', 'Max-Age=300']) { + expect(set).toContain(attribute); + } + expect(set).not.toContain('Domain='); + + // The app's page, on the next request: the cookie is all it needs. + const next = new Request(`${BASE}${MFA_PATH}`, { headers: { cookie: pairOf(set) } }); + const challenge = readMfaChallenge(next) ?? ''; + const result = await completeMfa(auth, challenge, totpCode(TOTP, totpStep(SAML_NOW))); + expect(result.session.userId).toBe(userId); + expect(result.session.mfaSatisfied).toBe(true); + + // Nowhere another origin or a log reads: not the URL, not a body, not a log line. + expect(await answer.text()).toBe(''); + expect(logged.join('\n')).not.toContain(challenge); + }); + + test('with no mfaPath the refusal is the old 401, and its fix names the option', async () => { + await enrol(email); + const answer = await call({}); + + expect(answer.status).toBe(401); + const cookies = answer.headers.getSetCookie(); + expect(cookies.some((c) => c.startsWith(MFA_CHALLENGE_COOKIE))).toBe(false); + expect(cookies.some((c) => c.startsWith('__Host-x_session='))).toBe(false); + const body = (await answer.json()) as { code: string; fix: string }; + expect(body.code).toBe('X_MFA_REQUIRED'); + expect(body.fix).toBe('x errors explain X_MFA_REQUIRED --json'); + const line = logged.findLast((entry) => entry.includes(event)) ?? ''; + expect(line).toContain("mfaPath: '/sign-in/mfa'"); + expect(line).toContain('readMfaChallenge(request)'); + // The fix a hand-written handler gets is a lie here: there is no handler to catch it in. + expect(line).not.toContain('catch X_MFA_REQUIRED in your sign-in handler'); + }); + }); +} + +describe('mfaPath is a path on this origin, or the call refuses', () => { + const HOSTILE = ['//evil.example/mfa', 'https://evil.example/mfa', '/\\evil.example', 'mfa']; + + test.each([...HOSTILE, '/a/../b', '/mfa?next=x', '/mfa#x'])('%s', (mfaPath) => { + expect(() => oauthLogin(auth, { mfaPath })).toThrow( + expect.objectContaining({ code: 'X_CONFIG_INVALID' }), + ); + expect(() => identityProviderRoutes(auth, { providers: [], mfaPath })).toThrow( + expect.objectContaining({ code: 'X_CONFIG_INVALID' }), + ); + }); + + test('the cookie is cleared by the one helper that names it', () => { + const cleared = clearMfaChallengeCookie(); + expect(cleared).toStartWith(`${MFA_CHALLENGE_COOKIE}=;`); + expect(cleared).toContain('Max-Age=0'); + expect(readMfaChallenge(new Request(BASE))).toBeNull(); + }); +}); diff --git a/packages/auth/src/mfa-handoff.ts b/packages/auth/src/mfa-handoff.ts new file mode 100644 index 000000000..fc0abab07 --- /dev/null +++ b/packages/auth/src/mfa-handoff.ts @@ -0,0 +1,86 @@ +// Single responsibility: how the built-in sign-in routes hand an `X_MFA_REQUIRED` challenge to the +// app's own second-factor page — the `mfaPath` they redirect to, the one cookie the challenge rides +// in, and its reader. A cookie and never the URL or a body: a URL is in a log, a history and a +// `Referer`; `__Host-` + `HttpOnly` is read by this origin's server and nothing else. + +import { + ConfigInvalidError, + isUltimateError, + readCookie, + renderCauseValue, + serializeSetCookie, +} from '@ultimat3/core'; +import { AuthError } from './errors'; +import { MFA_CHALLENGE_TTL_MS } from './mfa-challenge'; +import type { RequestLike } from './session'; + +/** `__Host-`: Secure, `Path=/`, no `Domain` — a sibling subdomain can neither read nor plant it. */ +export const MFA_CHALLENGE_COOKIE = '__Host-x_mfa'; + +/** The sign-in front door a `fix:` line names: the call an operator edits. */ +export type SignInFactory = 'oauthLogin' | 'identityProviderRoutes'; + +const CALL: Readonly> = { + oauthLogin: "oauthLogin(auth, { mfaPath: '/sign-in/mfa' })", + identityProviderRoutes: "identityProviderRoutes(auth, { providers, mfaPath: '/sign-in/mfa' })", +}; + +const PAGE = + "on that page: completeMfa(auth, readMfaChallenge(request) ?? '', code), then send result.cookie and clearMfaChallengeCookie()"; + +/** + * `mfaPath`, refused at the call when a browser could read it as anywhere but a path on this + * origin: `//host`, `/\host` and a scheme are all "another site" to a `Location` header. + */ +export function mfaLandingPath(factory: SignInFactory, path: string): string { + const local = + typeof path === 'string' && + path.startsWith('/') && + !/[\\?#]/.test(path) && + // `//host` resolves to another origin, and its pathname is no longer the whole input. + new URL(path, 'https://x.invalid').pathname === path; + if (!local) { + throw new ConfigInvalidError({ + cause: `${factory}({ mfaPath: ${renderCauseValue(path)} }) is not a normalised absolute path on this origin, so the MFA challenge cookie would be followed by a redirect somewhere else`, + fix: `${CALL[factory]} // one absolute path: no host, query, fragment, backslash or ./.. segment`, + }); + } + return path; +} + +/** The sealed challenge of an `X_MFA_REQUIRED`, or `null` for every other throw. */ +export function mfaChallengeOf(error: unknown): string | null { + if (!isUltimateError(error) || error.code !== 'X_MFA_REQUIRED') return null; + const challenge = error.meta?.['challenge']; + return typeof challenge === 'string' && challenge !== '' ? challenge : null; +} + +/** + * What the callback is refused with when no `mfaPath` was given: the same code, with the cause and + * fix that are true for a built-in route — there is no "your sign-in handler" to catch it in — and + * WITHOUT the challenge, which has nowhere to travel and so is not kept. + */ +export const mfaHandoffMissing = (factory: SignInFactory): AuthError => + new AuthError({ + code: 'X_MFA_REQUIRED', + cause: `this account has TOTP enrolled, and ${factory}() was given no mfaPath to hand the second-factor challenge to, so the sign-in cannot finish`, + fix: `${CALL[factory]} // ${PAGE}`, + }); + +/** The challenge as a `Set-Cookie`, living exactly as long as the challenge itself. */ +export const mfaChallengeCookie = (challenge: string): string => + serializeSetCookie(MFA_CHALLENGE_COOKIE, challenge, { + maxAge: Math.floor(MFA_CHALLENGE_TTL_MS / 1000), + }); + +/** Sent with the response that finishes (or abandons) the second leg. */ +export const clearMfaChallengeCookie = (): string => + serializeSetCookie(MFA_CHALLENGE_COOKIE, '', { maxAge: 0 }); + +/** + * The challenge a built-in callback handed to `mfaPath`, or `null`: what `completeMfa` takes as its + * second argument. Unverified here on purpose — `completeMfa` opens the seal and checks the expiry. + */ +export function readMfaChallenge(request: RequestLike): string | null { + return readCookie(request.headers.get('cookie'), MFA_CHALLENGE_COOKIE); +} diff --git a/packages/auth/src/oauth-route.ts b/packages/auth/src/oauth-route.ts index 9cc2c2e4a..19883e687 100644 --- a/packages/auth/src/oauth-route.ts +++ b/packages/auth/src/oauth-route.ts @@ -70,6 +70,14 @@ export interface OAuthLoginOptions { readonly timeoutMs?: number | undefined; /** Where a signed-in browser lands. A fixed path — never read from the request. See below. */ readonly successPath?: string | undefined; + /** + * The app's own second-factor page. A user with TOTP enrolled is sent there (303) instead of to + * `successPath`, with the sealed challenge in the `__Host-x_mfa` cookie — HttpOnly, and living + * `MFA_CHALLENGE_TTL_MS`: `completeMfa(auth, readMfaChallenge(request) ?? '', code)` finishes. + * Omit it and that user's callback is refused `X_MFA_REQUIRED` (401): they cannot finish here. + * One absolute path on this origin, or `X_CONFIG_INVALID` at the call. + */ + readonly mfaPath?: string | undefined; /** Narrower scopes than the provider's defaults, when the app wants less. */ readonly scopes?: readonly string[] | undefined; /** @@ -197,6 +205,7 @@ export function oauthLogin(auth: Auth, options: OAuthLoginOptions = {}): OAuthLo }, unknown, event: 'auth.oauth', + factory: 'oauthLogin', names: { start: 'auth.oauth.start', callback: 'auth.oauth.callback', acs: 'auth.oauth.acs' }, uncoded, grants(identity) { diff --git a/packages/cache/CLAUDE.md b/packages/cache/CLAUDE.md index f94c12e41..4f92074ad 100644 --- a/packages/cache/CLAUDE.md +++ b/packages/cache/CLAUDE.md @@ -86,7 +86,8 @@ Tier 1. Tagged caching + THE invalidation graph. tier is built (`assertJitterFraction`) and again at each write. - **A rung's limits are constructor options, set through `runtime.ts`'s `cacheTiers`** (`As of 2026-11`, #1178). The boot builds `lru` and `redis` with defaults; no `app.config.ts` key exists, - because it would be a second spelling of that replacement. Every limit `fix:` names the line. + because it would be a second spelling of that replacement — save `cache.defaultTtlMs`, which the + boot passes into both rungs, so that one limit's `fix:` names it too. Every limit `fix:` names the line. - **`cacheStack` is the production read path, and `@ultimat3/query`'s `readThrough` is its caller** — it is what makes an action's `cache.invalidates` reach a `cache:` query. - **`cacheStack` shares one in-flight `load()` per key** through `@ultimat3/core`'s @@ -128,9 +129,12 @@ Tier 1. Tagged caching + THE invalidation graph. - **A bust has no script.** `readBucket` pages `ZSCAN … COUNT 1000` — never a score/offset cursor: a concurrent prune of a read tie group, or a re-write re-scoring a read tie member, shifts an offset past live keys. `ZSCAN` returns every member present for the whole scan (the fake's - `ZSCAN` keeps exactly that guarantee and nothing stronger); `unlinkAll` `UNLINK`s one key per command; `sweepBuckets` `ZREM`s only what - `Promise.allSettled` says died, 8 commands in flight, so a refused `UNLINK` stays findable for the - retry. 10k members ≤ 100 sequential round trips (`roundTrips` in the fixture counts them). + `ZSCAN` keeps exactly that guarantee and nothing stronger). **Sweep BEFORE delete** (`As of + 2026-11-19`): `sweepBuckets` `ZREM`s what was read (8 in flight, settled), then `unlinkAll` + `UNLINK`s one key per command, then `rejoinBuckets` `ZADD`s back, at its read score, every member + whose `UNLINK` was refused — into a READ bucket only if it held it. Delete-then-sweep orphaned a + fill landing between the two (`redis-ordering.test.ts`). 10k members ≤ 100 sequential round trips + (`roundTrips` in the fixture counts them). - **A `set` joins its buckets BEFORE it writes the value, and re-checks membership after**; only a literal `null` from `ZSCORE` counts as busted-in-the-air (`lostMembership`). - **Every command the tier sends names ONE key** (the lease `EVAL` included), and bucket keys carry @@ -156,7 +160,8 @@ Tier 1. Tagged caching + THE invalidation graph. `receiveInvalidationBroadcast`; `cli` CHOOSES the bus (`runtime-cache-bus.ts`). The subscriber is its own connection, and every connect unsubscribes before it subscribes (Bun keeps the old listener: a bare re-subscribe delivers twice) — `redis-pubsub.test.ts`. The inbound half cannot - re-emit (only it passes `emit: false`). An undeclared inbound tag goes to `report.errors`, never a + re-emit (only it passes `emit: false`), and **skips a shared read tier** — one with a `fence`: + the sender's bust cleared it for the fleet (`broadcast.test.ts`). The edge is still purged. An undeclared inbound tag goes to `report.errors`, never a throw. - **A `cdn` tier holding `noopPurgeDriver()` reports `skipped`, never keys** (`isNoopPurgeDriver`, in `cdn.ts`). **`report.cdn` is what depends; `report.tiers` is what cleared** — `busted` is built diff --git a/packages/cache/README.md b/packages/cache/README.md index 0b3f09352..8c070c5fe 100644 --- a/packages/cache/README.md +++ b/packages/cache/README.md @@ -292,15 +292,18 @@ pod whose clock runs ahead from pruning a member whose value key still lives. |---|---|---| | fence | `SET` per generation key (`redis-fence.ts`) | one round trip | | read | `ZSCAN … COUNT 1000` (`BUST_PAGE_SIZE`), buckets concurrently | a page per round trip; returns every member present for the whole scan, so a concurrent prune or re-score skips nothing — a score/offset cursor did | +| sweep | `ZREM` of what was read, 1,000 members per command, 8 in flight | — | | delete | `UNLINK` per value key, 1,024 per burst | `UNLINK` frees off the server's main thread | -| sweep | `ZREM` of exactly what died, 1,000 members per command, 8 in flight | — | +| re-join | `ZADD` back, at its read score, each member whose `UNLINK` was refused | only on a refusal | 10k members clear in 25 sequential round trips (≤ 100 is the test). Every command names **one key**, so a bust is slot-local on Redis Cluster and Dragonfly whatever tags it carries; `{}` is still a **Redis Cluster hash tag**, so a row's bucket, its collection's and the -index share a slot. A refused `UNLINK` keeps its membership — the bust `ZREM`s only what it -deleted, including from the index a row bust never *reads* — so the retry the error asks for still -finds it. A `set` mirrors it: buckets are joined **before** the value is written and membership is +index share a slot. **Sweep before delete** (`As of 2026-11-19`): a fill from another replica that +landed between a delete and a later sweep re-joined a member the sweep then removed — a live value +no bust could reach, stale for its whole TTL. A refused `UNLINK` is re-joined to the buckets it +left (a bucket the bust read only if it held it, so a row never joins its collection's), including +the index a row bust never *reads*, so the retry the error asks for still finds it. A `set` mirrors it: buckets are joined **before** the value is written and membership is re-checked (`ZSCORE`) after, because a bust that landed in between would otherwise leave a row nothing can reach by tag. A collection bust leaves its members in the ROW buckets it never read; the prune and the lease bound them, and a later bust's `UNLINK` of a dead key is a no-op. @@ -431,7 +434,10 @@ bus.subscribe('cache.invalidate', (wireTags) => receiveInvalidationBroadcast(wir The inbound half **cannot** re-emit, and that is structural rather than a flag: `emit` lives on the private fan-out options and `receiveInvalidationBroadcast` is the only caller that passes `false`. -A receiver that re-broadcast would be a storm bounded by nothing. A failed send lands in +A receiver that re-broadcast would be a storm bounded by nothing. Inbound, a **shared** read tier +(one with a `fence`, as `redisTier` has) is skipped, `As of 2026-11-19`: the sender's own bust +cleared it for every replica, and a second bust per replica deleted what readers had refilled since. +The in-process tiers and the edge are still cleared. A failed send lands in `report.errors` under `tier: "broadcast"` and the write that triggered the bust still succeeds. What happens to that bust is the sender's (`@ultimat3/cli` keeps the refused tags, bounded, and publishes them when the bus returns); with no such sender the other pods clear on TTL. diff --git a/packages/cache/src/broadcast.test.ts b/packages/cache/src/broadcast.test.ts index 66492d3d6..5d2698083 100644 --- a/packages/cache/src/broadcast.test.ts +++ b/packages/cache/src/broadcast.test.ts @@ -12,6 +12,7 @@ import { resetTiers, } from './invalidate'; import { lruTier } from './lru'; +import { fakeRedis, tierFor } from './redis-fake-fixture'; import { declareTags, isolateDeclaredTags, resetDeclaredTags, tag } from './tags'; // Module scope, so the baseline is whatever a neighbouring file registered before this one ran. @@ -69,6 +70,39 @@ describe('cross-instance invalidation', () => { expect(await lru.get('feed')).toBeUndefined(); }); + // The sender's own bust already cleared the shared store for the whole fleet. Re-busting it on + // every replica's receipt (the sender's included: a real bus delivers back) deleted the value a + // reader had refilled since, re-bumped the fleet fence under every fill in flight, and cost each + // mutation one extra load and a bust's worth of commands per replica. + test('an inbound broadcast clears the in-process tier and sends nothing to a shared one', async () => { + const lru = lruTier({ maxBytes: 10_000, defaultTtlMs: 3_600_000 }); + registerTier(lru); + await lru.set('feed', ['a'], { tags: [tag('post')] }); + const server = fakeRedis(); + const shared = tierFor(server); + registerTier(shared); + await shared.set('feed', ['fresh'], { tags: [tag('post', '1')] }); + server.sent.length = 0; + + const report = await receiveInvalidationBroadcast(['post:1']); + + expect(await lru.get('feed')).toBeUndefined(); + expect(server.sent).toEqual([]); + expect((await shared.get('feed'))?.value).toEqual(['fresh']); + expect(report.tiers.map((entry) => entry.tier)).toEqual(['lru']); + }); + + test('a LOCAL bust still clears the shared tier', async () => { + const server = fakeRedis(); + const shared = tierFor(server); + registerTier(shared); + await shared.set('feed', ['stale'], { tags: [tag('post', '1')] }); + + await invalidateTags([tag('post', '1')]); + + expect(await shared.get('feed')).toBeUndefined(); + }); + test('a local bust whose receiver echoes back still sends exactly once', async () => { let sends = 0; registerInvalidationBroadcast(async (wire) => { diff --git a/packages/cache/src/errors.ts b/packages/cache/src/errors.ts index d1f8ee697..6365038a5 100644 --- a/packages/cache/src/errors.ts +++ b/packages/cache/src/errors.ts @@ -70,7 +70,8 @@ export class CacheTagUnknownError extends UltimateError { /** * Where an app tunes a rung. The boot builds `lru` and `redis` with their defaults and takes a * replacement from `runtime.ts`'s `cacheTiers`: the one way, so every fix below names it. Limits - * are not `app.config.ts` keys — they would be a second spelling of that same replacement. + * are not `app.config.ts` keys — they would be a second spelling of that same replacement — save + * `cache.defaultTtlMs`, which the boot passes into the rungs it builds (`optionHome` says so). */ const RUNG_FILE = 'apps/web/runtime.ts'; @@ -151,10 +152,14 @@ const LIMIT_OWNER: Readonly> = { function optionHome(tier: string, option: string, example: string): string { // `hasOwn`: `tier` is a caller's string, and `constructor` must not read the prototype. const owner = Object.hasOwn(LIMIT_OWNER, tier) ? LIMIT_OWNER[tier] : tier; - const rung = - tier === 'lru' || tier === 'redis' - ? `; for the rung a boot builds, cacheTiers: [${owner}({ ${option}: ${example} })] in ${RUNG_FILE}` - : ''; + const built = tier === 'lru' || tier === 'redis'; + const rung = built + ? `; for the rung a boot builds, cacheTiers: [${owner}({ ${option}: ${example} })] in ${RUNG_FILE}` + : ''; + // The one limit the boot also reads from config: it hands `cache.defaultTtlMs` to both rungs. + if (built && option === 'defaultTtlMs') { + return `${owner}(...)${rung}, or cache.defaultTtlMs in app.config.ts, which the boot passes to the lru and redis rungs it builds`; + } return `${owner}(...)${rung} — a constructor option, never an app.config.ts key`; } diff --git a/packages/cache/src/invalidate.ts b/packages/cache/src/invalidate.ts index e49149594..e2745d8a9 100644 --- a/packages/cache/src/invalidate.ts +++ b/packages/cache/src/invalidate.ts @@ -206,7 +206,15 @@ function fanOut(tags: readonly CacheTag[], options: FanOutOptions): Promise !isEdgeTier(one))) { + // Inbound, a SHARED read tier is skipped: the sender's own bust cleared it for the fleet, and + // a second one per replica deletes what readers refilled since and re-fences their fills. A + // tier is shared when it keeps a fleet fence (`CacheTier.fence`, omitted in-process) — the + // positive declaration, so an app tier that says nothing is still cleared. The edge is not + // skipped: a peer's purge after its own drop is the one that holds (`purgeEdgeAgain`). + const readTiers = farthestFirst.filter( + (one) => !isEdgeTier(one) && (emit || one.fence === undefined), + ); + for (const tier of readTiers) { try { tiers.push(await tier.invalidateTags(tags)); cleared.push(tier.name); diff --git a/packages/cache/src/lru.test.ts b/packages/cache/src/lru.test.ts index 31c2e20a7..e1a35e00b 100644 --- a/packages/cache/src/lru.test.ts +++ b/packages/cache/src/lru.test.ts @@ -273,6 +273,22 @@ describe('LruCache refuses a byte budget that is not a budget', () => { expect((caught as UltimateError).fix).not.toContain('lru.maxBytes in app.config.ts'); }); + // `defaultTtlMs` is the one limit with a second home: the boot passes `config.cache.defaultTtlMs` + // into the rungs it builds, so a fix calling it "never an app.config.ts key" sent the operator + // away from the line that set it. + test('a refused defaultTtlMs names app.config.ts too, where the boot read it from', () => { + let caught: unknown; + try { + new LruCache({ defaultTtlMs: Number.NaN }); + } catch (thrown) { + caught = thrown; + } + const fix = (caught as UltimateError).fix; + expect((caught as UltimateError).code).toBe('X_CACHE_LIMIT_INVALID'); + expect(fix).toContain('cache.defaultTtlMs in app.config.ts'); + expect(fix).not.toContain('never an app.config.ts key'); + }); + test('the default and an ordinary budget still construct', () => { expect(() => new LruCache()).not.toThrow(); expect(new LruCache({ maxBytes: 1 }).stats().maxBytes).toBe(1); diff --git a/packages/cache/src/redis-buckets.ts b/packages/cache/src/redis-buckets.ts index b1482d05b..505d83e39 100644 --- a/packages/cache/src/redis-buckets.ts +++ b/packages/cache/src/redis-buckets.ts @@ -118,17 +118,25 @@ export async function lostMembership( } /** `[cursor, [member, score, …]]` — flat in RESP2 and RESP3 alike; `[member, score]` pairs read too. */ -function scanPage(reply: unknown, bucket: string): { readonly cursor: string; members: string[] } { +function scanPage( + reply: unknown, + bucket: string, +): { readonly cursor: string; entries: [string, string][] } { if (!Array.isArray(reply) || reply.length !== 2 || !Array.isArray(reply[1])) { throw unreadable(bucket); } - const [cursor, entries] = reply as [unknown, unknown[]]; + const [cursor, flat] = reply as [unknown, unknown[]]; if (typeof cursor !== 'string' && typeof cursor !== 'number') throw unreadable(bucket); - const members = entries.every(Array.isArray) - ? (entries as unknown[][]).map(([member]) => member) - : entries.filter((_, i) => i % 2 === 0); - if (!members.every((member) => typeof member === 'string')) throw unreadable(bucket); - return { cursor: String(cursor), members: members as string[] }; + const pairs = flat.every(Array.isArray) + ? (flat as unknown[][]).map(([member, score]) => [member, score]) + : flat.flatMap((member, i) => (i % 2 === 0 ? [[member, flat[i + 1]]] : [])); + // RESP3 answers a score as a double, RESP2 as text: either is kept as the text `ZADD` takes. + const entries = pairs.map(([member, score]) => { + if (typeof member !== 'string') throw unreadable(bucket); + if (typeof score !== 'string' && typeof score !== 'number') throw unreadable(bucket); + return [member, String(score)] as [string, string]; + }); + return { cursor: String(cursor), entries }; } const unreadable = (bucket: string): CacheDriverUnavailableError => @@ -139,23 +147,23 @@ const unreadable = (bucket: string): CacheDriverUnavailableError => }); /** - * Every member of one bucket, `ZSCAN … COUNT BUST_PAGE_SIZE` per round trip. `ZSCAN`, never a + * Every member of one bucket with its score, `ZSCAN … COUNT BUST_PAGE_SIZE` per round trip. `ZSCAN`, never a * score cursor: Redis guarantees a scan returns every member present from its first call to its * last, whatever is added, removed or re-scored meanwhile. A `(score, offset)` cursor broke on * exactly those — a concurrent prune of a read page of tied dead members, or a re-write moving a * read tie member up, shifted the offset past live keys, which served stale until TTL. A scan - * may return a member twice; the set dedupes. + * may return a member twice; the map dedupes. The score is what a refused delete is re-joined at. */ -export async function readBucket(client: RedisLike, bucket: string): Promise { - const members = new Set(); +export async function readBucket(client: RedisLike, bucket: string): Promise> { + const members = new Map(); let cursor = '0'; do { const reply = await client.send('ZSCAN', [bucket, cursor, 'COUNT', String(BUST_PAGE_SIZE)]); const page = scanPage(reply, bucket); - for (const member of page.members) members.add(member); + for (const [member, score] of page.entries) members.set(member, score); cursor = page.cursor; } while (cursor !== '0'); - return [...members]; + return members; } /** `UNLINK` each key on its own (slot-local), pipelined per batch; which ones died is the answer. */ @@ -178,17 +186,40 @@ export async function unlinkAll( return { deleted, failures }; } -/** `ZREM` what died from every bucket that held it, `SWEEP_CONCURRENCY` commands in flight. */ +/** Which members each bucket really lost, and every `ZREM` the store refused. */ +export interface SweepResult { + readonly removed: Map>; + readonly failures: unknown[]; +} + +/** + * `ZREM` the members from every bucket named, `SWEEP_CONCURRENCY` commands in flight. Settled, never + * rejected: a refused chunk leaves its members where they were, which is a bucket still reaching + * them, and the caller must still delete the values the chunks that WERE removed point at. + */ export async function sweepBuckets( client: RedisLike, gone: ReadonlyMap>, -): Promise { - const work: (() => Promise)[] = []; +): Promise { + const removed = new Map>(); + const failures: unknown[] = []; + const work: (() => Promise)[] = []; for (const [bucket, members] of gone) { const list = [...members]; for (let start = 0; start < list.length; start += SWEEP_CHUNK) { const chunk = list.slice(start, start + SWEEP_CHUNK); - work.push(() => client.send('ZREM', [bucket, ...chunk])); + work.push(() => + client.send('ZREM', [bucket, ...chunk]).then( + () => { + const into = removed.get(bucket) ?? new Set(); + for (const member of chunk) into.add(member); + removed.set(bucket, into); + }, + (reason: unknown) => { + failures.push(reason); + }, + ), + ); } } let next = 0; @@ -200,4 +231,27 @@ export async function sweepBuckets( } }; await Promise.all(Array.from({ length: Math.min(SWEEP_CONCURRENCY, work.length) }, worker)); + return { removed, failures }; +} + +/** + * Put back every member whose value key the store refused to delete, in each bucket the sweep took + * it out of, at the score its bucket read gave it — so the retry the error asks for still reaches + * it. Settled: what the store refuses here is reported, never thrown past the rest. + */ +export async function rejoinBuckets( + client: RedisLike, + removed: ReadonlyMap>, + survivors: ReadonlyMap, +): Promise { + if (survivors.size === 0) return []; + const sends: Promise[] = []; + for (const [bucket, members] of removed) { + for (const member of members) { + const score = survivors.get(member); + if (score !== undefined) sends.push(client.send('ZADD', [bucket, score, member])); + } + } + const settled = await Promise.allSettled(sends); + return settled.flatMap((result) => (result.status === 'rejected' ? [result.reason] : [])); } diff --git a/packages/cache/src/redis-ordering.test.ts b/packages/cache/src/redis-ordering.test.ts index 8276f2848..0c659c824 100644 --- a/packages/cache/src/redis-ordering.test.ts +++ b/packages/cache/src/redis-ordering.test.ts @@ -77,17 +77,50 @@ describe('a bust racing a write, on the wire', () => { await expect(tier.invalidateTags([tag('post', '1')])).rejects.toThrow('redis refused UNLINK'); - const removed = client.sent - .filter((entry) => entry[0] === 'ZREM') - .map((entry) => entry.slice(2)); - // Only what actually died leaves the bucket. `x:c:stuck` is still a member, still tagged, - // and the retry the error asks for — `invalidateTags([tag('post', '1')])` — reaches it. - // Three buckets: the row's, the collection's, and the entity index the row bust never reads. - expect(removed).toEqual([['x:c:gone'], ['x:c:gone'], ['x:c:gone']]); + // The sweep runs before the delete (the next test says why), so what the store refused to + // delete is put back: `x:c:stuck` is a member again, at the score it was read with, and the + // retry the error asks for — `invalidateTags([tag('post', '1')])` — reaches it. Three + // buckets: the row's, the collection's, and the entity index the row bust never reads. + // A bucket the bust READ gets back only what it held: `x:t2:{post}` (the collection's) never + // held this row, and a member there would die with every other post's row bust. expect(client.members('x:t2:{post}:1')).toEqual(['x:c:stuck']); + expect(client.members('x:t2:{post}')).toEqual([]); expect(client.members('x:e2:{post}')).toEqual(['x:c:stuck']); }); + test("a fill that lands between a bust's delete and its sweep is still reached by the next bust of the same tag", async () => { + // Another replica's fill (its fence sampled after the bump, so a valid fresh value) lands + // right after this bust's UNLINK. A sweep that ran AFTER the delete removed the member the + // fill had just re-joined: a live value no tag reaches, which the next mutation's bust missed + // and which served stale for the whole TTL. + const server = fakeRedis(); + const replica = tierFor(server); + let fill: Promise | undefined; + const busting: RedisLike = { + get: (key) => server.get(key), + set: (key, value) => server.set(key, value), + async send(command, args) { + const reply = await server.send(command, args); + if (command === 'UNLINK' && args[0] === 'x:c:feed' && fill === undefined) { + fill = replica.set('feed', 'fresh', { ttlMs: 60_000, tags: [tag('post', '1')] }); + await fill; + } + return reply; + }, + }; + const tier = tierFor(busting); + await tier.set('feed', 'old', { ttlMs: 60_000, tags: [tag('post', '1')] }); + + await tier.invalidateTags([tag('post', '1')]); + expect(fill).toBeDefined(); + expect((await tier.get('feed'))?.value).toBe('fresh'); + + const next = await tier.invalidateTags([tag('post', '1')]); + + expect(next.keys).toEqual(['feed']); + expect(await tier.get('feed')).toBeUndefined(); + }); + test('a bust that succeeded empties the buckets it read, member by member', async () => { const client = fakeRedis(); const tier = tierFor(client); diff --git a/packages/cache/src/redis.ts b/packages/cache/src/redis.ts index 3c272cbeb..03ddf849c 100644 --- a/packages/cache/src/redis.ts +++ b/packages/cache/src/redis.ts @@ -14,6 +14,7 @@ import { joinBuckets, lostMembership, readBucket, + rejoinBuckets, sweepBuckets, unlinkAll, } from './redis-buckets'; @@ -137,16 +138,17 @@ function leaseFrom(reply: unknown): Lease { * the operator sees which key the store refused rather than a count. * * The `fix:` is the call, not a command: there is no `x cache` in this build, and the retry is one - * line of the app's own code. It is safe to repeat because every key the store refused kept its - * tag membership — the bust `ZREM`s only what it deleted. + * line of the app's own code. It is safe to repeat because every key the store refused to delete + * is re-joined to the buckets the sweep took it out of (`rejoinBuckets`), and a refused `ZREM` left + * its members where they were. */ function raiseSweepFailure(failures: readonly unknown[], attempted: number): never { const first = failures[0]; if (first instanceof Error) throw first; throw new CacheDriverUnavailableError({ driver: 'redis', - cause: `${String(failures.length)} of ${String(attempted)} value keys could not be deleted`, - fix: "await invalidateTags(tags) again once redis answers — from '@ultimat3/cache', with the same tags; every key it refused kept its bucket membership, so the retry reaches it", + cause: `redis refused ${String(failures.length)} command(s) of a bust over ${String(attempted)} value keys`, + fix: "await invalidateTags(tags) again once redis answers — from '@ultimat3/cache', with the same tags; every key it could not delete was put back in its buckets, so the retry reaches it", }); } @@ -288,9 +290,16 @@ export function redisTier(options: RedisTierOptions = {}): CacheTier { fence: (scope: FenceScope) => sampleGenerations(conn(), ns, clock, scope), /** - * Read every bucket the tags match, a page per round trip and the buckets concurrently; - * `UNLINK` what they held, one key per command; then `ZREM` exactly what died. Every command - * names one key, so a bust is slot-local on Redis Cluster whatever tags it carries. + * Read every bucket the tags match, a page per round trip and the buckets concurrently; `ZREM` + * what they held; THEN `UNLINK` it, one key per command; and re-join any member whose value + * the store refused to delete. Every command names one key, so a bust is slot-local on Redis + * Cluster whatever tags it carries. + * + * Sweep before delete, never after: another replica's fill can land between the two. After a + * delete, its `ZADD` re-joins a member the later sweep then removes — a live value no tag + * reaches, missed by every later bust and stale for the whole TTL. Before it, the fill's + * membership either lands after the sweep (and survives, reachable) or before it, where its + * own `ZSCORE` re-check finds it gone and deletes the value (`set`). */ async invalidateTags(tags: readonly CacheTag[]): Promise { const claimed = new Set(); @@ -309,27 +318,46 @@ export function redisTier(options: RedisTierOptions = {}): CacheTier { await bumpGenerations(bustConn(), ns, tags); const buckets = [...claimed]; const pages = await Promise.all(buckets.map((bucket) => readBucket(bustConn(), bucket))); - const held = new Map(buckets.map((bucket, i) => [bucket, pages[i] ?? []])); + const held = new Map(buckets.map((bucket, i) => [bucket, pages[i] ?? new Map()])); // A member may sit in two buckets; deleting it twice is harmless but reporting it twice - // makes the `/_x` panel overstate what cleared. - const members = [...new Set(pages.flat())]; - const { deleted, failures } = await unlinkAll(bustConn(), members); + // makes the `/_x` panel overstate what cleared. Its highest score is the one it re-joins at. + const scores = new Map(); + for (const page of pages) { + for (const [member, score] of page) { + const seen = scores.get(member); + if (seen === undefined || Number(score) > Number(seen)) scores.set(member, score); + } + } + const members = [...scores.keys()]; - // Only what actually died leaves its buckets. A member the store refused to delete keeps its - // membership, so the retry `report.errors` asks for still finds it. const gone = new Map>(); for (const { read, sweep } of perTag) { - const died = read.flatMap((bucket) => held.get(bucket) ?? []).filter((m) => deleted.has(m)); - if (died.length === 0) continue; + const found = read.flatMap((bucket) => [...(held.get(bucket)?.keys() ?? [])]); + if (found.length === 0) continue; for (const bucket of sweep) { const into = gone.get(bucket) ?? new Set(); - for (const member of died) into.add(member); + for (const member of found) into.add(member); gone.set(bucket, into); } } - await sweepBuckets(bustConn(), gone); + const swept = await sweepBuckets(bustConn(), gone); + const { deleted, failures } = await unlinkAll(bustConn(), members); - if (failures.length > 0) raiseSweepFailure(failures, members.length); + // A member the store refused to delete goes back into the buckets it left, so the retry + // `report.errors` asks for still finds it. A bucket this bust READ gets back only what it + // held — a row in its collection's bucket would die with every other row's bust. One it only + // swept is unknown, so it gets the member back: the entity index holds every write's member + // by construction, and an extra member there costs a miss, where a missing one serves stale. + const survivors = new Map([...scores].filter(([member]) => !deleted.has(member))); + const left = new Map( + [...swept.removed].map(([bucket, out]) => { + const read = held.get(bucket); + return [bucket, read === undefined ? out : new Set([...out].filter((m) => read.has(m)))]; + }), + ); + const lost = await rejoinBuckets(bustConn(), left, survivors); + const refused = [...failures, ...swept.failures, ...lost]; + if (refused.length > 0) raiseSweepFailure(refused, members.length); const stripped = [...deleted].map((key) => key.slice(valueKey('').length)); return { tier: 'redis', keys: stripped }; }, diff --git a/packages/cache/src/semantic.test.ts b/packages/cache/src/semantic.test.ts index bed236118..584bd80e1 100644 --- a/packages/cache/src/semantic.test.ts +++ b/packages/cache/src/semantic.test.ts @@ -130,6 +130,22 @@ describe('remember + lookup', () => { expect(newHit?.value).toBe('second'); expect(newHit?.key).toBe('k'); }); + + // Held by reference, a hit WAS the writer's object: a caller that appended to the completion it + // got back rewrote the answer every later near-duplicate prompt received — the shape the LRU + // tier stopped storing for the same reason. + test("a hit is not the writer's live object", async () => { + const cache = memorySemanticCache(); + const answer = { text: 'original', at: new Date('2026-11-19T00:00:00.000Z') }; + await cache.remember('k', [1, 0], answer); + answer.text = 'the writer changed it'; + + const first = await cache.lookup([1, 0]); + expect(first?.value).toEqual({ text: 'original', at: new Date('2026-11-19T00:00:00.000Z') }); + if (first !== undefined) first.value.text = 'a reader changed it'; + + expect((await cache.lookup([1, 0]))?.value.text).toBe('original'); + }); }); describe('maxEntries eviction', () => { diff --git a/packages/cache/src/semantic.ts b/packages/cache/src/semantic.ts index ad6e840bb..0d15e45f2 100644 --- a/packages/cache/src/semantic.ts +++ b/packages/cache/src/semantic.ts @@ -2,8 +2,8 @@ // Keyed by embedding, matched by cosine similarity above a threshold — exact string keys miss on // "list my orders" vs "show me my orders", which is most of the traffic. // -// The in-memory default is correct but O(n); pgvector is the production backing (an ivfflat index -// over `x_semantic_cache.embedding`), which is why the interface is a driver. +// The in-memory default is correct but O(n), and as of 2026-11 it is the only implementation: no +// Postgres/pgvector-backed one exists. The interface is a driver so an app can supply one. import type { Clock } from '@ultimat3/core'; import { systemClock } from '@ultimat3/core'; @@ -16,6 +16,7 @@ import { assertTtl, nowMs, } from './tiers'; +import { decodeCacheValue, encodeCacheValue } from './value-codec'; export type Embedding = readonly number[]; @@ -85,7 +86,11 @@ export function cosineSimilarity(a: Embedding, b: Embedding): number { interface SemanticRecord { readonly key: string; readonly embedding: Embedding; - readonly value: unknown; + /** + * `{ v }` as `value-codec.ts` text, as the LRU tier holds it — never the caller's object, or a + * hit is the writer's live object and one reader's edit is every later reader's answer. + */ + readonly text: string; readonly expiresAt: number; readonly tags: readonly CacheTag[]; } @@ -128,7 +133,7 @@ export function memorySemanticCache(options: SemanticCacheOptions = {}): Semanti override, 'the override argument to lookup(embedding, override)', ); - let best: SemanticHit | undefined; + let best: { readonly record: SemanticRecord; readonly similarity: number } | undefined; for (const record of live()) { const similarity = cosineSimilarity(embedding, record.embedding); // A similarity that is not a number is not a match. Every comparison against `NaN` is @@ -138,10 +143,13 @@ export function memorySemanticCache(options: SemanticCacheOptions = {}): Semanti if (!Number.isFinite(similarity)) continue; if (similarity < floor) continue; if (best === undefined || similarity > best.similarity) { - best = { value: record.value as T, similarity, key: record.key }; + best = { record, similarity }; } } - return Promise.resolve(best); + if (best === undefined) return Promise.resolve(undefined); + // Decoded once, for the winner only: a fresh object per hit. + const { v } = decodeCacheValue(best.record.text) as { readonly v: T }; + return Promise.resolve({ value: v, similarity: best.similarity, key: best.record.key }); }, remember( @@ -157,11 +165,12 @@ export function memorySemanticCache(options: SemanticCacheOptions = {}): Semanti const ttlMs = assertTtl(key, rememberOptions?.ttlMs ?? defaultTtlMs, 'semantic', { jitterFraction: 0, }); + const text = encodeCacheValue({ v: value }, { key, tier: 'semantic' }); records.delete(key); records.set(key, { key, embedding, - value, + text, expiresAt: nowMs(clock) + ttlMs, tags: rememberOptions?.tags ?? [], }); diff --git a/packages/cli/CLAUDE.md b/packages/cli/CLAUDE.md index 762a7550b..ce31bb8a5 100644 --- a/packages/cli/CLAUDE.md +++ b/packages/cli/CLAUDE.md @@ -123,7 +123,7 @@ Commands: `bun test ./packages/cli/` (repo root: the preload), | File | Job | |---|---| -| `serve.ts` / `serve-boot.ts` / `serve-entry.ts` / `serve-env.ts` | the production entry: `ROLE`, env bindings, `ROLE=migrate`; `X_APP_MODULE_LOAD_FAILED` † | +| `serve.ts` / `serve-boot.ts` / `serve-entry.ts` / `serve-env.ts` | the production entry: `ROLE` (outside `config.roles`: `X_CONFIG_INVALID`; `migrate` exempt), env bindings, `ROLE=migrate`; `X_APP_MODULE_LOAD_FAILED` † | | `app-load-batch.ts` / `app-load-register.ts` | one hook module per app module, registered in order; registration state † | | `app-load-prebuilt.ts` / `build-registry.ts` / `build-registry-background.ts` | every serving role boots from the prebuilt registry (`x build`); stale → scan † | | `generate-refresh.ts` | `x g` refreshes the manifest only when a written file needs it | @@ -140,7 +140,7 @@ Commands: `bun test ./packages/cli/` (repo root: the preload), | `runtime-mfa-warning.ts` / `runtime-idempotency-scope.ts` | boot warnings: unsealed MFA secrets, a per-process idempotency store † | | `app-config-load.ts` | the ONE reader of `app.config.ts` (`loadAppConfig`) † | | `theme-brand.ts` | the ONE reader of an app's theme (`brand` in `apps/web/shared/theme.ts`) † | -| `runtime-{jobs,realtime,notify-retention,cache,purge,replica}.ts` | the `app.config.ts` sections the boot obeys (`*Of(config)`) † | +| `runtime-{jobs,realtime,notify-retention,cache,purge,replica,database-ssl}.ts` | the `app.config.ts` sections the boot obeys (`*Of(config)`); `database.ssl` adds `sslmode=require` only where the URL and `PGSSLMODE` state none † | | `runtime-cache-bus.ts` | which bus carries cache/ISR invalidations across replicas; one `cache.broadcast` boot line † | | `runtime-jobs.ts` (queues) | `WORKER_QUEUES` = the EXACT set, else `X_WORKER_QUEUE_UNKNOWN`; `-unserved.ts`: what no worker serves † | | `serve-retire.ts` / `dev-restart-retire.ts` | the worker retire (SIGUSR2, before an `x dev` restart's drain) † | @@ -162,7 +162,8 @@ Commands: `bun test ./packages/cli/` (repo root: the preload), | `local-cli.ts` / `local-cli-handoff.ts` | a global `x` hands over to the app's own CLI † | | `serve-prebuilt.ts` / `serve-prebuilt-paths.ts` | the image's prebuilt store; a boot that built anything logs `X_IMAGE_NOT_PREBUILT` † | | `dev-*.ts` | `x dev` only: dashboard sources, traces, the N+1 ledger, watcher, reload, lock, port | -| `cmd-stop.ts` / `cmd-stop-spec.ts` | `x stop`: the lock's pid only, SIGTERM, wait; `X_DEV_STOP_TIMEOUT` † | +| `cmd-stop.ts` / `cmd-stop-spec.ts` | `x stop`: the lock's pid only, SIGTERM, wait; a reused pid's lock is cleared, unsignalled; `X_DEV_STOP_TIMEOUT` † | +| `dev-lock-live.ts` | `refuseBesideDev`: `x db migrate\|reset\|status\|diagnostics\|recount` never open an embedded database a live `x dev` holds | | `dev-dashboard-guard.ts` / `loopback-host.ts` | `/_x`: loopback `Host` (`X_DEV_HOST_REFUSED`) and peer (`X_DEV_PEER_REFUSED`) † | | `dev-host.ts` / `dev-tls*.ts` | `x dev --host` (loopback default) and `--tls`: a cached self-signed cert in `.x/tls/`, WebCrypto + hand-written DER | | `doctor-pooler.ts` / `runtime-statement-bound.ts` | the statement bound and a pooler's refusal, one finding, one boot line † | diff --git a/packages/cli/README.md b/packages/cli/README.md index 6f4b92d3d..b52af5088 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -244,7 +244,7 @@ its name like any guard. | `workspace-checks.ts` | file-size ceiling and package contract files | | `drift.ts` `budgets.ts` | the checks `x verify` composes | | `budgets-freshness.ts` `verify-budgets-build.ts` | whether `budgets` may read the stats on disk, and the build it runs when not | -| `cmd-stop.ts` | `x stop`: SIGTERM to the lock's pid, the wait, the Windows lock clear | +| `cmd-stop.ts` | `x stop`: SIGTERM to the lock's pid, the wait, the Windows lock clear; a lock whose pid the kernel reused is cleared with nothing signalled | The CLI describes an app by **loading** it, never by parsing it: `action()`, `entity()`, `job()` and `defineRoute()` register themselves, and `x manifest`, `x routes` and `x verify` diff --git a/packages/cli/e2e/client-navigation-modal-fixture.ts b/packages/cli/e2e/client-navigation-modal-fixture.ts index 8c56ebf99..e22db993d 100644 --- a/packages/cli/e2e/client-navigation-modal-fixture.ts +++ b/packages/cli/e2e/client-navigation-modal-fixture.ts @@ -27,23 +27,32 @@ if (script === undefined) expect.unreachable('the client router did not build'); const BUILD = 'm1'; const SURFACE = 'web:app'; -/** Mounts by writing its name; its disposer records it — what "the page beneath stayed live" reads. */ +/** + * Mounts by adding its name; its disposer records it — what "the page beneath stayed live" reads. + * It ADDS to the server markup, as a takeover island and Solid's `render()` do, so the props script + * the wrapper carries is still in the document when a modal brings a second one with the same id. + */ const ISLAND = `export function mount(el, props) { (window.__mounts = window.__mounts || []).push(props.name); - el.textContent = 'mounted:' + props.name; + el.append(' mounted:' + props.name); return () => (window.__disposed = window.__disposed || []).push(props.name); }`; -const island = (name: string): { html: string; directive: IslandDirective } => { +/** + * One island module, so the id is the collector's `-` PER DOCUMENT: the page + * and the modal over it both hold `island-1`, and only the props tell the two apart. + */ +const island = (name: string, index: number): { html: string; directive: IslandDirective } => { const directive: IslandDirective = { - islandId: `island-${name}`, + islandId: `island-${String(index + 1)}`, + moduleId: 'island', strategy: 'idle', entry: '/island.js', props: { name }, }; return { directive, - html: `
${emitIslandProps(directive)}server:${name}
`, + html: `
server:${name}${emitIslandProps(directive)}
`, }; }; diff --git a/packages/cli/e2e/client-navigation-modal.e2e.test.ts b/packages/cli/e2e/client-navigation-modal.e2e.test.ts index caea15213..786da9d26 100644 --- a/packages/cli/e2e/client-navigation-modal.e2e.test.ts +++ b/packages/cli/e2e/client-navigation-modal.e2e.test.ts @@ -91,6 +91,26 @@ describe.skipIf(noBrowser)('client navigation · route-presented modals', () => TIMEOUT_MS, ); + // An island id is per document (`island-1` on the page and again in the modal), so a lookup of + // the props by id across the whole tab hands the modal's island the page's — the first in order. + test( + 'an island in a modal boots with its own props when the page beneath holds the same island id', + async () => { + await start(); + await read('window.__mounts = []'); + await read('document.getElementById("new").click()'); + await opened('New run'); + const ISLANDS = 'document.querySelectorAll("[data-x-island=island-1]")'; + expect(await read(`${ISLANDS}.length`)).toBe(2); + await waitFor( + `${DIALOG}.querySelector("[data-x-mounted]") !== null`, + "the modal's island mounted", + ); + expect(await read('JSON.stringify(window.__mounts)')).toBe('["form"]'); + }, + TIMEOUT_MS, + ); + test( 'the click opens the frame in its own task; the answer fills it when it arrives', async () => { diff --git a/packages/cli/src/app-root.ts b/packages/cli/src/app-root.ts index febd7e163..85004b88b 100644 --- a/packages/cli/src/app-root.ts +++ b/packages/cli/src/app-root.ts @@ -54,7 +54,12 @@ export function findAppRoot(from: string): AppRoot | undefined { : { dir, configPath: join(dir, APP_CONFIG_FILE), manifestPath: join(dir, MANIFEST_FILE) }; } -export function requireAppRoot(command: string, from: string): AppRoot { +export function requireAppRoot( + command: string, + from: string, + /** What was typed after `x`, for the refusal's fix to hand back whole (`dispatch.ts`). */ + typed?: readonly string[], +): AppRoot { const root = findAppRoot(from); if (root === undefined) { const dir = resolve(from); @@ -64,6 +69,7 @@ export function requireAppRoot(command: string, from: string): AppRoot { below: appDirsBelow(dir), adopter: dependsOnFramework(dir), xScript: hasXScript(dir), + ...(typed === undefined ? {} : { typed }), }); } return root; diff --git a/packages/cli/src/cmd-db-recount.ts b/packages/cli/src/cmd-db-recount.ts index 55dd67c9b..0d0c28ff5 100644 --- a/packages/cli/src/cmd-db-recount.ts +++ b/packages/cli/src/cmd-db-recount.ts @@ -19,13 +19,14 @@ import { loadApp } from './app-load'; import { loadAppRuntime } from './app-runtime'; import type { CommandContext } from './command'; import { withOpenedDb } from './db-client-displace'; -import { DevAlreadyRunningError, liveDevLock } from './dev-lock'; +import { refuseBesideDev } from './dev-lock-live'; import { BadFlagError } from './errors'; import { msg } from './messages'; import type { CommandResult } from './output'; import { flagBool } from './parse'; import { resolveServices } from './runtime-bindings'; import { installBootPorts } from './runtime-boot-ports'; +import { databaseSslOf } from './runtime-database-ssl'; import { startDb } from './runtime-queue'; import { quoteArg } from './shell-quote'; @@ -144,20 +145,12 @@ async function recount(ctx: CommandContext, root: string): Promise startDb(services, ctx.env), + () => startDb(services, ctx.env, ssl), async (client) => { const report = await recountInBatches(client, parent.$table, counter, { write }); const drift = report.rows; diff --git a/packages/cli/src/cmd-db-status.ts b/packages/cli/src/cmd-db-status.ts index 5bcd190b3..26b12bb5e 100644 --- a/packages/cli/src/cmd-db-status.ts +++ b/packages/cli/src/cmd-db-status.ts @@ -21,12 +21,13 @@ import { dbStatusJson, dbStatusLines, } from './db-status'; -import { DevAlreadyRunningError, liveDevLock } from './dev-lock'; +import { refuseBesideDev } from './dev-lock-live'; import { readStamp, thisBuild } from './framework-schema-apply'; import { msg } from './messages'; import { readMigrations } from './migrations'; import type { CommandResult } from './output'; import { resolveServices } from './runtime-bindings'; +import { databaseSslOf } from './runtime-database-ssl'; import { startDb } from './runtime-queue'; /** The stamp, then the ledger; a missing ledger (`42P01`) is a fact, every other failure throws. */ @@ -46,16 +47,10 @@ async function readFromApp(ctx: CommandContext, root: string): Promise startDb(services, ctx.env), readDbStatus); + const ssl = await databaseSslOf(services); + return withOpenedDb(() => startDb(services, ctx.env, ssl), readDbStatus); } export async function runDbStatus(ctx: CommandContext, root: string): Promise { diff --git a/packages/cli/src/cmd-db.ts b/packages/cli/src/cmd-db.ts index 5481b48a8..40b8c0f1f 100644 --- a/packages/cli/src/cmd-db.ts +++ b/packages/cli/src/cmd-db.ts @@ -41,7 +41,7 @@ import { selectSeeds, } from './db-seed'; import { runGeneratedSeed } from './db-seed-generate'; -import { DevAlreadyRunningError, liveDevLock } from './dev-lock'; +import { refuseBesideDev } from './dev-lock-live'; import { MissingSubcommandError, UnknownCommandError } from './errors'; import { type HeavyChild, withCheckoutLock } from './heavy'; import { withJobDriver } from './jobs-driver'; @@ -256,6 +256,10 @@ async function runMigrate( // and reports its own table as drift, and neither result says what happened. const fork = migrationFork(await readMigrations(root)); if (fork !== undefined) throw migrationForked(fork); + // An `x dev` holding the embedded database: PGlite takes no lock of its own, so this would + // apply into a directory that process has open, and its next write drops the tables applied. + const services = resolveServices(root, ctx.env); + if (services.db.mode === 'embedded') await refuseBesideDev(services.stateDir); const migrated = await runMigrations({ root, env: ctx.env }); const report = migrated.report; // A hand-written or pulled migration reaches the dump here, with no `x db gen` in between. @@ -313,14 +317,7 @@ async function runReset(ctx: CommandContext, root: string): Promise { findings: [conflictFinding(path, `git merge-file refused ${path}: ${merge.stderr.trim()}`)], }); } - const { text: result, conflicts } = path.endsWith('.json') + const resolved = path.endsWith('.json') ? { text: merge.stdout, conflicts: merge.code } : resolveAdditions(merge.stdout); + const result = resolved.text; + // Never exit 0 over a marker: git then records a clean merge of a file that still holds one. + const conflicts = conflictsLeft(result, resolved.conflicts, merge.code); await Bun.write(ours, result); if (conflicts === 0) { return ok(NAME, `${path}: merged both sides' additions`, { data: { path, conflicts } }); diff --git a/packages/cli/src/cmd-stop.test.ts b/packages/cli/src/cmd-stop.test.ts index e26a017d9..e8c44fc11 100644 --- a/packages/cli/src/cmd-stop.test.ts +++ b/packages/cli/src/cmd-stop.test.ts @@ -11,7 +11,8 @@ import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { UltimateError } from '@ultimat3/core'; import { DevStopDeniedError, DevStopTimeoutError, stopDev } from './cmd-stop'; -import { lockPath, parseLock, writeLock } from './dev-lock'; +import { clearStaleLock, liveDevLock, lockPath, parseLock, writeLock } from './dev-lock'; +import { liveDevLockChecked, refuseBesideDev } from './dev-lock-live'; const dirs: string[] = []; const children: Bun.Subprocess[] = []; @@ -157,7 +158,44 @@ describe('unit · x stop never signals a process the lock does not identify', () expect(result).toEqual({ stopped: false, stale: true }); expect(signalled).toEqual([]); expect(stranger.exitCode).toBeNull(); - expect(await Bun.file(lockPath(dir)).exists()).toBe(true); + }); + + // The lock a kill -9 left, on a pid the kernel handed to a stranger: `liveDevLock` reads the + // stranger as the holder, so `x db reset|status|diagnostics|recount` refused + // X_DEV_ALREADY_RUNNING with `fix: x stop`, and `x stop` answered "stale" and left it there. + test('a lock whose pid was reused is cleared, and liveDevLock then answers undefined', async () => { + const dir = stateDir(); + const stranger = await holder(dir, true); + const reused = { pid: stranger.pid, port: 4123, url: 'http://localhost:4123', started: '1' }; + await Bun.write(lockPath(dir), JSON.stringify(reused)); + // Before any `x stop`: the commands that refuse beside a live `x dev` already see no holder. + expect(liveDevLock(dir)?.pid).toBe(stranger.pid); + expect(await liveDevLockChecked(dir)).toBeUndefined(); + await refuseBesideDev(dir); + + await stopDev({ stateDir: dir, timeoutMs: 1_000, kill: () => undefined }); + expect(await Bun.file(lockPath(dir)).exists()).toBe(false); + expect(await Bun.file(`${lockPath(dir)}.steal`).exists()).toBe(false); + expect(liveDevLock(dir)).toBeUndefined(); + expect(stranger.exitCode).toBeNull(); + }); + + test('the x dev that wrote the lock is still the holder those commands refuse beside', async () => { + const dir = stateDir(); + const child = await holder(dir, true); + expect((await liveDevLockChecked(dir))?.pid).toBe(child.pid); + const refusal = await refuseBesideDev(dir).catch((error: unknown) => error); + expect(refusal).toBeInstanceOf(UltimateError); + expect((refusal as UltimateError).code).toBe('X_DEV_ALREADY_RUNNING'); + }); + + test('a lock that changed hands since it was judged stale is never deleted', async () => { + const dir = stateDir(); + const child = await holder(dir, true); + const before = await Bun.file(lockPath(dir)).text(); + // Judged from an older read of the file: same pid, another start time. + clearStaleLock(dir, { pid: child.pid, port: 4123, url: '', startedAt: '', started: '1' }); + expect(await Bun.file(lockPath(dir)).text()).toBe(before); }); test('a pid another user owns is X_DEV_STOP_DENIED, never a raw EPERM', async () => { diff --git a/packages/cli/src/cmd-stop.ts b/packages/cli/src/cmd-stop.ts index 932dcd7c5..a81a45f90 100644 --- a/packages/cli/src/cmd-stop.ts +++ b/packages/cli/src/cmd-stop.ts @@ -7,7 +7,15 @@ import { parseDuration } from '@ultimat3/time'; import { requireAppRoot } from './app-root'; import { stopSpec } from './cmd-stop-spec'; import type { CliCommand, CommandContext } from './command'; -import { clearLock, isProcessAlive, liveDevLock, lockPath, parseLock, reusedPid } from './dev-lock'; +import { + clearLock, + clearStaleLock, + isProcessAlive, + liveDevLock, + lockPath, + parseLock, + reusedPid, +} from './dev-lock'; import { BadFlagError } from './errors'; import { MIN_RELEASE_MS } from './hold'; import { msg } from './messages'; @@ -96,15 +104,21 @@ const lockNames = async (stateDir: string, pid: number): Promise => { * Signal the lock's holder and wait for both facts the next boot reads: the pid gone and the lock * no longer naming it. A dead pid whose lock survived was terminated without a drain (Windows, or a * crash mid-drain), and its lock is cleared here so `x stop` returning means `x dev` boots. - * No live holder is not a failure: a stale lock is left for `preflight`, which owns that clear. + * No live holder is not a failure: a lock naming a dead pid is left for `preflight`'s clear, and + * one naming a pid the kernel reused is cleared here, with nothing signalled. */ export async function stopDev(input: StopInput): Promise { const alive = input.alive ?? isProcessAlive; const lock = liveDevLock(input.stateDir); if (lock === undefined || !alive(lock.pid)) return { stopped: false }; // A pid alone is not the holder: a kill -9 leaves the lock and the kernel reuses the number. - // Nothing is signalled and nothing cleared; the next `x dev`'s preflight clears it (`reusedPid`). - if (await reusedPid(lock)) return { stopped: false, stale: true }; + // Nothing is signalled. The lock is cleared, under `preflight`'s own guard and only while it + // still holds the bytes judged here (`stealStale`): `x stop` returning means nothing holds the + // directory, and a lock left behind kept answering "stale" until the next `x dev`. + if (await reusedPid(lock)) { + clearStaleLock(input.stateDir, lock); + return { stopped: false, stale: true }; + } const windows = (input.platform ?? process.platform) === 'win32'; const started = performance.now(); signal(lock.pid, input.kill ?? ((pid: number) => process.kill(pid, 'SIGTERM'))); diff --git a/packages/cli/src/db-diagnostics.ts b/packages/cli/src/db-diagnostics.ts index 40dffcf0a..c316af911 100644 --- a/packages/cli/src/db-diagnostics.ts +++ b/packages/cli/src/db-diagnostics.ts @@ -9,11 +9,12 @@ import { } from '@ultimat3/db/diagnostics'; import type { CommandContext } from './command'; import { withOpenedDb } from './db-client-displace'; -import { DevAlreadyRunningError, liveDevLock } from './dev-lock'; +import { refuseBesideDev } from './dev-lock-live'; import { readIntFlag } from './flag-number'; import { msg } from './messages'; import type { CommandResult, JsonValue } from './output'; import { resolveServices } from './runtime-bindings'; +import { databaseSslOf } from './runtime-database-ssl'; import { startDb } from './runtime-queue'; import { renderTable } from './table'; @@ -80,20 +81,14 @@ export async function runDiagnostics(ctx: CommandContext, root: string): Promise if (services.db.mode === 'embedded') { // Check-then-open, as `x db reset` does: an `x dev` starting between this read and `startDb` // below is not seen. Narrow, and the same window every embedded `x db` subcommand has. - const holder = liveDevLock(services.stateDir); - if (holder !== undefined) { - throw new DevAlreadyRunningError({ - lock: holder, - stateDir: services.stateDir, - embeddedDb: true, - }); - } + await refuseBesideDev(services.stateDir); } + const ssl = await databaseSslOf(services); // `startDb` installs its client as the process's `db()`; `withOpenedDb` puts back what was there // (closing a lazy default it dropped) and closes both pools, or every later `db()` in an // embedding process reaches a dead pool. return withOpenedDb( - () => startDb(services, ctx.env), + () => startDb(services, ctx.env, ssl), async (client) => { // Embedded, the probe IS the boot — a WASM compile and an initdb, 12.6 s cold under coverage — // so the 3 s probe wait answered a healthy database X_DB_UNAVAILABLE. A server keeps the default. diff --git a/packages/cli/src/db-reset-lock.test.ts b/packages/cli/src/db-reset-lock.test.ts index 955f41780..f6dcdf648 100644 --- a/packages/cli/src/db-reset-lock.test.ts +++ b/packages/cli/src/db-reset-lock.test.ts @@ -44,3 +44,33 @@ describe('unit · x db reset never deletes a database a running x dev holds', () } }); }); + +// PGlite takes no lock of its own. Measured: a second process opens a directory `x dev` holds, +// its `create table` succeeds, and the holder's next write replaces the catalog — the table the +// migration created is gone, with no error on either side. +describe('unit · x db migrate never applies into an embedded database a running x dev holds', () => { + test('a live dev lock refuses the migrate with X_DEV_ALREADY_RUNNING, before pgdata is opened', async () => { + const root = await mkdtemp(join(tmpdir(), 'x-db-migrate-lock-')); + try { + await Bun.write(join(root, 'app.config.ts'), "export const config = { name: 'held' };\n"); + const lock = { pid: process.pid, port: 3000, url: 'http://localhost:3000', startedAt: '' }; + await Bun.write(lockPath(join(root, '.x')), JSON.stringify(lock)); + const ctx: CommandContext = { + args: parseArgs(['db', 'migrate'], SPECS), + cwd: root, + runner: exec, + env: {}, + bunVersion: REQUIRED_BUN, + }; + + const result = await dbCommand.run(ctx); + + expect(result.ok).toBe(false); + expect(result.findings?.map((finding) => finding.code)).toEqual(['X_DEV_ALREADY_RUNNING']); + expect(result.findings?.[0]?.fix).toStartWith('x stop --json'); + expect(await Bun.file(join(root, '.x/pgdata/PG_VERSION')).exists()).toBe(false); + } finally { + await rm(root, { recursive: true, force: true }); + } + }); +}); diff --git a/packages/cli/src/dev-lock-live.ts b/packages/cli/src/dev-lock-live.ts new file mode 100644 index 000000000..9082b39c8 --- /dev/null +++ b/packages/cli/src/dev-lock-live.ts @@ -0,0 +1,24 @@ +// Whether a LIVE `x dev` holds a state directory, asked by the commands that must not open or +// delete its embedded database beside it. A pid alone is not the holder: a kill -9 leaves the lock +// and the kernel reuses the number, and a stranger on that pid refused every `x db` command. + +import { DevAlreadyRunningError, type DevLock, liveDevLock } from './dev-lock'; +import { reusedPid } from './dev-lock-identity'; + +/** The lock of the `x dev` that wrote it and is still running; a reused pid is no holder. */ +export async function liveDevLockChecked(stateDir: string): Promise { + const lock = liveDevLock(stateDir); + return lock === undefined || (await reusedPid(lock)) ? undefined : lock; +} + +/** + * `X_DEV_ALREADY_RUNNING` when an `x dev` holds the embedded database under `stateDir`. PGlite + * takes no lock of its own: a second process opens the directory, writes, and the holder's next + * write replaces the catalog it wrote — measured, a `create table` from the second opener is gone. + */ +export async function refuseBesideDev(stateDir: string): Promise { + const holder = await liveDevLockChecked(stateDir); + if (holder !== undefined) { + throw new DevAlreadyRunningError({ lock: holder, stateDir, embeddedDb: true }); + } +} diff --git a/packages/cli/src/dev-lock.ts b/packages/cli/src/dev-lock.ts index 99af159be..3b3d9d9c3 100644 --- a/packages/cli/src/dev-lock.ts +++ b/packages/cli/src/dev-lock.ts @@ -308,6 +308,30 @@ const readLock = async (path: string): Promise => { return raw === null ? null : parseLock(raw); }; +/** + * Remove the lock `judged` was read from, for a caller that found its pid reused (`x stop`). Under + * the same guard a boot's steal holds, and only while the file still holds those bytes: a claim + * made since is another `x dev`'s, and is never deleted. + */ +export function clearStaleLock(stateDir: string, judged: DevLock): void { + const path = lockPath(stateDir); + let raw: string; + try { + raw = readFileSync(path, 'utf-8'); + } catch { + return; + } + const now = parseLock(raw); + if (now === null || now.pid !== judged.pid || now.started !== judged.started) return; + const mine: DevLock = { pid: process.pid, port: 0, url: '', startedAt: new Date().toISOString() }; + stealStale({ + path, + judged: raw, + claim: (guard) => claimExclusive(stateDir, guard, mine), + alive: isProcessAlive, + }); +} + export interface PreflightInput { readonly stateDir: string; readonly port: number; diff --git a/packages/cli/src/dispatch.test.ts b/packages/cli/src/dispatch.test.ts index 83133553c..0b5b9ac85 100644 --- a/packages/cli/src/dispatch.test.ts +++ b/packages/cli/src/dispatch.test.ts @@ -3,15 +3,16 @@ // the one branch that has no `ParsedArgs` to read `--json` off. import { afterAll, beforeAll, describe, expect, test } from 'bun:test'; -import { mkdtempSync, rmSync } from 'node:fs'; // why: Bun has no mkdtemp. +import { mkdtempSync, realpathSync, rmSync } from 'node:fs'; // why: Bun has no mkdtemp. // why: Bun exposes no tmpdir(), so only node:os answers the platform temp root. import { tmpdir } from 'node:os'; import { currentLogStream, setLogStream } from '@ultimat3/core'; import { REQUIRED_BUN } from './app-root'; -import { dispatch, sinkFor } from './dispatch'; +import { dispatch, sinkFor, typedWords } from './dispatch'; import { loadErrorCatalog } from './error-catalog'; import { loadCodeFixes } from './error-fixes'; import type { CommandResult } from './output'; +import { parseArgs } from './parse'; import { SPECS } from './registry'; /** Every temp dir this file makes, removed after it: a fixture that outlives its run is a leftover (#738). */ @@ -79,6 +80,33 @@ describe('unit · the dispatcher is what enforces requiresApp', () => { } }); + // The fix was rebuilt from the command's NAME alone: `x db migrate` came back as + // `… @ultimat3/cli db --json`, which is X_CLI_BAD_FLAG (no subcommand) the moment it is pasted. + test("X_NOT_IN_APP's fix for `x db migrate` parses and names migrate", async () => { + const dir = made(realpathSync(mkdtempSync(`${tmpdir()}/x-below-app-`))); + await Bun.write(`${dir}/apps/game/app.config.ts`, ''); + const fixOf = async (argv: readonly string[]): Promise => { + const out = JSON.parse((await run(argv, dir)).out) as { findings?: { fix: string }[] }; + return out.findings?.[0]?.fix ?? expect.unreachable('no X_NOT_IN_APP finding'); + }; + const prefix = 'cd apps/game && bunx @ultimat3/cli '; + + const fix = await fixOf(['db', 'migrate', '--json']); + expect(fix).toBe(`${prefix}db migrate --json`); + const pasted = parseArgs(fix.slice(prefix.length).split(' '), SPECS); + expect([pasted.command, pasted.subcommand]).toEqual(['db', 'migrate']); + + // Positionals and flags travel too; `--cwd` and the JSON switch are the fix's own to write. + expect(await fixOf(['db', 'seed', 'demo', '--tier', 'dev', '-j', '--cwd', dir])).toBe( + `${prefix}db seed demo --tier dev --json`, + ); + expect(await fixOf(['db', 'seed', `--cwd=${dir}`, '--json', '--name', 'two words'])).toBe( + `${prefix}db seed --name 'two words' --json`, + ); + // A passthrough tail is the other tool's: `--json` appended behind it would be too. + expect(typedWords(['test', '--json', '--', '-t', 'name'])).toEqual(['test']); + }); + // The exemption, pinned: usage has to be readable from anywhere, and `--help` swaps the target // for the help command — which declares nothing — so this must keep answering outside an app. test('--help on a requiresApp command still answers outside an app', async () => { diff --git a/packages/cli/src/dispatch.ts b/packages/cli/src/dispatch.ts index d5e19919a..c22534e8c 100644 --- a/packages/cli/src/dispatch.ts +++ b/packages/cli/src/dispatch.ts @@ -93,6 +93,23 @@ const errorResult = (command: string, error: unknown): CommandResult => ({ * Returns the exit code instead of calling process.exit, so a test can drive the whole CLI end to * end without terminating the test runner. */ +/** + * `argv` as a refusal's fix pastes it back: every word typed, less `--cwd` (the fix names the + * directory itself) and the JSON switch (it ends with one). Rebuilt from the command's name alone, + * `x db migrate` came back as `x db`, a second refusal. Cut at a bare `--`: the fix appends its + * `--json` last, and behind a passthrough tail that switch would be the other tool's. + */ +export function typedWords(argv: readonly string[]): readonly string[] { + const words: string[] = []; + for (let index = 0; index < argv.length; index += 1) { + const word = argv[index] as string; + if (word === '--') break; + if (word === '--cwd') index += 1; + else if (word !== '--json' && word !== '-j' && !word.startsWith('--cwd=')) words.push(word); + } + return words; +} + export async function dispatch(options: DispatchOptions): Promise { const earlyReader = readerFor(options.cwd, options.invocation); // Its own branch, ahead of the parse: an unsupported Bun is a fact about the environment and @@ -180,7 +197,9 @@ export async function dispatch(options: DispatchOptions): Promise { // (`env init`, `secrets set`) — but the DECLARATION is now what decides, ahead of any check a // command makes about its own arguments. `--help` is exempt because `target` is then the help // command, which declares nothing: usage for a command must be readable from anywhere. - if (target.spec.requiresApp === true) requireAppRoot(target.spec.name, ctx.cwd); + if (target.spec.requiresApp === true) { + requireAppRoot(target.spec.name, ctx.cwd, typedWords(options.argv)); + } const result = await target.run(ctx); sinkFor(result, options)(render(result, args.json, args.flags.get('verbose') === true, reader)); // `x dev` and `x mcp serve --transport http` are still listening here: report first, so the diff --git a/packages/cli/src/errors.ts b/packages/cli/src/errors.ts index c37c62786..d40e0761c 100644 --- a/packages/cli/src/errors.ts +++ b/packages/cli/src/errors.ts @@ -8,11 +8,16 @@ import { quoteArg } from './shell-quote'; /** Commands whose bare form runs everything. */ const WHOLE_RUN: ReadonlySet = new Set(['test', 'verify']); -/** The nearest real command as a fix: its help when running it bare would start a whole suite. */ +/** Commands that act when run bare (stop, delete, roll out, rewrite, re-pin, inject a fault). */ +const ACTS_BARE = new Set('stop clean deploy fix upgrade drill'.split(' ')); + +/** The suggested command as a fix: its help when bare it starts a whole suite or changes state. */ const suggestedCommandFix = (suggestion: string): string => WHOLE_RUN.has(suggestion) ? `x ${suggestion} --help # the nearest command; bare, it runs every suite` - : `x ${quoteArg(suggestion.split(' '))}`; + : ACTS_BARE.has(suggestion) + ? `x ${suggestion} --help # the nearest command; bare, it acts at once` + : `x ${quoteArg(suggestion.split(' '))}`; /** An unknown command or subcommand. Carries a suggestion so the retry is one keystroke away. */ export class UnknownCommandError extends UltimateError { @@ -147,12 +152,14 @@ export class NotInAppError extends UltimateError { adopter?: boolean; /** `from`'s `package.json` has an `x` script (the framework repo): `bun run x -- … --cwd`. */ xScript?: boolean; + /** The words as typed — subcommand, positionals, flags — less the two the fix writes itself. */ + typed?: readonly string[]; }) { const [first] = input.below ?? []; const found = (input.below ?? []).join(', '); // Word by word: `'vapid create'` pasted as one quoted token is a command `x` does not have. // Assembled from arrays of screened words, so no value is spliced where a shell runs it. - const argv = input.command.split(' ').map(quoteArg); + const argv = (input.typed ?? input.command.split(' ')).map(quoteArg); const words = argv.join(' '); super({ code: 'X_NOT_IN_APP', diff --git a/packages/cli/src/mcp-host.ts b/packages/cli/src/mcp-host.ts index a6cf36435..e0e64a974 100644 --- a/packages/cli/src/mcp-host.ts +++ b/packages/cli/src/mcp-host.ts @@ -40,7 +40,7 @@ import { appManifest, policyFacts } from './app-manifest'; import { loadAppRuntime } from './app-runtime'; import { loadAppGraph, resolveNode } from './cmd-graph-load'; import { declareDevEnvironment, needsDevEnvironmentDeclaration } from './dev-environment'; -import { liveDevLock } from './dev-lock'; +import { liveDevLockChecked } from './dev-lock-live'; import { loadCodeFixes } from './error-fixes'; import type { Runner } from './exec'; import { assertExplainTarget, devNotRunning, narrowVerify, searchDocs } from './mcp-agent-host'; @@ -253,7 +253,7 @@ function capabilities( async requestStatements(ask) { // The lock `x dev` writes names its URL; a missing or stale one is no server to ask. - const lock = liveDevLock(lazy.services.stateDir); + const lock = await liveDevLockChecked(lazy.services.stateDir); if (lock === undefined) throw devNotRunning(); return requestStatements({ devUrl: lock.url, ...ask }); }, diff --git a/packages/cli/src/merge-driver-lines.test.ts b/packages/cli/src/merge-driver-lines.test.ts index 0c5833102..136ba8812 100644 --- a/packages/cli/src/merge-driver-lines.test.ts +++ b/packages/cli/src/merge-driver-lines.test.ts @@ -1,7 +1,7 @@ // Which conflicts `x merge-driver` may resolve: both sides adding whole entries, and nothing else. import { describe, expect, test } from 'bun:test'; -import { resolveAdditions } from './merge-driver-lines'; +import { conflictsLeft, resolveAdditions } from './merge-driver-lines'; const conflict = (ours: string[], base: string[], theirs: string[]): string[] => [ '<<<<<<< ours', @@ -86,3 +86,36 @@ describe('unit · a real conflict stays one, markers and all', () => { expect(resolveAdditions('a\nb\n')).toEqual({ text: 'a\nb\n', conflicts: 0 }); }); }); + +// `git merge-file` ends its markers the way the file ends its lines: on a CRLF checkout each is +// `<<<<<<< ours\r`. Compared whole, none was a marker — the text passed through with every marker +// in it, reported as 0 conflicts, and the driver exited 0: git recorded a clean merge. +describe('unit · a CRLF file', () => { + const crlf = (lines: string[]): string => lines.map((line) => `${line}\r\n`).join(''); + + test("CRLF input: both sides' additions merge, and an unrecognised marker is never reported as 0 conflicts", () => { + const text = crlf(['before', ...conflict([' beta,'], [], [' alpha,']), 'after']); + // Merged, and every line still ends as the file's lines do. + expect(resolveAdditions(text)).toEqual({ + text: 'before\r\n alpha,\r\n beta,\r\nafter\r\n', + conflicts: 0, + }); + + // A real conflict stays one, counted, with its markers as git wrote them. + const real = resolveAdditions( + crlf(['before', ...conflict([' a: 1,'], [], [' a: 2,']), 'after']), + ); + expect(real.conflicts).toBe(1); + expect(real.text).toContain('<<<<<<< ours\r\n'); + + // The backstop: git said it left conflicts and the text still opens one, whatever the + // resolver counted — a marker spelling it does not know must not become exit 0. + const unknown = 'a\n<<<<<<< ours\u2028\nb\n'; + expect(resolveAdditions(unknown).conflicts).toBe(0); + expect(conflictsLeft(unknown, 0, 2)).toBe(2); + // Nothing invented where there is nothing left, or where git reported none. + expect(conflictsLeft('a\nb\n', 0, 1)).toBe(0); + expect(conflictsLeft(unknown, 0, 0)).toBe(0); + expect(conflictsLeft(real.text, 1, 3)).toBe(1); + }); +}); diff --git a/packages/cli/src/merge-driver-lines.ts b/packages/cli/src/merge-driver-lines.ts index 4b8d45ee7..607aa6034 100644 --- a/packages/cli/src/merge-driver-lines.ts +++ b/packages/cli/src/merge-driver-lines.ts @@ -84,6 +84,17 @@ function bothSides(ours: readonly string[], theirs: readonly string[]): string[] .flatMap((entry) => entry.split('\n')); } +/** + * A marker line, with or without the `\r` git ends it with on a CRLF file. The `\r` stays on every + * line this module passes through or reorders, so the merged file keeps its own line ending. + */ +const isMarker = (line: string | undefined, marker: string): boolean => + line === marker || line === `${marker}\r`; + +/** The first `marker` line at or after `from`; -1 when there is none, or no `from` to start at. */ +const markerAt = (lines: readonly string[], marker: string, from: number): number => + from < 0 ? -1 : lines.findIndex((line, at) => at >= from && isMarker(line, marker)); + /** `text` — `git merge-file --diff3 -L ours -L base -L theirs` output — with additions resolved. */ export function resolveAdditions(text: string): LineMerge { const lines = text.split('\n'); @@ -91,13 +102,13 @@ export function resolveAdditions(text: string): LineMerge { let conflicts = 0; for (let index = 0; index < lines.length; index += 1) { const line = lines[index] as string; - if (line !== OURS_MARKER) { + if (!isMarker(line, OURS_MARKER)) { out.push(line); continue; } - const baseAt = lines.indexOf(BASE_MARKER, index); - const splitAt = lines.indexOf(SPLIT_MARKER, baseAt); - const endAt = lines.indexOf(THEIRS_MARKER, splitAt); + const baseAt = markerAt(lines, BASE_MARKER, index); + const splitAt = markerAt(lines, SPLIT_MARKER, baseAt); + const endAt = markerAt(lines, THEIRS_MARKER, splitAt); if (baseAt === -1 || splitAt === -1 || endAt === -1) { out.push(line); continue; @@ -112,3 +123,13 @@ export function resolveAdditions(text: string): LineMerge { } return { text: out.join('\n'), conflicts }; } + +/** + * The count the driver exits on. `resolved` is `resolveAdditions`' own; the rest is a backstop for + * a marker it did not recognise: when git reported conflicts and a line of the result still opens + * one, the file is not merged whatever was counted, and git's number stands. + */ +export function conflictsLeft(text: string, resolved: number, gitReported: number): number { + if (resolved > 0 || gitReported <= 0) return resolved; + return /^<{7} /m.test(text) ? gitReported : 0; +} diff --git a/packages/cli/src/parse.test.ts b/packages/cli/src/parse.test.ts index 92e1f15ea..64add50e7 100644 --- a/packages/cli/src/parse.test.ts +++ b/packages/cli/src/parse.test.ts @@ -1,7 +1,7 @@ import { describe, expect, test } from 'bun:test'; import { UnknownCommandError } from './errors'; import type { CommandSpec } from './parse'; -import { flagBool, flagString, parseArgs } from './parse'; +import { COMMAND_INTENTS, flagBool, flagString, intentFor, parseArgs } from './parse'; import { SPECS as SPECS_SHIPPED } from './registry'; import { thrownBy } from './thrown-by-fixture'; @@ -181,6 +181,45 @@ describe('unit · parseArgs', () => { expect(failure.fix).toStartWith('x verify --help'); }); + // Edit distance alone answered `x migrate` with `x upgrade`, `x start` with `x stop` and + // `x check` with `x clean`: a paste-and-run fix that changes state the caller never named. + test('no unknown-command fix is a bare state-changing command (migrate, start, check)', () => { + const fixFor = (word: string): string => + String(thrownBy(() => parseArgs([word], SPECS_SHIPPED)).fix); + // What the word means in every other toolchain, said in `x`'s own spelling. + expect(fixFor('migrate')).toBe('x db migrate'); + expect(fixFor('seed')).toBe('x db seed'); + for (const word of ['start', 'serve', 'server']) expect(fixFor(word)).toBe('x dev'); + expect(fixFor('lint')).toBe('x verify --only lint'); + for (const word of ['typecheck', 'tsc']) expect(fixFor(word)).toBe('x verify --only typecheck'); + expect(fixFor('check')).toStartWith('x verify --help'); + // A near miss of a command that acts when run bare is its help, never the command. + expect(fixFor('upgrad')).toStartWith('x upgrade --help'); + expect(fixFor('stopp')).toStartWith('x stop --help'); + expect(fixFor('clear')).toStartWith('x clean --help'); + expect(fixFor('deply')).toStartWith('x deploy --help'); + expect(fixFor('fixx')).toStartWith('x fix --help'); + const acting = ['x upgrade', 'x stop', 'x clean', 'x deploy', 'x fix', 'x drill']; + const words = ['migrate', 'start', 'check', 'update', 'cleanup', 'create', 'destroy', 'fmt']; + for (const word of [...words, 'kill', 'restart', 'rollback', 'reset', 'run', 'install']) { + expect(acting).not.toContain(fixFor(word)); + } + // A read-only near miss still pastes straight back. + expect(fixFor('route')).toBe('x routes'); + }); + + test('every intent names a command the shipped CLI parses', () => { + expect(Object.keys(COMMAND_INTENTS).length).toBeGreaterThan(0); + for (const [word, argv] of Object.entries(COMMAND_INTENTS)) { + // The word itself is not a command, or the entry is dead. + expect(SPECS_SHIPPED.some((spec) => spec.name === word)).toBe(false); + const args = parseArgs([...argv], SPECS_SHIPPED); + expect(args.command).toBe(argv[0] ?? expect.unreachable(`${word} names no command`)); + } + // Asked only of a table that has the command: a fixture without `dev` falls back to the guess. + expect(intentFor('start', ['verify', 'db'])).toBeUndefined(); + }); + test('an unknown subcommand names the command path, not just the token', () => { const failure = thrownBy(() => parseArgs(['db', 'frobnicate'], SPECS)); expect(failure.code).toBe('X_CLI_UNKNOWN_COMMAND'); diff --git a/packages/cli/src/parse.ts b/packages/cli/src/parse.ts index 52d708fbc..cf25605ef 100644 --- a/packages/cli/src/parse.ts +++ b/packages/cli/src/parse.ts @@ -122,11 +122,40 @@ export const wantsJson = (argv: readonly string[]): boolean => const HELP_ALIASES = new Set(['--help', '-h', 'help']); const VERSION_ALIASES = new Set(['--version', '-v', '-V']); +// What an unknown top-level word most likely MEANT, ahead of what it merely resembles. Edit +// distance answered `x migrate` with `x upgrade` and `x start` with `x stop`: a `fix:` is pasted +// and run, so a guess that changes state is worse than no guess. +/** + * A word other toolchains use, as the `x` argv that does it. Each is held to the shipped parser by + * `parse.test.ts`, so an entry cannot outlive the command it names. + */ +export const COMMAND_INTENTS: Readonly> = Object.freeze({ + migrate: ['db', 'migrate'], + seed: ['db', 'seed'], + start: ['dev'], + serve: ['dev'], + server: ['dev'], + lint: ['verify', '--only', 'lint'], + typecheck: ['verify', '--only', 'typecheck'], + tsc: ['verify', '--only', 'typecheck'], + check: ['verify'], +}); + +/** The suggestion for `word` (`'db migrate'`), when `commands` has the command it starts with. */ +export function intentFor(word: string, commands: readonly string[]): string | undefined { + const argv = Object.hasOwn(COMMAND_INTENTS, word) ? COMMAND_INTENTS[word] : undefined; + const [command] = argv ?? []; + return argv !== undefined && command !== undefined && commands.includes(command) + ? argv.join(' ') + : undefined; +} + function resolveCommand(token: string, specs: readonly CommandSpec[]): CommandSpec { const found = specs.find((spec) => spec.name === token || (spec.aliases ?? []).includes(token)); if (found !== undefined) return found; const names = specs.map((spec) => spec.name); - const suggestion = nearestName(token, names); + // What the word means before what it resembles: `migrate` is two edits from `upgrade`. + const suggestion = intentFor(token, names) ?? nearestName(token, names); throw new UnknownCommandError( suggestion === undefined ? { path: token, known: names } diff --git a/packages/cli/src/role-select.ts b/packages/cli/src/role-select.ts new file mode 100644 index 000000000..c69706fd1 --- /dev/null +++ b/packages/cli/src/role-select.ts @@ -0,0 +1,57 @@ +// `x dev --role`: which roles one dev process runs. Every value that is not a runnable selection +// is a flag error carrying the working invocation, never a silently narrowed or empty set. + +import type { Role } from '@ultimat3/core'; +import { isRole, ROLES } from '@ultimat3/core'; +import { BadFlagError } from './errors'; +import { DEV_ROLES } from './role-start-types'; +import { quoteArg } from './shell-quote'; + +/** + * What `--role` accepts. The replicator is here but not in `DEV_ROLES`: opt-in, because it takes + * the one replication slot a database has, and a default that did that would mean two developers + * pointed at one staging database silently fighting over it. + */ +export const SELECTABLE_ROLES: readonly Role[] = [...DEV_ROLES, 'replicator']; + +/** + * `--role web,worker` picks a subset. An unknown or out-of-scope role is a flag error with the + * working invocation in the fix line, never a silently ignored value — which is what it was. + */ +export function selectRoles(flag: string | undefined): readonly Role[] { + if (flag === undefined || flag.trim().length === 0) return DEV_ROLES; + const wanted = flag + .split(',') + .map((part) => part.trim()) + .filter((part) => part.length > 0); + // `--role ,` names nothing: read as "no roles" it booted an `x dev` that served nothing. + if (wanted.length === 0) { + throw new BadFlagError({ + flag: 'role', + command: 'dev', + reason: `it names no role (one or more of: ${SELECTABLE_ROLES.join(', ')})`, + fix: `x dev --role ${quoteArg(DEV_ROLES.join(','))}`, + }); + } + const selected: Role[] = []; + for (const name of wanted) { + if (!isRole(name)) { + throw new BadFlagError({ + flag: 'role', + command: 'dev', + reason: `"${name}" is not a role (known: ${ROLES.join(', ')})`, + fix: `x dev --role ${quoteArg(DEV_ROLES.join(','))}`, + }); + } + if (!SELECTABLE_ROLES.includes(name)) { + throw new BadFlagError({ + flag: 'role', + command: 'dev', + reason: `"${name}" does not run under x dev (it runs once, as \`x db migrate\`)`, + fix: `x dev --role ${quoteArg(DEV_ROLES.join(','))}`, + }); + } + if (!selected.includes(name)) selected.push(name); + } + return SELECTABLE_ROLES.filter((role) => selected.includes(role)); +} diff --git a/packages/cli/src/role-start.test.ts b/packages/cli/src/role-start.test.ts index 1af61aa03..5c6f42f0c 100644 --- a/packages/cli/src/role-start.test.ts +++ b/packages/cli/src/role-start.test.ts @@ -82,6 +82,16 @@ describe('unit · x dev --role', () => { expect((thrown as { fix: string }).fix).toBe('x dev --role web,sync,worker,scheduler'); }); + // `--role ,` split to nothing and selected NO role: `x dev` booted, served nothing, held the lock. + test('a --role that names no role at all is a flag error, never an empty selection', () => { + for (const flag of [',', ' , ,', ',,']) { + const thrown = refused(flag); + expect(thrown).toBeUltimateError('X_CLI_BAD_FLAG'); + expect((thrown as { cause: string }).cause).toContain('names no role'); + expect((thrown as { fix: string }).fix).toBe('x dev --role web,sync,worker,scheduler'); + } + }); + test('migrate is refused rather than silently dropped: it is a command, not a process', () => { expect(refused('migrate')).toBeUltimateError('X_CLI_BAD_FLAG'); }); diff --git a/packages/cli/src/role-start.ts b/packages/cli/src/role-start.ts index 2833648c9..8aa9fed63 100644 --- a/packages/cli/src/role-start.ts +++ b/packages/cli/src/role-start.ts @@ -6,8 +6,7 @@ // selectable but not default — it takes a replication slot on a shared database, which is not // something every `x dev` in a team should do to the same server by simply starting. -import type { Role } from '@ultimat3/core'; -import { ctxOf, isRole, logger, markReady, ROLES } from '@ultimat3/core'; +import { ctxOf, logger, markReady } from '@ultimat3/core'; import { dbExecutor } from '@ultimat3/db'; import type { RateLimitStore, Route, ServerHandle, WebSocketMount } from '@ultimat3/http'; import { @@ -31,7 +30,7 @@ import { import type { SyncWs } from '@ultimat3/realtime/server'; import { loadAppConfig } from './app-config-load'; import { errorPageHook } from './error-pages'; -import { BadFlagError, RuntimeDriverSplitError } from './errors'; +import { RuntimeDriverSplitError } from './errors'; import { DEFAULT_METRICS_PORT, rolePorts, @@ -43,7 +42,6 @@ import { rolesUnderRealtime } from './role-realtime'; import { startReplicator } from './role-replicator'; import { type DeviceMount, hostDeviceSockets } from './role-start-devices'; import type { RunningRoles, StartRolesOptions } from './role-start-types'; -import { DEV_ROLES } from './role-start-types'; import { prepareSync, type RunningSync, syncReadsChanges } from './role-sync'; import { startWorkerWake } from './role-wake'; import { installRoleBootWarnings } from './runtime-boot-warnings'; @@ -54,62 +52,22 @@ import { startLiveFeed } from './runtime-live-feed'; import { type RunningServices, releaseOrThrow } from './runtime-services'; import { inlineScriptSources } from './script-csp'; import { bootWarningConcernsAny } from './serve-boot-warnings'; -import { quoteArg } from './shell-quote'; import { inlineStyleSources } from './style-csp'; import { syncConnectSources } from './sync-url'; import { trustedHopsFromEnv } from './trusted-hops'; import { DEV_BINDING } from './web-binding'; -// Declared beside the option types so `x dev`'s spec reads it without loading this module. -export { DEV_ROLES } from './role-start-types'; - -/** - * What `--role` accepts. The replicator is here but not in `DEV_ROLES`: opt-in, because it takes - * the one replication slot a database has, and a default that did that would mean two developers - * pointed at one staging database silently fighting over it. - */ -export const SELECTABLE_ROLES: readonly Role[] = [...DEV_ROLES, 'replicator']; - +// `--role`'s reading, in a file of its own at the line ceiling. +export { SELECTABLE_ROLES, selectRoles } from './role-select'; // The two shapes this module takes and answers, in a file of their own at the line ceiling. export type { RunningRoles, StartRolesOptions } from './role-start-types'; +// Declared beside the option types so `x dev`'s spec reads it without loading this module. +export { DEV_ROLES } from './role-start-types'; // Re-exported, not re-declared: `web-binding.ts` is a leaf so `role-sync` can read the default // without importing this module, which imports it. export { DEV_BINDING, type WebBinding } from './web-binding'; -/** - * `--role web,worker` picks a subset. An unknown or out-of-scope role is a flag error with the - * working invocation in the fix line, never a silently ignored value — which is what it was. - */ -export function selectRoles(flag: string | undefined): readonly Role[] { - if (flag === undefined || flag.trim().length === 0) return DEV_ROLES; - const wanted = flag - .split(',') - .map((part) => part.trim()) - .filter((part) => part.length > 0); - const selected: Role[] = []; - for (const name of wanted) { - if (!isRole(name)) { - throw new BadFlagError({ - flag: 'role', - command: 'dev', - reason: `"${name}" is not a role (known: ${ROLES.join(', ')})`, - fix: `x dev --role ${quoteArg(DEV_ROLES.join(','))}`, - }); - } - if (!SELECTABLE_ROLES.includes(name)) { - throw new BadFlagError({ - flag: 'role', - command: 'dev', - reason: `"${name}" does not run under x dev (it runs once, as \`x db migrate\`)`, - fix: `x dev --role ${quoteArg(DEV_ROLES.join(','))}`, - }); - } - if (!selected.includes(name)) selected.push(name); - } - return SELECTABLE_ROLES.filter((role) => selected.includes(role)); -} - /** * A server whose route table demands an identity it has no way to resolve. * diff --git a/packages/cli/src/runtime-cache-limits.test.ts b/packages/cli/src/runtime-cache-limits.test.ts index 1238656f5..cda6f923d 100644 --- a/packages/cli/src/runtime-cache-limits.test.ts +++ b/packages/cli/src/runtime-cache-limits.test.ts @@ -17,6 +17,7 @@ import { logger } from '@ultimat3/core'; import { InProcessTransport } from '@ultimat3/realtime/server'; import type { Env } from './runtime-bindings'; import { startCacheTiers } from './runtime-cache'; +import { thrownBy } from './thrown-by-fixture'; const warnings: { line: string; meta: unknown }[] = []; const printWarning = logger.warn; @@ -135,6 +136,42 @@ describe('cache.defaultTtlMs', () => { expect(lease).toBeGreaterThan(4_000); }); + // `defineConfig` let 0 through, and the first reader was `lruTier`: X_CACHE_LIMIT_INVALID about + // an option "lru.defaultTtlMs" the app never wrote, its fix pointing at `runtime.ts`. + test('a lease that is not a whole number of milliseconds above zero refuses the boot, naming the config key', () => { + for (const defaultTtlMs of [0, -1, 1.5, Number.NaN, Number.POSITIVE_INFINITY]) { + const refused = thrownBy(() => + startCacheTiers({ + env: {}, + purge: noopPurgeDriver(), + transport: new InProcessTransport(), + tiers: ['request-memo', 'lru'], + defaultTtlMs, + }), + ); + expect(refused.code).toBe('X_CONFIG_INVALID'); + expect(refused.cause).toContain('cache.defaultTtlMs'); + expect(refused.fix).toContain('app.config.ts'); + expect(refused.fix).toContain('defaultTtlMs: 60_000'); + // Refused before any rung is registered: nothing is left in the process-global ladder. + expect(registeredTiers()).toEqual([]); + } + }); + + // Even where no rung reads it: the key is wrong in the file, whatever this ladder builds. + test('and it is refused on a ladder with no rung that takes a lease', () => { + const refused = thrownBy(() => + startCacheTiers({ + env: {}, + purge: noopPurgeDriver(), + transport: new InProcessTransport(), + tiers: ['request-memo'], + defaultTtlMs: 0, + }), + ); + expect(refused.code).toBe('X_CONFIG_INVALID'); + }); + test('leaves a supplied rung with the lease it was built with', async () => { const lease = await leaseOf(['request-memo', 'lru'], [lruTier({ defaultTtlMs: 120_000 })]); expect(lease).toBeGreaterThan(100_000); diff --git a/packages/cli/src/runtime-cache-ttl.ts b/packages/cli/src/runtime-cache-ttl.ts new file mode 100644 index 000000000..0a5e29db6 --- /dev/null +++ b/packages/cli/src/runtime-cache-ttl.ts @@ -0,0 +1,23 @@ +// `cache.defaultTtlMs` as the boot hands it to the rungs it builds — refused here under the key +// the app wrote, never by a rung under the name of an option the app never set. + +import { ConfigInvalidError } from '@ultimat3/core'; + +/** `describeValue` answers "a number" for 0 and 2.5 alike; a number is printed as itself. */ +const shown = (value: number): string => `${value}`; + +/** + * The lease option for a built rung, or nothing so the rung keeps its own default. A value that is + * not a whole number of milliseconds above zero is `X_CONFIG_INVALID` naming `cache.defaultTtlMs`: + * `lruTier` refuses the same value as `X_CACHE_LIMIT_INVALID` about "lru.defaultTtlMs", with a + * fix that points at `runtime.ts` — the wrong file for a key written in `app.config.ts`. + */ +export function defaultTtlOf(value: number | undefined): { defaultTtlMs?: number } { + if (value === undefined) return {}; + if (Number.isSafeInteger(value) && value > 0) return { defaultTtlMs: value }; + throw new ConfigInvalidError({ + cause: `cache.defaultTtlMs must be a whole number of milliseconds of at least 1, not ${shown(value)}`, + fix: 'defineConfig({ cache: { defaultTtlMs: 60_000 } }) # in app.config.ts: the lease of a cached value set with no ttlMs', + meta: { key: 'cache.defaultTtlMs', value: shown(value) }, + }); +} diff --git a/packages/cli/src/runtime-cache.ts b/packages/cli/src/runtime-cache.ts index b6caf6f9a..026523524 100644 --- a/packages/cli/src/runtime-cache.ts +++ b/packages/cli/src/runtime-cache.ts @@ -42,6 +42,7 @@ import { redisClient, redisUrlSource } from '@ultimat3/core/redis'; import type { Transport } from '@ultimat3/realtime/server'; import type { Env } from './runtime-bindings'; import { logCacheBus, selectCacheBus } from './runtime-cache-bus'; +import { defaultTtlOf } from './runtime-cache-ttl'; /** * The subject every replica of every app publishes tag invalidations on. One subject and not one @@ -154,7 +155,7 @@ const lazyRedis = (url: string, client: (url: string) => RedisLike): RedisLike = /** The boot's default lease, or nothing so the rung keeps its own. */ const ttlOf = (options: CacheTiersOptions): { defaultTtlMs?: number } => - options.defaultTtlMs === undefined ? {} : { defaultTtlMs: options.defaultTtlMs }; + defaultTtlOf(options.defaultTtlMs); /** * One rung, or a refusal. A process that cannot build what it was configured to build must not @@ -248,8 +249,11 @@ function warnDefaultRedis(built: readonly CacheTier[], env: Env): void { * * The outbound half publishes the wire tags this process just dropped; the inbound half applies * another instance's. A message this process published is delivered back to it on every real bus - * and is applied again — deliberately, with no node-id filter: dropping an already-dropped key is - * idempotent and free, while a dedup table is state that can be wrong. Re-emit is impossible by + * and is applied again — deliberately, with no node-id filter — to the tiers this process OWNS + * (the in-process rungs): there, dropping an already-dropped key is idempotent and free, while a + * dedup table is state that can be wrong. A SHARED rung is not free and is not re-busted: the + * sender cleared the one Redis every replica reads, so `@ultimat3/cache` applies an inbound + * broadcast to no tier the process does not own. Re-emit is impossible by * construction, not by a flag: `receiveInvalidationBroadcast` is the only entry point that * suppresses it, and `emit` is not a public parameter. */ @@ -261,6 +265,8 @@ export function startCacheTiers(options: CacheTiersOptions): () => Promise 'firstDialGraceMs', options.firstDialGraceMs ?? FIRST_DIAL_GRACE_MS, ); + // Whatever the ladder builds: the key is wrong in `app.config.ts`, and is named as that key. + defaultTtlOf(options.defaultTtlMs); // Built before ANY of them is registered: a refusal halfway through a list would leave the // process-global registry holding the rungs that came first, with no release returned to drop // them. Registration order does not decide read order — `sortTiers` does, by `CACHE_TIERS`. diff --git a/packages/cli/src/runtime-database-ssl.test.ts b/packages/cli/src/runtime-database-ssl.test.ts new file mode 100644 index 000000000..9e1939a52 --- /dev/null +++ b/packages/cli/src/runtime-database-ssl.test.ts @@ -0,0 +1,124 @@ +// `database.ssl: true` reaches the pool the boot opens: TLS is required where the URL says nothing, +// and a URL (or `PGSSLMODE`) that states its own mode is never overridden. + +import { afterEach, describe, expect, test } from 'bun:test'; +import { mkdtempSync } from 'node:fs'; // why: Bun has no temp-directory primitive. +import { rm } from 'node:fs/promises'; // why: Bun has no recursive remove. +import { tmpdir } from 'node:os'; // why: Bun exposes no temp root. +import { join } from 'node:path'; // why: Bun exposes no path-join primitive. +import { setDbClient } from '@ultimat3/db'; +import type { DevServices } from './runtime-bindings'; +import { databaseSslOf, withRequiredTls } from './runtime-database-ssl'; +import { startDb, startQueue } from './runtime-queue'; + +const host = globalThis as unknown as { Bun: { SQL: unknown } }; +const realBunSql = host.Bun.SQL; +const roots: string[] = []; + +afterEach(async () => { + host.Bun.SQL = realBunSql; + setDbClient(undefined); + await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true }))); +}); + +const recordPools = (): { readonly urls: string[] } => { + const seen = { urls: [] as string[] }; + host.Bun.SQL = class { + constructor(url: string) { + seen.urls.push(url); + } + async unsafe(): Promise { + return []; + } + async close(): Promise {} + }; + return seen; +}; + +const external = (url: string, root = '/app'): DevServices => + ({ root, db: { mode: 'external', url } }) as unknown as DevServices; + +const sslModeOf = (url: string | undefined): string | null => + new URL(url ?? expect.unreachable('no pool was opened')).searchParams.get('sslmode'); + +const appRoot = async (database: string): Promise => { + const root = mkdtempSync(join(tmpdir(), 'x-db-ssl-')); + roots.push(root); + await Bun.write( + join(root, 'app.config.ts'), + `export const config = { name: 'ssl-fixture', database: ${database} };\n`, + ); + return root; +}; + +describe('unit · database.ssl', () => { + test('database.ssl: true requires TLS on a URL that states no sslmode', async () => { + const pools = recordPools(); + const { client } = startDb(external('postgres://app@db.internal:5432/app'), {}, true); + await client.ping(); + expect(sslModeOf(pools.urls[0])).toBe('require'); + }); + + test('and on the standby the same boot opens', async () => { + const pools = recordPools(); + const { replica } = startDb( + external('postgres://app@db.internal:5432/app'), + { DATABASE_REPLICA_URL: 'postgres://reader@replica.internal:5432/app' }, + true, + ); + await replica?.ping(); + expect(pools.urls[0]).toContain('replica.internal'); + expect(sslModeOf(pools.urls[0])).toBe('require'); + }); + + test('database.ssl: false leaves the URL as written', async () => { + const pools = recordPools(); + const { client } = startDb(external('postgres://app@db.internal:5432/app'), {}, false); + await client.ping(); + expect(sslModeOf(pools.urls[0])).toBeNull(); + }); + + test("a URL's own sslmode is never overridden: neither downgraded nor weakened", () => { + for (const mode of ['disable', 'prefer', 'verify-ca', 'verify-full']) { + const url = `postgres://app@db.internal:5432/app?sslmode=${mode}`; + expect(withRequiredTls(url, {})).toBe(url); + } + }); + + test('PGSSLMODE in the boot env is the operator stating the mode: nothing is added', () => { + const url = 'postgres://app@db.internal:5432/app'; + expect(withRequiredTls(url, { PGSSLMODE: 'verify-full' })).toBe(url); + expect(sslModeOf(withRequiredTls(url, { PGSSLMODE: ' ' }))).toBe('require'); + }); + + test('a value that is not a URL is handed on untouched, for the client to refuse by name', () => { + expect(withRequiredTls('db.internal', {})).toBe('db.internal'); + }); + + // The wiring, not the rule: `startQueue` is every boot path's opener, and the switch was + // validated and documented while this call passed nothing. + test('startQueue opens the pool the app declared: ssl true, TLS required', async () => { + const pools = recordPools(); + const root = await appRoot('{ ssl: true }'); + const services = external('postgres://app@db.internal:5432/app', root); + // The recording pool answers no real catalog, so the boot past the ping may refuse: only the + // URL the pool was opened on is under test. + const queue = await startQueue(services, undefined, {}, 'ensure').catch(() => undefined); + await queue?.stop(); + expect(sslModeOf(pools.urls[0])).toBe('require'); + }); + + test('the switch is read from app.config.ts, and only for an external database', async () => { + const on = await appRoot('{ ssl: true }'); + expect(await databaseSslOf(external('postgres://app@db.internal/app', on))).toBe(true); + expect( + await databaseSslOf({ root: on, db: { mode: 'embedded' } } as unknown as DevServices), + ).toBe(false); + const off = await appRoot('{}'); + expect(await databaseSslOf(external('postgres://app@db.internal/app', off))).toBe(false); + // No app.config.ts at all: not an app, and nothing was declared. + expect(await databaseSslOf(external('postgres://app@db.internal/app', '/nonexistent'))).toBe( + false, + ); + }); +}); diff --git a/packages/cli/src/runtime-database-ssl.ts b/packages/cli/src/runtime-database-ssl.ts new file mode 100644 index 000000000..5c6ddf662 --- /dev/null +++ b/packages/cli/src/runtime-database-ssl.ts @@ -0,0 +1,41 @@ +// `app.config.ts`'s `database.ssl`, obeyed where the boot opens its pool: `true` requires TLS on a +// connection string that states no mode of its own. What the operator wrote always wins. + +import { loadAppConfig } from './app-config-load'; +import type { DevServices, Env } from './runtime-bindings'; + +/** libpq's parameter, which `Bun.SQL` reads off the URL (measured on bun 1.4: `require` refuses a + * server with no TLS, `ERR_POSTGRES_TLS_NOT_AVAILABLE`). */ +const SSL_MODE = 'sslmode'; + +/** + * `url` with `sslmode=require`, unless a mode is already stated — in the URL (`sslmode`, or the + * `ssl` spelling some dashboards hand out) or by `PGSSLMODE` in the boot's env. Never an override: + * replacing `verify-full` with `require` would drop certificate verification, and replacing + * `disable` would break the sidecar or loopback hop it was written for. `require` and not + * `verify-full` because a managed Postgres seldom ships its CA into the image; an operator who + * has one says so in the URL. A value no URL parser reads is handed on as it is: `postgresClient` + * refuses it by name (`X_DB_UNAVAILABLE`). + */ +export function withRequiredTls(url: string, env: Env): string { + if ((env['PGSSLMODE'] ?? '').trim() !== '') return url; + let parsed: URL; + try { + parsed = new URL(url); + } catch { + return url; + } + if (parsed.searchParams.has(SSL_MODE) || parsed.searchParams.has('ssl')) return url; + parsed.searchParams.set(SSL_MODE, 'require'); + return parsed.toString(); +} + +/** + * Whether this boot's pool must be TLS: `database.ssl` of the app at `services.root`. `false` for + * the embedded database (PGlite is in this process: there is no wire) without reading the config, + * and for a root with no `app.config.ts`. + */ +export async function databaseSslOf(services: DevServices): Promise { + if (services.db.mode !== 'external') return false; + return (await loadAppConfig(services.root))?.database.ssl === true; +} diff --git a/packages/cli/src/runtime-jobs.test.ts b/packages/cli/src/runtime-jobs.test.ts index 3dd072d70..b6d701f50 100644 --- a/packages/cli/src/runtime-jobs.test.ts +++ b/packages/cli/src/runtime-jobs.test.ts @@ -13,7 +13,8 @@ import { tmpdir } from 'node:os'; // why: Bun ships no path-joining API, so the temp root and the config file are joined with this. import { join } from 'node:path'; import { installLogSink, isUltimateError } from '@ultimat3/core'; -import { job, resetJobs, t } from '@ultimat3/jobs'; +import { job, purge, resetJobs, t } from '@ultimat3/jobs'; +import { resetDefaultRetry } from '@ultimat3/jobs/adapter'; import { definedStorage, resetStorage, type Storage } from '@ultimat3/storage'; import { loadAppConfig } from './app-config-load'; import type { RunningRoles } from './role-start'; @@ -46,6 +47,9 @@ afterEach(() => { ownStorages.clear(); }); +// `workerConfigOf` installs the app's default retry process-wide; no later file inherits it. +afterEach(() => resetDefaultRetry()); + const loadWorkerConfig = async (root: string) => workerConfigOf(await loadAppConfig(root)); const dirs: string[] = []; @@ -103,6 +107,47 @@ describe('workerConfigOf, over the one loader', () => { }); }); +describe('jobs.maxAttempts and jobs.backoff', () => { + afterEach(() => resetJobs()); + + test('jobs.maxAttempts and jobs.backoff reach a job that declares no retry', async () => { + // Built BEFORE the config is read, as an app's job modules are. + const sweep = purge({ name: 'sweep', targets: () => [] }); + const own = job({ + tenant: 'none', + name: 'own', + input: t.object({}), + idempotencyKey: () => 'own', + retry: { attempts: 2 }, + run: () => Promise.resolve(), + }); + expect(sweep.retry).toMatchObject({ attempts: 3, backoff: 'exponential' }); + + await loadWorkerConfig( + await appRoot( + "export const config = { name: 'demo', jobs: { maxAttempts: 7, backoff: 'fixed' } };\n", + ), + ); + + expect(sweep.retry).toMatchObject({ attempts: 7, backoff: 'fixed' }); + // A job's own `retry` overrides the count; the curve it does not name is the app's. + expect(own.retry).toMatchObject({ attempts: 2, backoff: 'fixed' }); + }); + + test('a root with no app.config.ts leaves the framework default, and clears an earlier one', async () => { + const sweep = purge({ name: 'sweep', targets: () => [] }); + workerConfigOf( + await loadAppConfig( + await appRoot("export const config = { name: 'demo', jobs: { maxAttempts: 7 } };\n"), + ), + ); + expect(sweep.retry.attempts).toBe(7); + + await loadWorkerConfig(await appRoot(undefined)); + expect(sweep.retry).toMatchObject({ attempts: 3, backoff: 'exponential' }); + }); +}); + describe('workerQueuesFor', () => { test('the configured queues first, then every queue a registered job is enqueued on', () => { expect(workerQueuesFor(['mail', 'digest'], ['default', 'mail'])).toEqual([ @@ -267,7 +312,15 @@ describe('WORKER_QUEUES — the exact queues this worker serves', () => { test('set, it replaces jobs.queues for this process and marks the set exact', () => { const config = workerConfigOf( - { jobs: { queues: ['bank-default'], concurrency: 4, visibilityTimeoutMs: 30_000 } } as never, + { + jobs: { + queues: ['bank-default'], + concurrency: 4, + visibilityTimeoutMs: 30_000, + maxAttempts: 3, + backoff: 'exponential', + }, + } as never, { [WORKER_QUEUES_ENV]: 'banks' }, ); expect(config).toEqual({ diff --git a/packages/cli/src/runtime-jobs.ts b/packages/cli/src/runtime-jobs.ts index f7074f524..b5177eb25 100644 --- a/packages/cli/src/runtime-jobs.ts +++ b/packages/cli/src/runtime-jobs.ts @@ -1,7 +1,8 @@ // The queues a `worker` serves and the slots each gets: `jobs.queues`, `jobs.concurrency`, // `jobs.maxInFlight` and `jobs.visibilityTimeoutMs` off the app's own `app.config.ts`, and `WORKER_QUEUES` off the // Deployment's env — the one per-Deployment answer, since every Deployment runs the same image and -// the same config (issues #673, #676). +// the same config (issues #673, #676). And `jobs.maxAttempts` / `jobs.backoff`: the retry of a job +// that declares none, installed for every role. import type { AppConfig, JobsConcurrency } from '@ultimat3/core'; import { @@ -11,6 +12,7 @@ import { UltimateError, } from '@ultimat3/core'; import { registeredJobs, type WorkerOptions } from '@ultimat3/jobs'; +import { installDefaultRetry, resetDefaultRetry } from '@ultimat3/jobs/adapter'; import type { Env } from './runtime-bindings'; /** The env key a worker Deployment names its queues with: `WORKER_QUEUES=banks,banks-long`. */ @@ -64,7 +66,22 @@ export function workerQueuesFromEnv(env: Env): readonly string[] | undefined { }); } +/** + * `jobs.maxAttempts` and `jobs.backoff`, installed as the retry of a job that declares none. In + * EVERY role, never the worker alone: the process that enqueues stamps the row's `max_attempts` + * from the policy the worker retries by. No config is the framework's own default again. + */ +export function installJobsRetry(config: AppConfig | undefined): void { + if (config === undefined) resetDefaultRetry(); + else installDefaultRetry({ attempts: config.jobs.maxAttempts, backoff: config.jobs.backoff }); +} + +/** + * What the boot reads of `jobs.*`, once, for whichever roles it runs — which is why the default + * retry is installed here (`installJobsRetry`) and not at the worker's start. + */ export function workerConfigOf(config: AppConfig | undefined, env: Env = {}): WorkerConfig { + installJobsRetry(config); const fromEnv = workerQueuesFromEnv(env); const base = config === undefined diff --git a/packages/cli/src/runtime-pooler.test.ts b/packages/cli/src/runtime-pooler.test.ts index 11d268ffd..0b3ffb464 100644 --- a/packages/cli/src/runtime-pooler.test.ts +++ b/packages/cli/src/runtime-pooler.test.ts @@ -40,7 +40,7 @@ const recordPools = (): { readonly urls: string[] } => { describe('startDb', () => { test('hands the boot its own DATABASE_POOLER', async () => { const pools = recordPools(); - const { client } = startDb(external, { DATABASE_POOLER: 'transaction' }); + const { client } = startDb(external, { DATABASE_POOLER: 'transaction' }, false); await client.ping(); @@ -49,10 +49,14 @@ describe('startDb', () => { test('and the replica the same answer', async () => { const pools = recordPools(); - const { replica } = startDb(external, { - DATABASE_POOLER: 'transaction', - DATABASE_REPLICA_URL: 'postgres://reader@replica:5432/app', - }); + const { replica } = startDb( + external, + { + DATABASE_POOLER: 'transaction', + DATABASE_REPLICA_URL: 'postgres://reader@replica:5432/app', + }, + false, + ); await replica?.ping(); @@ -63,7 +67,7 @@ describe('startDb', () => { test('unset sends the bounds', async () => { const pools = recordPools(); - const { client } = startDb(external, {}); + const { client } = startDb(external, {}, false); await client.ping(); @@ -71,7 +75,7 @@ describe('startDb', () => { }); test('a typo refuses the boot', () => { - expect(() => startDb(external, { DATABASE_POOLER: 'txn' })).toThrow('X_ENV_MISSING'); + expect(() => startDb(external, { DATABASE_POOLER: 'txn' }, false)).toThrow('X_ENV_MISSING'); }); }); diff --git a/packages/cli/src/runtime-queue.test.ts b/packages/cli/src/runtime-queue.test.ts index 7e279f397..6cb611bb5 100644 --- a/packages/cli/src/runtime-queue.test.ts +++ b/packages/cli/src/runtime-queue.test.ts @@ -212,11 +212,11 @@ describe('unit · which environment the boot builds its client from', () => { const services = resolveServices(ROOT, EXTERNAL); // The dangerous direction first: the process says there is a standby and the boot's own env // does not, which is what a `x jobs` run inside a shell with a stale variable looks like. - const ignored = withProcessReplica(STANDBY, () => startDb(services, { ...EXTERNAL })); + const ignored = withProcessReplica(STANDBY, () => startDb(services, { ...EXTERNAL }, false)); expect(ignored.replica).toBeUndefined(); const attached = withProcessReplica(undefined, () => - startDb(services, { ...EXTERNAL, [REPLICA_URL_ENV]: STANDBY }), + startDb(services, { ...EXTERNAL, [REPLICA_URL_ENV]: STANDBY }, false), ); expect(attached.replica).toBeDefined(); // And the ambient client is the PAIR, which is the object a repository reads through. @@ -228,11 +228,11 @@ describe('unit · which environment the boot builds its client from', () => { // `53300 too many connections for role`. test('DATABASE_POOL_MAX from the boot env caps the primary and the standby', () => { const services = resolveServices(ROOT, EXTERNAL); - const started = startDb(services, { - ...EXTERNAL, - [POOL_MAX_ENV]: '4', - [REPLICA_URL_ENV]: STANDBY, - }); + const started = startDb( + services, + { ...EXTERNAL, [POOL_MAX_ENV]: '4', [REPLICA_URL_ENV]: STANDBY }, + false, + ); expect('profile' in started.client && started.client.profile.max).toBe(4); expect(started.replica?.profile.max).toBe(4); }); @@ -254,7 +254,7 @@ describe('unit · which environment the boot builds its client from', () => { }; throw failure; }; - expect(() => startDb(services, { ...EXTERNAL }, attach)).toThrow(failure); + expect(() => startDb(services, { ...EXTERNAL }, false, attach)).toThrow(failure); expect(closing).toBeDefined(); await closing; expect(dbClientInstalled()).toBe(false); @@ -262,7 +262,7 @@ describe('unit · which environment the boot builds its client from', () => { test('an unset DATABASE_POOL_MAX keeps the role default', () => { const services = resolveServices(ROOT, EXTERNAL); - const started = startDb(services, { ...EXTERNAL }); + const started = startDb(services, { ...EXTERNAL }, false); expect('profile' in started.client && started.client.profile.max).toBeGreaterThan(4); }); }); diff --git a/packages/cli/src/runtime-queue.ts b/packages/cli/src/runtime-queue.ts index ac5a811ab..8273b0b6c 100644 --- a/packages/cli/src/runtime-queue.ts +++ b/packages/cli/src/runtime-queue.ts @@ -38,6 +38,7 @@ import { import { applyLockedSchema, ensureSchema } from './framework-schema-apply'; import { appExtensions } from './migration-extensions'; import type { DevServices } from './runtime-bindings'; +import { databaseSslOf, withRequiredTls } from './runtime-database-ssl'; import type { RuntimeOverrides } from './runtime-overrides'; import { QUEUE_PORT_BINDINGS } from './runtime-port-bindings-queue'; import { installPorts, type PortRelease, suppliedOr } from './runtime-ports'; @@ -97,10 +98,17 @@ export interface RunningQueue { export function startDb( services: DevServices, env: ReplicaEnv, + /** + * `database.ssl` (`databaseSslOf`). REQUIRED for `env`'s reason: defaulted, the switch was + * validated, documented and read by nothing, and a pool to a managed Postgres went out in clear. + */ + ssl: boolean, // A seam for the one failure after the primary exists: the standby refused at construction. attach: typeof attachReplica = attachReplica, ): StartedDb { const binding = services.db; + // The primary and the standby alike, and never over a mode the URL states (`withRequiredTls`). + const tls = (url: string): string => (ssl ? withRequiredTls(url, env) : url); // `DATABASE_POOL_MAX` from the env the boot was HANDED, for `env`'s reason below. Installing a // client here means `defaultClient()` — the only other reader — never runs in a served role, so // without this the operator's cap reached no booted process and every role ran its @@ -118,10 +126,11 @@ export function startDb( dataDir: pgliteDataDir(binding.url), extensions: () => appExtensions(services.root), }) - : postgresClient({ url: binding.url, profile, env }); + : postgresClient({ url: tls(binding.url), profile, env }); let attached: ReturnType; try { - attached = attach(client, replicaUrlFor(binding, env), profile); + const standby = replicaUrlFor(binding, env); + attached = attach(client, standby === undefined ? undefined : tls(standby), profile); } catch (error) { // The primary is built and nothing will hold it: close it here, and say so if that fails too, // without letting the close's answer replace the error the caller is handed. @@ -348,7 +357,7 @@ export async function startQueue( ) { throw poolerSessionRequired('a step that applies migrations'); } - const { client: db, replica } = startDb(services, env); + const { client: db, replica } = startDb(services, env, await databaseSslOf(services)); try { // Pay the Postgres boot here, so the first request is not the slow one and a broken database // fails at boot rather than on some later query. diff --git a/packages/cli/src/serve-boot.ts b/packages/cli/src/serve-boot.ts index 458213bb9..4a50f1f6e 100644 --- a/packages/cli/src/serve-boot.ts +++ b/packages/cli/src/serve-boot.ts @@ -30,7 +30,13 @@ import { bootTimeline } from './serve-boot-phases'; import { type BootProbe, openBootProbe } from './serve-boot-probe'; import { bootWarningConcerns, warnAtBoot } from './serve-boot-warnings'; import { loadDrainConfig, loadHealthConfig } from './serve-drain'; -import { configureReporting, containerBinding, metricsPortFor, portFromEnv } from './serve-env'; +import { + assertRoleDeclared, + configureReporting, + containerBinding, + metricsPortFor, + portFromEnv, +} from './serve-env'; import { type ListenerTls, tlsFromEnv } from './serve-env-tls'; import { adoptPrebuiltStyles, reportBootBuilds, watchBootBuilds } from './serve-prebuilt'; import type { ServedApp, ServeOptions } from './serve-types'; @@ -97,6 +103,9 @@ export async function bootServing(boot: { readonly metrics: MetricsEndpoint; }): Promise { const { options } = boot; + // Before anything is started or created: a role `app.config.ts` does not list is refused while + // there is nothing to unwind but the scrape listener. + assertRoleDeclared(boot.role, await loadAppConfig(options.root)); // The role's own grace FIRST, before the services: the schema wait runs inside them, and a worker // SIGTERMed mid-wait sat through web's readiness grace. `app.config.ts`'s `drain` section is // applied over this once the app is loaded (`bootRoles`). diff --git a/packages/cli/src/serve-env.ts b/packages/cli/src/serve-env.ts index 386ccdb56..e6f8a9294 100644 --- a/packages/cli/src/serve-env.ts +++ b/packages/cli/src/serve-env.ts @@ -1,8 +1,9 @@ -// What a container's environment decides about a boot: which role, which port, which interface, -// and where errors are reported. Split from `serve.ts`, which re-exports every name here. +// What a container's environment decides about a boot: which role (and whether the app declares +// it), which port, which interface, and where errors are reported. Split from `serve.ts`, which re-exports every name here. -import type { ErrorReporter, Role } from '@ultimat3/core'; +import type { AppConfig, ErrorReporter, Role } from '@ultimat3/core'; import { + ConfigInvalidError, chainErrorReporters, configureErrorReporting, errorReportersOf, @@ -64,6 +65,25 @@ export function roleFromEnv(env: Env): Role { return role; } +/** + * Throws `X_CONFIG_INVALID` when `role` is absent from `config.roles`. Unset, `roles` is every + * role (core's default), so an app that never wrote the key boots each one as it always did; so + * does a root with no `app.config.ts`. `migrate` is never refused: it is the release phase — run + * once, then exit — not a process the app "runs", and an app listing `['web', 'worker']` still has + * migrations to apply. + */ +export function assertRoleDeclared(role: Role, config: AppConfig | undefined): void { + if (config === undefined || role === 'migrate' || config.roles.includes(role)) return; + const declared = config.roles.map((name) => `'${name}'`); + // Every value below is a member of core's closed `ROLES` set (`defineConfig` refused the rest, + // `roleFromEnv` the env's), so none needs quoting for the shell or for TypeScript. + throw new ConfigInvalidError({ + cause: `ROLE=${role} is not a role this app declares: roles in app.config.ts lists ${config.roles.join(', ')}`, + fix: `ROLE=${config.roles.find((name) => name !== 'migrate') ?? 'web'} bun apps/web/server.ts # a declared role — or declare this one in app.config.ts: roles: [${[...declared, `'${role}'`].join(', ')}]`, + meta: { key: 'roles', role, declared: [...config.roles] }, + }); +} + /** * `Number.parseInt` would read `80abc` as 80, and `Number` reads `0x1F90` as 8080 and `8e3` as * 8000, so the whole string has to be decimal digits — a port spelled any other way is a deploy diff --git a/packages/cli/src/serve-graph-ceilings-fixture.ts b/packages/cli/src/serve-graph-ceilings-fixture.ts index c97fd56d8..3b4a1783a 100644 --- a/packages/cli/src/serve-graph-ceilings-fixture.ts +++ b/packages/cli/src/serve-graph-ceilings-fixture.ts @@ -342,8 +342,13 @@ * `db/src/not-null-contract.ts` (a required column's NOT NULL contract step). * raised 987 → 989, measured 989 (2026-11-18, a queued write's binding): `core/src/client-scope-id.ts` * (the scope id auth renders and action judges, one key) and `action/src/replay-scope.ts` (the check). + * raised 989 → 995, measured 995 (2026-11-19, r9 sweep, metafile walk): `cli/src/runtime-database-ssl.ts` + * and the `cli/src/app-config-load.ts` it reads `database.ssl` through — the migrate step opens the + * pool too, and the switch was read by nothing; `entity/src/uuid-text.ts`, `entity/src/pg-sql-in.ts` and `entity/src/instant-range.ts` (a malformed + * uuid operand and a long `in` list answered alike on both drivers) and `jobs/src/retry-default.ts` + * (`jobs.maxAttempts`/`jobs.backoff` as the worker's default retry). */ -export const MIGRATE_CEILING = 989; +export const MIGRATE_CEILING = 995; // One import site for the test, which reads both pins from here. export { SERVING_ROLE_CEILING } from './serve-graph-serving-ceiling-fixture'; diff --git a/packages/cli/src/serve-graph-serving-ceiling-fixture.ts b/packages/cli/src/serve-graph-serving-ceiling-fixture.ts index 23d279388..288850ff2 100644 --- a/packages/cli/src/serve-graph-serving-ceiling-fixture.ts +++ b/packages/cli/src/serve-graph-serving-ceiling-fixture.ts @@ -339,5 +339,10 @@ * raised 1547 → 1548, measured 1548 (2026-11-19, multi-agent DX): `cli/src/port-pair-free.ts`, so * the sync role's `X_PORT_IN_USE` names a pair that is free when asked, as `x doctor`'s fix does. * The fork check that also arrived (three modules) went to `@ultimat3/db/schema-dump` instead. + * raised 1548 → 1556, measured 1556 (2026-11-19, r9 sweep, metafile walk): the five new on + * `MIGRATE_CEILING` (`app-config-load.ts` was already here), `cli/src/runtime-cache-ttl.ts` + * (`cache.defaultTtlMs` refused under its own key), `cli/src/role-select.ts` (`--role`'s reading, + * split from `role-start.ts` at the line ceiling) and `auth/src/mfa-handoff.ts` (an SSO callback + * hands an MFA-enrolled user their challenge). */ -export const SERVING_ROLE_CEILING = 1548; +export const SERVING_ROLE_CEILING = 1556; diff --git a/packages/cli/src/serve-graph-web-ceiling-fixture.ts b/packages/cli/src/serve-graph-web-ceiling-fixture.ts index 6b5ffbd32..a1a35cf88 100644 --- a/packages/cli/src/serve-graph-web-ceiling-fixture.ts +++ b/packages/cli/src/serve-graph-web-ceiling-fixture.ts @@ -299,5 +299,7 @@ * and `action/src/replay-scope.ts`, the scope id and the check that compares it. * raised 1747 → 1748, measured 1748 (2026-11-19, multi-agent DX): the one on * `SERVING_ROLE_CEILING`, `cli/src/port-pair-free.ts`. + * raised 1748 → 1756, measured 1756 (2026-11-19, r9 sweep): the eight on `SERVING_ROLE_CEILING`. + * Nothing web-only. */ -export const WEB_ROLE_CEILING = 1748; +export const WEB_ROLE_CEILING = 1756; diff --git a/packages/cli/src/serve.test.ts b/packages/cli/src/serve.test.ts index f10adad5a..98522c9e3 100644 --- a/packages/cli/src/serve.test.ts +++ b/packages/cli/src/serve.test.ts @@ -6,12 +6,14 @@ import { errorGroupsSink, memoryErrorGroupsStore } from '@ultimat3/admin/error-g import type { ErrorReport } from '@ultimat3/core'; import { chainErrorReporters, + defineConfig, errorReportersOf, InternalError, installedErrorReporter, isSentryErrorReporter, logger, memoryErrorReporter, + ROLES, reportError, resetErrorReporting, sentryErrorReporter, @@ -21,6 +23,7 @@ import { installErrorReporter } from '@ultimat3/core/adapter'; import { DEFAULT_METRICS_PORT } from './metrics-endpoint'; import { processRoot } from './process-root-fixture'; import { + assertRoleDeclared, CONTAINER_BINDING, configureReporting, containerBinding, @@ -33,6 +36,7 @@ import { releaseBoot, roleFromEnv, runRole, + serveApp, withAppRuntime, } from './serve'; import type { ThrownShape } from './thrown-by-fixture'; @@ -321,3 +325,43 @@ test('a release that itself fails does not strand the ones acquired before it', // The step that refused to START is the failure worth reporting; a stop on the way out is not. expect(released).toEqual(['roles', 'services']); }); + +// `roles` was validated (a closed set, never empty), documented as "which runtime roles this app +// runs", and read by nothing: an app declaring `roles: ['web']` booted a worker all the same. +test('a ROLE outside config.roles refuses to boot', async () => { + const root = processRoot(join(import.meta.dir, '..', '.serve-roles-fixture')); + await rm(root, { recursive: true, force: true }); + try { + await Bun.write( + join(root, 'app.config.ts'), + "export const config = { name: 'roles-fixture', roles: ['web', 'sync'] };\n", + ); + const env = { NODE_ENV: 'test', ULTIMATE_STATE_DIR: join(root, '.x') }; + const refused = await serveApp({ root, env, role: 'worker', port: 0, metricsPort: 0 }).then( + () => expect.unreachable('a role the app does not declare booted'), + (error: unknown) => error as ThrownShape, + ); + expect(refused.code).toBe('X_CONFIG_INVALID'); + expect(refused.cause).toContain('ROLE=worker'); + expect(refused.cause).toContain('web, sync'); + // Either remedy, each pasteable: declare the role, or start one that is declared. + expect(refused.fix).toContain("roles: ['web', 'sync', 'worker']"); + expect(refused.fix).toContain('ROLE=web bun apps/web/server.ts'); + // Refused before a single service: no state directory was created under the root. + expect(await Bun.file(join(root, '.x')).exists()).toBe(false); + } finally { + await rm(root, { recursive: true, force: true }); + } +}); + +test('config.roles unset declares every role, and the release phase is never a declared process', () => { + const unset = defineConfig({ name: 'roles-default' }); + for (const role of ROLES) assertRoleDeclared(role, unset); + // No app.config.ts at all: nothing was declared, so nothing is refused. + for (const role of ROLES) assertRoleDeclared(role, undefined); + const webOnly = defineConfig({ name: 'roles-web', roles: ['web'] }); + assertRoleDeclared('web', webOnly); + // `migrate` runs once and exits (`x db migrate`, the release phase): `roles` lists what RUNS. + assertRoleDeclared('migrate', webOnly); + expect(thrownBy(() => assertRoleDeclared('scheduler', webOnly)).code).toBe('X_CONFIG_INVALID'); +}); diff --git a/packages/cli/src/serve.ts b/packages/cli/src/serve.ts index 6bf979fa7..4873425e1 100644 --- a/packages/cli/src/serve.ts +++ b/packages/cli/src/serve.ts @@ -20,6 +20,7 @@ import { containerBinding, metricsPortFor, portFromEnv, roleFromEnv } from './se import type { MigratedApp, ServedApp, ServeOptions, StartedApp } from './serve-types'; export { + assertRoleDeclared, CONTAINER_BINDING, configureReporting, containerBinding, diff --git a/packages/core/src/client-stream.test.ts b/packages/core/src/client-stream.test.ts index 90b0fd70f..8ab66c453 100644 --- a/packages/core/src/client-stream.test.ts +++ b/packages/core/src/client-stream.test.ts @@ -56,6 +56,35 @@ describe('clientStream', () => { expect(() => wire.end()).toThrow(); }); + test('a done frame with a dates: line returns a Date; one without returns the string unchanged', async () => { + const at = '2026-01-02T03:04:05.678Z'; + const answer = { at: new Date(at), note: at }; + const read = async (frame: string): Promise => { + const wire = held(); + const stream = clientStream({ + url: '/api/words/say', + body: {}, + fetchImpl: () => Promise.resolve(wire.response), + }); + const done = stream.next(); + wire.push(frame); + return (await done).value; + }; + const data = JSON.stringify(answer); + const marked = await read(`event: done\ndates: ${wireDatePaths(answer)}\ndata: ${data}\n\n`); + expect(marked).toEqual(answer); + expect((marked as { at: unknown }).at).toBeInstanceOf(Date); + // New client, old server: no marker, so nothing is guessed from the look of a string. + expect(await read(`event: done\ndata: ${data}\n\n`)).toEqual({ at, note: at }); + // A marker belongs to its own frame: a chunk's never reaches the done frame after it. + expect( + takeFrames('event: chunk\ndates: x\ndata: 1\n\nevent: done\ndata: 2\n\n').frames, + ).toEqual([ + { event: 'chunk', data: '1', dates: 'x' }, + { event: 'done', data: '2' }, + ]); + }); + test('an error frame is thrown as the coded problem it carries', async () => { const wire = held(); const stream = clientStream({ url: '/x', fetchImpl: () => Promise.resolve(wire.response) }); diff --git a/packages/core/src/client-stream.ts b/packages/core/src/client-stream.ts index 5347b6ec2..ac0cb161d 100644 --- a/packages/core/src/client-stream.ts +++ b/packages/core/src/client-stream.ts @@ -11,7 +11,7 @@ import { settleAnswer } from './client-transport'; import { notifyClientWrite } from './client-writes'; import { RECORDS_HEADER } from './record-envelope'; import { pageClient } from './record-sink'; -import { DATES_HEADER } from './wire-dates'; +import { DATES_HEADER, reviveWireDates } from './wire-dates'; /** What `clientStream` reads: a write's request, never a raw body or a flight. */ export type StreamRequest = StreamDispatch; @@ -19,6 +19,8 @@ export type StreamRequest = StreamDispatch; interface Frame { readonly event: string; readonly data: string; + /** The `x-ultimate-dates` value for this frame's data, when the server named any. */ + readonly dates?: string; } /** Splits a growing buffer into complete frames; the incomplete tail is handed back. */ @@ -28,14 +30,19 @@ export function takeFrames(buffer: string): { readonly frames: Frame[]; readonly const rest = blocks.pop() ?? ''; for (const block of blocks) { let event = 'message'; + let dates: string | undefined; const data: string[] = []; for (const line of block.split(/\r?\n/)) { // A `:` line is a comment — the server's keep-alive. if (line.startsWith(':')) continue; if (line.startsWith('event:')) event = line.slice(6).trim(); + else if (line.startsWith('dates:')) dates = line.slice(6).trim(); else if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, '')); } - if (data.length > 0) frames.push({ event, data: data.join('\n') }); + if (data.length > 0) { + const text = data.join('\n'); + frames.push(dates === undefined ? { event, data: text } : { event, data: text, dates }); + } } return { frames, rest }; } @@ -71,7 +78,8 @@ export async function* clientStream( buffer = taken.rest; for (const frame of taken.frames) { if (frame.event === 'chunk') yield JSON.parse(frame.data) as TChunk; - else if (frame.event === 'done') return JSON.parse(frame.data) as TOutput; + else if (frame.event === 'done') + return reviveWireDates(JSON.parse(frame.data), frame.dates ?? null) as TOutput; else if (frame.event === 'error') { const status = problemStatus(frame.data); throw ( diff --git a/packages/core/src/config-defaults.ts b/packages/core/src/config-defaults.ts index 4d4db771a..2b3016558 100644 --- a/packages/core/src/config-defaults.ts +++ b/packages/core/src/config-defaults.ts @@ -46,7 +46,9 @@ export function configDefaults(): Omit { jobs: { queues: ['default'], concurrency: JOBS_CONCURRENCY_DEFAULT, - maxAttempts: 5, + // 3 is `@ultimat3/jobs`' own default retry: the key is the worker's default for a job that + // declares none, so the default moves no app that never set it. + maxAttempts: 3, backoff: 'exponential', visibilityTimeoutMs: 30_000, doneRetentionMs: JOBS_DONE_RETENTION_MS_DEFAULT, diff --git a/packages/core/src/config-sections.test.ts b/packages/core/src/config-sections.test.ts index a9066d89d..d92ac6d7d 100644 --- a/packages/core/src/config-sections.test.ts +++ b/packages/core/src/config-sections.test.ts @@ -75,6 +75,8 @@ describe('every numeric key is screened', () => { ['jobs.maxAttempts', { jobs: { maxAttempts: 0 } }, 0], ['jobs.visibilityTimeoutMs', { jobs: { visibilityTimeoutMs: Number.NaN } }, Number.NaN], ['jobs.visibilityTimeoutMs', { jobs: { visibilityTimeoutMs: 0 } }, 0], + // 0 passed here and crashed the boot: the cache rungs refuse a lease of no length. + ['cache.defaultTtlMs', { cache: { defaultTtlMs: 0 } }, 0], ['cache.defaultTtlMs', { cache: { defaultTtlMs: -1 } }, -1], ['cache.defaultTtlMs', { cache: { defaultTtlMs: 1.5 } }, 1.5], ['cache.defaultTtlMs', { cache: { defaultTtlMs: '60s' } }, '60s'], @@ -89,7 +91,7 @@ describe('every numeric key is screened', () => { defineConfig({ name: 'app', jobs: { concurrency: 1, maxAttempts: 1, visibilityTimeoutMs: 1 }, - cache: { defaultTtlMs: 0 }, + cache: { defaultTtlMs: 1 }, }), ).not.toThrow(); }); diff --git a/packages/core/src/config.test.ts b/packages/core/src/config.test.ts index 28e6eaf80..cb08c982c 100644 --- a/packages/core/src/config.test.ts +++ b/packages/core/src/config.test.ts @@ -42,8 +42,8 @@ describe('defineConfig', () => { ); expect(config.jobs.concurrency).toBe(32); - // untouched keys still come from defaults - expect(config.jobs.maxAttempts).toBe(5); + // untouched keys still come from defaults — 3, the retry a job declaring none has always had + expect(config.jobs.maxAttempts).toBe(3); expect(config.realtime.maxSocketsPerActor).toBe(4); expect(config.roles).toEqual(['web', 'worker']); }); diff --git a/packages/core/src/config.ts b/packages/core/src/config.ts index b01fb47ef..44bd7b048 100644 --- a/packages/core/src/config.ts +++ b/packages/core/src/config.ts @@ -108,6 +108,7 @@ const DATABASE_DRIVERS = ['postgres'] as const; export interface DatabaseConfig { readonly driver: (typeof DATABASE_DRIVERS)[number]; + /** `true` requires TLS when the URL states no `sslmode`; a URL's own `sslmode` is never overridden. */ readonly ssl: boolean; /** * Every `tenant:` table carries a forced policy (`x db gen`) the serving role must be subject to @@ -137,6 +138,7 @@ export interface DatabaseConfig { * exist is `cache.tiers` and only that; a rung the environment cannot supply refuses the boot. */ export interface CacheConfig { + /** At least 1: the rungs refuse a lease of no length, so 0 is refused here rather than at boot. */ readonly defaultTtlMs: number; /** Order is fixed by `CACHE_TIERS`; listing order here selects rungs, it does not rank them. */ readonly tiers: readonly CacheTierName[]; @@ -168,6 +170,7 @@ export interface JobsConfig { * `maxInFlight`), the per-queue `concurrency` still bounding each under it. Unset: no process cap. */ readonly maxInFlight?: number | undefined; + /** With `backoff`: the retry of a job that declares none. A job's own `retry` wins. */ readonly maxAttempts: number; readonly backoff: (typeof JOB_BACKOFFS)[number]; readonly visibilityTimeoutMs: number; @@ -308,7 +311,7 @@ function validate(config: AppConfig): void { config.jobs[key] === undefined ? undefined : countIssue(`jobs.${key}`, config.jobs[key], 1), ), oneOfIssue('jobs.backoff', config.jobs.backoff, JOB_BACKOFFS), - countIssue('cache.defaultTtlMs', config.cache.defaultTtlMs, 0), + countIssue('cache.defaultTtlMs', config.cache.defaultTtlMs, 1), oneOfIssue('database.driver', config.database.driver, DATABASE_DRIVERS), booleanIssue('database.ssl', config.database.ssl), booleanIssue('database.rowSecurity', config.database.rowSecurity), diff --git a/packages/core/src/locale-direction.test.ts b/packages/core/src/locale-direction.test.ts new file mode 100644 index 000000000..6a332fbdd --- /dev/null +++ b/packages/core/src/locale-direction.test.ts @@ -0,0 +1,37 @@ +// Direction is the SCRIPT's: a tag that names its script is answered by it, and only a tag that +// names none falls back to the language's usual one. + +import { describe, expect, test } from 'bun:test'; +import { directionOf, isRtl } from './locale-direction'; + +describe('directionOf', () => { + test('a language written right-to-left by default is rtl, with or without a region', () => { + for (const tag of ['ar', 'ar-EG', 'he-IL', 'fa', 'ur-PK', 'ckb', 'AR-eg']) { + expect(directionOf(tag)).toBe('rtl'); + } + for (const tag of ['en', 'de-DE', 'ja', 'zh-Hant-TW']) expect(directionOf(tag)).toBe('ltr'); + }); + + test('an explicit script subtag decides direction', () => { + // Was read off the language alone: Azerbaijani in Arabic script rendered ltr, and Kashmiri in + // Devanagari or Sindhi in Latin rendered rtl. + for (const tag of ['az-Arab', 'az-Arab-IR', 'pa-Arab-PK', 'uz-arab', 'ku-Arab-IQ', 'yi-Hebr']) { + expect(isRtl(tag)).toBe(true); + } + for (const tag of ['ks-Deva', 'sd-Deva-IN', 'ar-Latn', 'ug-Cyrl', 'fa-latn', 'az-Latn-AZ']) { + expect(isRtl(tag)).toBe(false); + } + }); + + test('ku with no script is Kurmanji in Latin, ltr; Sorani (ckb) stays rtl', () => { + expect(directionOf('ku')).toBe('ltr'); + expect(directionOf('ku-TR')).toBe('ltr'); + expect(directionOf('ckb-IQ')).toBe('rtl'); + }); + + test('a four-letter REGION-position word is only a script in second place', () => { + // `ar-EG-x-arab`-style private use or a variant never overrides the language. + expect(directionOf('en-US-x-arab')).toBe('ltr'); + expect(directionOf('')).toBe('ltr'); + }); +}); diff --git a/packages/core/src/locale-direction.ts b/packages/core/src/locale-direction.ts index aa2743bc8..845b2e657 100644 --- a/packages/core/src/locale-direction.ts +++ b/packages/core/src/locale-direction.ts @@ -8,8 +8,10 @@ export type Direction = 'ltr' | 'rtl'; /** - * Right-to-left scripts, by primary subtag. A static CLDR-derived set rather than - * `Intl.Locale.prototype.getTextInfo` so direction is deterministic across runtimes. + * Languages whose usual script is right-to-left, by primary subtag: what a tag naming no script + * falls back to. A static CLDR-derived set rather than `Intl.Locale.prototype.getTextInfo` so + * direction is deterministic across runtimes. No `ku`: CLDR's likely script for it is Latin + * (Kurmanji); Sorani is `ckb`, and Kurdish in Arabic script says so (`ku-Arab`). */ const RTL_LOCALES: ReadonlySet = new Set([ 'ar', @@ -19,7 +21,6 @@ const RTL_LOCALES: ReadonlySet = new Set([ 'fa', 'he', 'ks', - 'ku', 'nqo', 'ps', 'sd', @@ -28,9 +29,26 @@ const RTL_LOCALES: ReadonlySet = new Set([ 'yi', ]); +/** ISO 15924 right-to-left scripts in living use, lower-cased. */ +const RTL_SCRIPTS: ReadonlySet = new Set([ + 'adlm', + 'arab', + 'hebr', + 'mand', + 'nkoo', + 'rohg', + 'samr', + 'syrc', + 'thaa', +]); + +/** + * A script subtag is four letters in second place (BCP 47), and when a tag names one it decides: + * `az-Arab` is rtl and `ks-Deva` ltr, whatever the language usually writes. + */ export function isRtl(locale: string): boolean { - const primary = locale.split('-')[0]?.toLowerCase() ?? ''; - return RTL_LOCALES.has(primary); + const [primary = '', second = ''] = locale.toLowerCase().split('-'); + return /^[a-z]{4}$/.test(second) ? RTL_SCRIPTS.has(second) : RTL_LOCALES.has(primary); } export function directionOf(locale: string): Direction { diff --git a/packages/db/README.md b/packages/db/README.md index 2d0b3666d..9b6660eee 100644 --- a/packages/db/README.md +++ b/packages/db/README.md @@ -46,7 +46,7 @@ await withTransaction(async (tx) => { | `completeTransaction()` / `refuseAbandoned()` | `As of 2026-11-02`: the mark that takes the open root's statements and COMMIT past an abandoned scope (a keyed action's), and the check for a write that goes through no `DbTx` (`@ultimat3/entity`'s `writing()`, the enqueue facade) → [Transactions that end badly](#transactions-that-end-badly) | | `liveTxConnection()` | the connection of the transaction still **open** on this async context, or `undefined`. `currentTx()` keeps answering a finished scope's handle to a promise chain the body forgot to await; this is the one that says whether a statement sent now is really inside a transaction. `@ultimat3/action` reads it before binding an idempotency settlement to a commit | | `sqlState()` / `isRetryableState()` / `SQLSTATE` | `As of 2026-08`: the SQLSTATE a driver error carries, and the closed table from it to a code. `Bun.SQL` puts it on `errno`; PGlite puts it on `code`; **one** reader answers for both | -| `migrate()` / `rollback()` / `readLedger()` | the `x_migrations` ledger | +| `migrate()` / `rollback()` / `readLedger()` | the `x_migrations` ledger. `rollback({ steps })` reverses the most recently **applied** migrations (`applied_at`, then id, both descending), `As of 2026-11-19` — not the highest ids: a branch merged late applies an older id after a newer one, and is the first undone | | `ledgerAheadOfBuild()` / `ROLLBACK_ALLOW_DESTRUCTIVE_ENV` | `As of 31.30`: the ledger split when it is exactly a rollback onto a newer build's schema (every unknown row newer than the newest shipped, nothing pending), else `undefined` and `auditLedger` refuses it; a destructive row ahead throws `X_MIGRATION_ROLLBACK_DESTRUCTIVE` unless named in the variable. `migrate()`'s own first step, exported so `x db status` judges a ledger as `x db migrate` will | | `statementsOf()` | `As of 2026-08`: a SQL script → the statements a driver sends one at a time. One send is one statement, so `migrate()` splits with this — a `;` inside a literal, an identifier, a dollar-quoted body or a comment is data | | `withReplicaReads()` | `As of 2026-08-24`: the scope inside which a plain read may be served by a replica — until it writes, after which every read in it is the primary's. No scope open, nothing routes | diff --git a/packages/db/src/migrate.ts b/packages/db/src/migrate.ts index 78f0d84fb..0b3abd31c 100644 --- a/packages/db/src/migrate.ts +++ b/packages/db/src/migrate.ts @@ -24,6 +24,7 @@ import { migrationChecksum, pendingMigrations, readLedger, + rollbackTargets, } from './migration-ledger'; import { applyMigrationStep } from './migration-step'; import { poolProfileFor } from './pool-profile'; @@ -310,7 +311,10 @@ export async function migrate(options: MigrateOptions): Promise export interface RollbackOptions { readonly migrations: readonly Migration[]; readonly client?: DbClient | undefined; - /** How many applied migrations to reverse, newest first. A positive integer; defaults to 1. */ + /** + * How many applied migrations to reverse, most recently applied first (not highest id). A + * positive integer; defaults to 1. + */ readonly steps?: number | undefined; /** * Skip the advisory lock, for a database only this process can reach — a branch, a test. No @@ -325,7 +329,10 @@ export interface RollbackOptions { readonly lockRetries?: number | undefined; } -/** Reverse the newest `steps` applied migrations. `x db rollback`. */ +/** + * Reverse the `steps` most recently APPLIED migrations — by `applied_at`, not by id, so a migration + * merged late is the first undone (`rollbackTargets`). `x db rollback`. + */ export async function rollback(options: RollbackOptions): Promise { const client = options.client ?? baseClient(); const steps = options.steps ?? 1; @@ -345,10 +352,11 @@ export async function rollback(options: RollbackOptions): Promise { const ledger = await readLedger(session); - const targets = [...ledger].reverse().slice(0, steps); + const targets = rollbackTargets(ledger, steps); - // The same deliberate loop as `migrate`, read backwards: one transaction per `down`, newest - // first, so a `down` that fails leaves every migration before it still applied and recorded. + // The same deliberate loop as `migrate`, read backwards: one transaction per `down`, most + // recently applied first, so a `down` that fails leaves every migration applied before it + // still applied and recorded. return expectedQueryLoop( 'each migration reverses in its own transaction, newest first, so a failure stops exactly there', async () => { diff --git a/packages/db/src/migration-ledger.ts b/packages/db/src/migration-ledger.ts index 19c802bed..5d51991bd 100644 --- a/packages/db/src/migration-ledger.ts +++ b/packages/db/src/migration-ledger.ts @@ -189,6 +189,26 @@ function conflictFix(row: LedgerRow): string { ); } +/** + * The `steps` rows a rollback reverses: the most recently APPLIED first, never the highest id. A + * branch merged late applies an older id after a newer one, and reversing by id then undoes the + * previous release's migration while the one just shipped stays applied. Rows sharing an + * `applied_at` (one run on a coarse clock, a restored dump) fall back to id descending, which is + * one run read backwards: a run applies in id order. Every ledger any release wrote has the column + * (`not null default now()`); a value no driver could parse ties rather than guessing an order. + */ +export function rollbackTargets(ledger: readonly LedgerRow[], steps: number): readonly LedgerRow[] { + // `applied_at` is typed as text but a driver hands back a `Date`: both construct one. + const at = (row: LedgerRow): number => new Date(row.applied_at).getTime(); + return [...ledger] + .sort((a, b) => { + const later = at(b) - at(a); + if (later > 0 || later < 0) return later; + return a.id < b.id ? 1 : a.id > b.id ? -1 : 0; + }) + .slice(0, steps); +} + export function pendingMigrations( ledger: readonly LedgerRow[], migrations: readonly Migration[], diff --git a/packages/db/src/rollback-order-embedded.test.ts b/packages/db/src/rollback-order-embedded.test.ts new file mode 100644 index 000000000..c9fb110c8 --- /dev/null +++ b/packages/db/src/rollback-order-embedded.test.ts @@ -0,0 +1,82 @@ +// Which migration `rollback()` reverses, on the real embedded engine: the most recently APPLIED, +// never the highest id. A branch merged late applies an older id after a newer one; reversing by +// id then drops the previous release's table while the migration just shipped stays applied. + +import { afterAll, beforeEach, describe, expect, test } from 'bun:test'; +import { LEDGER_TABLE, type Migration, migrate, rollback } from './migrate'; +import { pgliteClient } from './pglite'; +import { raw, sql } from './sql'; + +const PGLITE_BOOT_MS = 30_000; + +const table = (id: string, name: string): Migration => ({ + id, + name, + up: `create table "${name}" ("id" int primary key)`, + down: `drop table "${name}"`, +}); + +/** Released first, with the higher id. */ +const released = table('20260102000000_released', 'order_released'); +/** A branch written earlier, merged and applied after `released`. */ +const lateMerge = table('20260101000000_late_merge', 'order_late_merge'); + +describe('rollback order on the real embedded database', () => { + const client = pgliteClient(); + + const exists = async (name: string): Promise => + ( + await client.one<{ n: number }>( + sql`select count(*)::int as n from pg_tables where tablename = ${name}`, + ) + )?.n === 1; + + // The test clock is frozen and PGlite's `now()` reads it, so every row would share one instant: + // each release's apply time is stamped the way a week between deploys would have written it. + const stamp = async (id: string, appliedAt: string): Promise => { + await client.execute( + sql`update ${raw(LEDGER_TABLE)} set applied_at = ${appliedAt}::timestamptz where id = ${id}`, + ); + }; + + beforeEach(async () => { + await client.execute(raw(`drop table if exists ${LEDGER_TABLE}`)); + await client.execute(sql`drop table if exists order_released`); + await client.execute(sql`drop table if exists order_late_merge`); + }, PGLITE_BOOT_MS); + + afterAll(async () => { + await client.close(); + }); + + test( + 'rollback reverses the most recently applied migration, not the highest id, after an out-of-order apply', + async () => { + await migrate({ migrations: [released], appVersion: 'v1', client }); + await stamp(released.id, '2026-01-02T00:00:00Z'); + await migrate({ migrations: [lateMerge, released], appVersion: 'v2', client }); + await stamp(lateMerge.id, '2026-01-09T00:00:00Z'); + + expect(await rollback({ migrations: [lateMerge, released], client })).toEqual([lateMerge.id]); + expect(await exists('order_late_merge')).toBe(false); + expect(await exists('order_released')).toBe(true); + }, + PGLITE_BOOT_MS, + ); + + // One run applies in id order, and two of its rows can carry one `applied_at` (a coarse clock, a + // ledger restored from a dump): the tiebreak must still read the run backwards. + test( + 'rows sharing one applied_at reverse highest id first, as one run applied them', + async () => { + await migrate({ migrations: [lateMerge, released], appVersion: 'v1', client }); + await client.execute(raw(`update ${LEDGER_TABLE} set applied_at = '2026-01-03T00:00:00Z'`)); + + expect(await rollback({ migrations: [lateMerge, released], client, steps: 2 })).toEqual([ + released.id, + lateMerge.id, + ]); + }, + PGLITE_BOOT_MS, + ); +}); diff --git a/packages/entity/CLAUDE.md b/packages/entity/CLAUDE.md index cf90f192b..db88dda06 100644 --- a/packages/entity/CLAUDE.md +++ b/packages/entity/CLAUDE.md @@ -34,6 +34,11 @@ A rule marked `†` has its full text in [`docs/history/entity-rules.md`](../../ - **A numeric key has one spelling** (`keyOf`): batches, conflict targets and memory's uniques. **A null test on a whole money property reads `

.minor`; any other predicate on it, or an unknown operator, is refused at plan time (`predicate-screen.ts`).** Why: `docs/history/entity.md` (31.0.0). - **A PREDICATE's meaning is decided by the column's KIND** (`memory-match.ts`; `compareByKind` / `sameValueOfKind` exported for query); ONE numeric comparison, `numericOrder`; `LIKE` never a regex. † +- **An operand Postgres would refuse is decided in `operandFor`, never bound** (`As of 2026-11`): text + that is no uuid equals no row (`equalsNoValue`, `uuid-text.ts`); `like` is text/char/bytea only; an + instant crosses in years 0001–9999 (writes too, `instant-range.ts` — never on read); an `in` list + ≥ `IN_LIST_AS_ARRAY_FROM` is one array bind (`pg-sql-in.ts`). `readByIds` isolates a class-22 id. +- **`avg` is `averageSql`** — `averageDecimalText`'s integer arithmetic; never `round(avg())`. - **The Postgres driver is proved against a real Postgres** (`pg-driver.live.test.ts`, skipped without `TEST_DATABASE_URL`). A new operator, kind or write path is not done until it round-trips. - **A repository call rejects, never throws synchronously** (`tableFor`'s writes are `async`). diff --git a/packages/entity/README.md b/packages/entity/README.md index 9cee5b478..917354c96 100644 --- a/packages/entity/README.md +++ b/packages/entity/README.md @@ -519,7 +519,7 @@ visibility, never its page. |---|---| | Never a float | `sum`/`avg` answer decimal **text** whatever the column was (the sum of a million `integer` rows is not an `integer`, and `Number()` past 2^53 loses digits); money answers `MoneyValue` in integer minor units; `min`/`max` answer the row's own type | | Empty set | `null` in every function, which is what SQL answers — a `0` would claim rows were seen. `count()` is `0`, and that is the distinction | -| `avg` | one fixed scale (6 digits), rounded half away from zero from the exact rational, so both drivers land on one number | +| `avg` | one fixed scale (6 digits), rounded half away from zero from the exact rational, so both drivers land on one number — at any magnitude: Postgres' own `avg(bigint)` keeps about sixteen significant digits, so the statement does the integer arithmetic itself (`averageSql`, `As of 2026-11`) | | Refused | `min`/`max` on `text` (ordering is the database's collation there and JS code-unit order here); `avg` over money (every answer would be a silent rounding of a fraction of a minor unit — `sum()` and `count()` instead, dividing where the rounding is a decision); an amount covering more than one currency **or scale**; a money total past ±2^53 minor units | | `approximateCount()` | `reltuples` out of `pg_class`, constant time, because `count(*)` walks every visible row and no index can make it cheaper. The whole **table** — a filtered chain, every tenant-scoped entity and every soft-deleting one (`reltuples` counts the deleted rows) are `X_APPROXIMATE_COUNT_FILTERED`, and `null` means the table has never been analysed | @@ -540,9 +540,13 @@ An operand is read by the column's kind, once for both drivers (`predicate-opera | `timestamp()` | a `Date` or ISO text with `Z`/an offset | compared as that instant | | `timestamp()` | zoneless ISO text (`'2026-01-01'`, `'2026-01-01T10:00'`) | read as UTC in both drivers, never the server's `TimeZone` | | `timestamp()` | a number | `X_INVARIANT_VIOLATED` — epoch milliseconds are no instant Postgres parses | +| `timestamp()` | a `Date` outside years 0001–9999, or text in year `0000` | `X_INVARIANT_VIOLATED` — Postgres reads an instant as ISO text with a four-digit year. A write is refused the same way, at its entry; a row the server already holds outside the range still reads (`As of 2026-11`) | | `date()` | a `Date` | its UTC calendar date (`plainDateUtc`), as `$parse` writes one | | `integer()` / `bigint()` | a fraction (`1.5`, `'1.5'`, `'1e1'`) | `X_INVARIANT_VIOLATED` — round it to the bound you mean | -| `integer()` / `bigint()` / `decimal()` | any `like` | `X_INVARIANT_VIOLATED` — a number is matched by range | +| every kind but `text()` / `char()` / `bytes()` | any `like` | `X_INVARIANT_VIOLATED` — a pattern matches text; a number is matched by range, a `uuid`, `boolean`, instant, date, `jsonb` or array by value (`As of 2026-11`) | +| `uuid()` | any spelling Postgres parses — upper case, no hyphens, `{braces}` | the one value it names, in `eq`/`neq`/`in`, `findById` and a batched lookup | +| `uuid()` | text that is no uuid, under `eq`/`neq`/`in` | a value no row equals: `eq`/`in` match nothing, `neq` every row; `findById` is `null`, `update`/`delete` are `X_NOT_FOUND` — never `22P02`. It is not bound, so the statement reads `1 = 0` (`As of 2026-11`) | +| any | an `in` list of 32,768 values or more | one array parameter (`= any($1)`) on Postgres, so a list past the 65,535-bind limit answers. `bytes()`, `json()` and `arrayOf()` have no array form: past 65,535 values they are `X_INVARIANT_VIOLATED` in both drivers (`As of 2026-11`) | | `arrayOf()` | a list, under `eq`/`neq`/`in` | element by element, in order (`array_eq`) | ## A predicate tree: `andWhereNode` diff --git a/packages/entity/src/aggregate.ts b/packages/entity/src/aggregate.ts index 72f5b2b41..deb4f5028 100644 --- a/packages/entity/src/aggregate.ts +++ b/packages/entity/src/aggregate.ts @@ -159,9 +159,10 @@ export const sumDecimalText = (values: readonly string[]): string | null => { }; /** - * `sum / count`, rounded half away from zero at `AVG_SCALE` — which is what Postgres' `round()` - * does to a `numeric`, and the reason the statement asks for `round(avg(...), 6)` rather than the - * server's own default scale: two drivers rounding at different places answer two numbers. + * `sum / count`, rounded half away from zero at `AVG_SCALE`. The statement spells the same integer + * arithmetic (`averageSql`, `pg-sql-aggregate.ts`) rather than taking the server's own scale: two + * drivers rounding at different places answer two numbers, and `avg(bigint)` past sixteen digits + * rounds at none. */ export const averageDecimalText = (total: string | null, count: number): string | null => { if (total === null || count === 0) return null; diff --git a/packages/entity/src/batch-key-spelling.test.ts b/packages/entity/src/batch-key-spelling.test.ts index df9461149..7bcf27671 100644 --- a/packages/entity/src/batch-key-spelling.test.ts +++ b/packages/entity/src/batch-key-spelling.test.ts @@ -90,6 +90,17 @@ describe('postgres · a key the column cannot hold', () => { await pglite.close(); }); + test('one key the column cannot hold fails alone: the lookups batched with it still answer', async () => { + const repo = postgresRepo(bigs, { client: pglite }); + const settled = await inRequest(() => + Promise.allSettled([repo.findById('7'), repo.findById('abc'), repo.findById('8')]), + ); + expect(settled.map((result) => result.status)).toEqual(['fulfilled', 'rejected', 'fulfilled']); + expect(settled[0]).toMatchObject({ value: { label: 'big' } }); + expect(settled[1]).toMatchObject({ reason: { code: 'X_DB_STATEMENT_FAILED' } }); + expect(settled[2]).toMatchObject({ value: null }); + }); + test("a key the column cannot hold is the server's own refusal", async () => { const repo = postgresRepo(bigs, { client: pglite }); const refused = await inRequest(() => repo.findById('abc')).catch((error: unknown) => error); diff --git a/packages/entity/src/batch-read.ts b/packages/entity/src/batch-read.ts index a059c7e7b..25bd8a1b2 100644 --- a/packages/entity/src/batch-read.ts +++ b/packages/entity/src/batch-read.ts @@ -3,12 +3,13 @@ // answers them. The microtask coalescer and the sibling-aware preload both read ids through here, // so the two can never disagree about when a shared statement is legal. -import type { DbClient } from '@ultimat3/db'; +import { type DbClient, sqlState } from '@ultimat3/db'; import type { EntityCore } from './entity'; import { canonicalDecimal, canonicalInteger } from './numeric-compare'; import { decodeRow, type PhysicalRow } from './pg-row'; import { type ReadShape, selectStatement } from './pg-sql'; import type { QueryPlan } from './tenancy'; +import { canonicalUuid } from './uuid-text'; /** * Postgres binds at most 65535 parameters, so a batch wider than this becomes several statements @@ -36,14 +37,15 @@ export type Answer = { readonly row: unknown } | { readonly error: unknown }; * The string both sides of a batch are filed under — the requested id, and the key of a row that * came back. Postgres compares a `uuid` as a value and prints it lower-cased, so an id handed in * upper case matches the row *there* and would miss it here, which would make an answer depend on - * whether some other lookup shared the microtask. An integer or `numeric` is compared by value too: + * whether some other lookup shared the microtask; braces and missing hyphens are the same value + * there too (`uuid-text.ts`). An integer or `numeric` is compared by value too: * `'007'` matched the row and missed its answer here, filed under `'7'`. One the column could not * hold stays as written, so the statement still carries it and Postgres answers its own refusal. * Every other kind compares by its bytes, and lower-casing a text key would merge two rows * Postgres keeps apart. */ export const keyOf = (kind: string, value: unknown): string => { - if (kind === 'uuid') return String(value).toLowerCase(); + if (kind === 'uuid') return canonicalUuid(value) ?? String(value).toLowerCase(); if (kind === 'integer' || kind === 'bigint') return canonicalInteger(value) ?? String(value); if (kind === 'numeric') return canonicalDecimal(value) ?? String(value); if (kind === 'timestamptz') return canonicalInstant(value) ?? String(value); @@ -117,7 +119,7 @@ export interface PointRead { } /** The one statement, filed by key — the same builder, the same scope, `in` instead of `=`. */ -export const readByIds = async ( +const readStatement = async ( read: PointRead, ids: readonly unknown[], ): Promise> => { @@ -144,6 +146,57 @@ export const readByIds = async ( return answers; }; +/** SQLSTATE class 22, data exception: the server refused a VALUE, not the statement's shape. */ +const isDataError = (error: unknown): boolean => sqlState(error)?.startsWith('22') === true; + +/** + * `readStatement`, with a value the server refuses failing only the id that carried it. One key + * the column cannot hold (`'abc'` against a `bigint`) is a class 22 refusal of the WHOLE statement, + * so every lookup widened into it was failed by an id it never asked for — rows the single + * statement each would have sent answers. The ids are re-sent in halves until the refused one + * stands alone: about `2k·log2(n)` statements for `k` bad ids, never one per id. + * + * Anything else — a dropped connection, a timeout, a stale schema — is the statement's own failure + * and is rethrown for every caller, as before. So is a retry that fails for a reason of its own + * (a transaction the first refusal aborted answers `25P02`): those ids get the FIRST refusal, the + * one the unsplit statement gave them. + */ +export const readByIds = async ( + read: PointRead, + ids: readonly unknown[], +): Promise> => { + try { + return await readStatement(read, ids); + } catch (error) { + if (!isDataError(error) || ids.length < 2) throw error; + const answers = new Map(); + await isolate(read, ids, error, answers); + return answers; + } +}; + +/** `ids` is known to fail together with `refusal`: halve, and file what each half answers. */ +const isolate = async ( + read: PointRead, + ids: readonly unknown[], + refusal: unknown, + answers: Map, +): Promise => { + const middle = Math.ceil(ids.length / 2); + for (const half of [ids.slice(0, middle), ids.slice(middle)]) { + try { + for (const [key, answer] of await readStatement(read, half)) answers.set(key, answer); + } catch (error) { + if (isDataError(error) && half.length > 1) { + await isolate(read, half, error, answers); + continue; + } + const own = isDataError(error) ? error : refusal; + for (const id of half) answers.set(keyOf(read.key.kind, id), { error: own }); + } + } +}; + /** One statement's worth at a time — a batch too wide for the bind count is several, never one. */ export const statementChunks = (values: readonly T[]): readonly (readonly T[])[] => { const chunks: T[][] = []; diff --git a/packages/entity/src/coalesce.test.ts b/packages/entity/src/coalesce.test.ts index b82c3abb2..f7fd38d8f 100644 --- a/packages/entity/src/coalesce.test.ts +++ b/packages/entity/src/coalesce.test.ts @@ -7,6 +7,7 @@ import { ctxOf, runWithContext, serviceActor, userActor, withChildContext } from import { type DbClient, type RecordingClient, recordingClient, setDbClient } from '@ultimat3/db'; import { MAX_IDS_PER_STATEMENT } from './batch-read'; import { money, text, timestamp, uuid } from './columns'; +import { bigint } from './columns-data'; import { CROSS_TENANT_SCOPE, crossTenant } from './cross-tenant'; import { entity } from './entity'; import { postgresRepo } from './pg-driver'; @@ -202,11 +203,68 @@ describe('findById coalescing', () => { ); // One bind: Postgres compares a uuid as a value and would have matched either spelling, so // the two spellings must not become two lookups — or the answer would depend on the batch. - expect(client.statements[0]?.values).toEqual([mixed.toUpperCase(), ORG, 1]); + expect(client.statements[0]?.values).toEqual([mixed, ORG, 1]); expect(upper?.id).toBe(mixed); expect(lower).toBe(upper); }); + test('one malformed id does not fail the other lookups in its batch', async () => { + // Text that is no uuid never reaches the statement: it is the row that is not there. + client.on('select', { rows: [physical(idAt(10))] }); + const [bad, good] = await inRequest(() => + Promise.all([ + repo().findById('not-a-uuid', { orgId: ORG }), + repo().findById(idAt(10), { orgId: ORG }), + ]), + ); + expect(client.statements).toHaveLength(1); + expect(client.statements[0]?.values).toEqual([idAt(10), ORG, 2]); + expect(bad).toBeNull(); + expect(good?.id).toBe(idAt(10)); + }); + + test('an id the server refuses fails its own caller, and the rest are read again', async () => { + // A key no pre-check knows is bad (`bigint` text the column cannot hold): the statement is + // refused whole with a class 22 state, so the ids are re-sent in halves until the one stands + // alone. Every other caller gets its row, as the single statement it did not share would have. + const counters = entity('coalesce_test_counters', { + columns: { id: bigint().primaryKey(), label: text({ max: 8 }) }, + }); + const sent: (readonly unknown[])[] = []; + const query = (statement: { readonly values: readonly unknown[] }): Promise => { + const ids = statement.values.slice(0, -1); + sent.push(ids); + return ids.includes('abc') + ? Promise.reject( + Object.assign(new RangeError('22P02'), { code: '22P02', severity: 'ERROR' }), + ) + : Promise.resolve(ids.map((id) => ({ id: String(id), label: `n${String(id)}` }))); + }; + const unreached = (): Promise => Promise.reject(new Error('a point read sends query')); + const refusing = { query, one: unreached, execute: unreached } as unknown as DbClient; + const pinned = postgresRepo(counters, { client: refusing }); + const ids = ['1', '2', 'abc', '4', '5']; + const settled = await runWithContext(ctxOf({}), () => + settledWithin( + ids.map((id) => pinned.findById(id)), + 20, + ), + ); + expect(settled.map((result) => result.status)).toEqual([ + 'fulfilled', + 'fulfilled', + 'rejected', + 'fulfilled', + 'fulfilled', + ]); + expect( + settled.flatMap((result) => (result.status === 'fulfilled' ? [result.value?.id] : [])), + ).toEqual(['1', '2', '4', '5']); + expect((settled[2] as PromiseRejectedResult).reason).toMatchObject({ code: '22P02' }); + // Halves, never one statement per id: five ids are five statements at most. + expect(sent.length).toBeLessThanOrEqual(5); + }); + test('a row that no longer decodes fails its own caller, not the batch', async () => { // `reference` is not-null, so a null from the database means the table no longer matches the // entity. That is this row's problem: the caller of the other id still gets their row. diff --git a/packages/entity/src/coalesce.ts b/packages/entity/src/coalesce.ts index ef54ee020..48e654934 100644 --- a/packages/entity/src/coalesce.ts +++ b/packages/entity/src/coalesce.ts @@ -107,8 +107,9 @@ const flush = async (batch: Batch): Promise => { else entry.settle(answer.row); } } catch (error) { - // The statement failed, so everyone in it gets the failure the single statement would - // have handed them. Every one was returned to a caller, so none goes unhandled. + // The statement failed for a reason that is the statement's — a refused VALUE never + // reaches here: `readByIds` re-sends around it and files that failure under its own id + // (`batch-read.ts`). Every entry was returned to a caller, so none goes unhandled. for (const entry of chunk) entry.fail(error); } } diff --git a/packages/entity/src/columns.ts b/packages/entity/src/columns.ts index d067a3432..32c445c47 100644 --- a/packages/entity/src/columns.ts +++ b/packages/entity/src/columns.ts @@ -20,6 +20,7 @@ import { makeTimestamp, } from './column'; import { got, oneOf, refuseNul } from './column-values'; +import { assertInstantsCross } from './instant-range'; import { refuseColumn } from './refuse'; import type { Column, @@ -443,8 +444,10 @@ const narrowUuid = (columns: ColumnMap, row: Row): Row => { * nowhere. The `as` is the one assertion this file is for — every money property is a `MoneyValue` * once `narrowMoney` has returned, and `parseMinor` threw for anything that could not become one. */ -export const narrowRow = (columns: ColumnMap, values: RowWrite): Row => - narrowUuid(columns, narrowMoney(columns, values)) as Row; +export const narrowRow = (columns: ColumnMap, values: RowWrite): Row => { + assertInstantsCross(columns, values); + return narrowUuid(columns, narrowMoney(columns, values)) as Row; +}; /** * The CHECK that stops a psql session writing a currency the app would refuse — the app's own diff --git a/packages/entity/src/entity-patch.ts b/packages/entity/src/entity-patch.ts index a27a89682..4745fa1fe 100644 --- a/packages/entity/src/entity-patch.ts +++ b/packages/entity/src/entity-patch.ts @@ -3,6 +3,7 @@ // would rewrite every column it did not name. import { invariantViolated } from './errors'; +import { assertInstantsCross } from './instant-range'; import { holdsJsonNull } from './json-null'; import { copyRow } from './sealed'; import type { AnyColumn } from './types'; @@ -40,5 +41,7 @@ export const parseEntityPatch = ( configurable: true, }); } + // A patch is a write: an instant Postgres would refuse is refused here, for both drivers. + assertInstantsCross(columns, parsed); return parsed as Patch; }; diff --git a/packages/entity/src/instant-range.test.ts b/packages/entity/src/instant-range.test.ts new file mode 100644 index 000000000..fff02fc60 --- /dev/null +++ b/packages/entity/src/instant-range.test.ts @@ -0,0 +1,95 @@ +// A `timestamp()` value outside years 0001–9999, written through each door a row has: memory +// stored it and Postgres refused the statement. Both refuse now, with one code, before a statement. + +import { afterAll, beforeAll, describe, expect, test } from 'bun:test'; +import { + generateMigration, + type PgliteClient, + pgliteClient, + raw, + statementsOf, +} from '@ultimat3/db'; +import { text, timestamp, uuid } from './columns'; +import { arrayOf } from './columns-data'; +import { type Driver, database, memoryDriver } from './database'; +import { entity } from './entity'; +import { postgresDriver } from './pg-driver'; +import { clearRegistry } from './registry'; + +const marks = entity('instant_range_marks', { + columns: { + id: uuid().primaryKey(), + label: text({ max: 20 }), + at: timestamp(), + seen: arrayOf(timestamp()).nullable(), + }, +}); + +const ID = '00000000-0000-7000-8000-000000000001'; +const OTHER = '00000000-0000-7000-8000-000000000002'; +const FIRST = new Date('0001-01-01T00:00:00.000Z'); +const LAST = new Date('9999-12-31T23:59:59.999Z'); +const OUTSIDE = [ + new Date(FIRST.getTime() - 1), + new Date(LAST.getTime() + 1), + new Date(-8.64e15), + new Date(8.64e15), +]; + +let pglite: PgliteClient; +const drivers: (readonly [string, () => Driver])[] = [ + ['memory', () => memoryDriver()], + ['postgres (PGlite)', () => postgresDriver({ client: pglite })], +]; + +beforeAll(async () => { + pglite = pgliteClient(); + const { up } = generateMigration({ + entities: [marks.$describe()], + name: 'instant range', + now: new Date('2026-11-19T00:00:00.000Z'), + }); + for (const statement of statementsOf(up)) await pglite.execute(raw(statement)); +}, 30_000); + +afterAll(async () => { + await pglite.close(); + clearRegistry(); +}); + +const codeOf = (error: unknown): unknown => (error as { code?: unknown }).code; + +describe.each(drivers)('%s · an instant outside years 0001–9999', (_name, driverOf) => { + const db = () => database({ marks }, { driver: driverOf() }); + + test('the first and last instants are stored and read back', async () => { + const table = db().marks; + await table.insert({ id: ID, label: 'first', at: FIRST, seen: [FIRST, LAST] }); + await table.update(ID, { at: LAST }); + expect(await table.where({ id: ID }).one()).toMatchObject({ at: LAST, seen: [FIRST, LAST] }); + }); + + test.each(OUTSIDE)('%p is refused by insert, insertAll, update and updateWhere', async (at) => { + const table = db().marks; + const row = { id: OTHER, label: 'out', at }; + expect(await table.insert(row).catch(codeOf)).toBe('X_INVARIANT_VIOLATED'); + expect(await table.insertAll([row]).catch(codeOf)).toBe('X_INVARIANT_VIOLATED'); + expect(await table.update(ID, { at }).catch(codeOf)).toBe('X_INVARIANT_VIOLATED'); + expect(await table.updateWhere({ id: ID }, { at }).catch(codeOf)).toBe('X_INVARIANT_VIOLATED'); + expect( + await table.insert({ id: OTHER, label: 'out', at: FIRST, seen: [at] }).catch(codeOf), + ).toBe('X_INVARIANT_VIOLATED'); + expect(await table.where({ id: OTHER }).one()).toBeNull(); + }); +}); + +test('a row the server already holds past year 9999 still reads', async () => { + await pglite.execute( + raw( + `insert into instant_range_marks (id, label, at) values ('00000000-0000-7000-8000-000000000009', 'sentinel', '12000-01-01T00:00:00Z')`, + ), + ); + const table = database({ marks }, { driver: postgresDriver({ client: pglite }) }).marks; + const row = await table.where({ id: '00000000-0000-7000-8000-000000000009' }).one(); + expect(row?.at.getUTCFullYear()).toBe(12_000); +}); diff --git a/packages/entity/src/instant-range.ts b/packages/entity/src/instant-range.ts new file mode 100644 index 000000000..dddd3e5fc --- /dev/null +++ b/packages/entity/src/instant-range.ts @@ -0,0 +1,38 @@ +// Single responsibility: refuse, at a WRITE's entry, a `timestamp()` value Postgres cannot be +// handed. Never on read: an instant the server already holds — a sentinel a psql session wrote past +// year 9999 — still decodes, exactly as it did. + +import { got } from './column-values'; +import { instantCrosses } from './instant'; +import { refuseColumn } from './refuse'; +import type { AnyColumn } from './types'; + +const outOfRange = (value: unknown): boolean => value instanceof Date && !instantCrosses(value); + +/** + * A `Date` is bound as its ISO text, and outside years 0001–9999 the server refuses that text + * (`22008`, `22007`, `22009`) while memory stored the row: one only a single driver could hold. + * Refused by both, before either — the same place a malformed `uuid` is (`narrowUuid`). Only a + * `Date` is judged: a repository write is asserted, not parsed, and `timestamp()`'s own parser has + * made every other spelling a `Date` before a row reaches here. + */ +export const assertInstantsCross = ( + columns: Readonly>, + row: unknown, +): void => { + if (typeof row !== 'object' || row === null) return; + const record = row as Readonly>; + for (const [property, column] of Object.entries(columns)) { + const kind = + column.$meta.kind === 'array' ? column.$meta.element?.$meta.kind : column.$meta.kind; + if (kind !== 'timestamptz') continue; + const value = record[property]; + const refusedValue = Array.isArray(value) ? value.find(outOfRange) : value; + if (!outOfRange(refusedValue)) continue; + refuseColumn( + 'format', + `${property}: expected an instant in years 0001–9999, ${got(refusedValue)}`, + "new Date('2026-03-14T09:00:00Z') // timestamp() crosses to Postgres as ISO text with a four-digit year; store null on a .nullable() column for 'never', not a far-off sentinel", + ); + } +}; diff --git a/packages/entity/src/instant.ts b/packages/entity/src/instant.ts index 282c0d275..9700fc443 100644 --- a/packages/entity/src/instant.ts +++ b/packages/entity/src/instant.ts @@ -131,6 +131,20 @@ const isoInstantMicros = (text: string): bigint | undefined => { return local - offset * MICROS_PER_MINUTE; }; +/** The first and last milliseconds `toISOString()` writes with a four-digit year, 0001 to 9999. */ +const FIRST_INSTANT_MS = -62_135_596_800_000; +const LAST_INSTANT_MS = 253_402_300_799_999; + +/** + * Whether a `Date` crosses to Postgres. It is bound as its ISO text, and outside years 0001–9999 + * that text is one the server refuses (`22008` for year 0000, `22007`/`22009` for a signed year) + * while memory stored and compared the value: a row only one driver could hold. + */ +export const instantCrosses = (value: Date): boolean => { + const ms = value.getTime(); + return ms >= FIRST_INSTANT_MS && ms <= LAST_INSTANT_MS; +}; + /** * The microsecond epoch of whatever a sort key or an operand is holding: a decoded row's `Date` * (milliseconds, so the last three digits are zero), a value already counted in microseconds, the diff --git a/packages/entity/src/jit-preload.ts b/packages/entity/src/jit-preload.ts index 6758d45d8..03fda47f4 100644 --- a/packages/entity/src/jit-preload.ts +++ b/packages/entity/src/jit-preload.ts @@ -201,8 +201,9 @@ const fill = async ( try { answers = await readByIds(read, chunk); } catch (error) { - // The statement failed, so it fails for everyone it was widened to cover — which is what - // the single statement each of them would have sent would have done. + // The statement failed for a reason that is the statement's, so it fails for everyone it was + // widened to cover. A refused VALUE is not that: `readByIds` isolates the id that carried it + // (`batch-read.ts`), so the rest are answered as their own statement would have been. for (const id of chunk) settlers.get(keyOf(read.key.kind, id))?.({ error }); continue; } diff --git a/packages/entity/src/pg-aggregate.live.test.ts b/packages/entity/src/pg-aggregate.live.test.ts index ace99804d..0a41eb2e2 100644 --- a/packages/entity/src/pg-aggregate.live.test.ts +++ b/packages/entity/src/pg-aggregate.live.test.ts @@ -132,8 +132,8 @@ describe.skipIf(!hasPostgres)('live · postgres · aggregates', () => { test('avg rounds at one fixed scale in both drivers', async () => { // 4/3 likes and 3.3/3 rate: repeating decimals, so the two drivers only agree if they round in - // the same place — which is why the statement says `round(avg(...), 6)` rather than taking the - // server's own numeric scale. + // the same place — which is why the statement rounds once itself (`averageSql`) rather than + // taking the server's own numeric scale. await agrees((repo) => repo.aggregate('avg', 'likeCount'), '1.333333'); await agrees((repo) => repo.aggregate('avg', 'rate'), '1.100000'); }); diff --git a/packages/entity/src/pg-driver-filtered.test.ts b/packages/entity/src/pg-driver-filtered.test.ts index 39ed94e7d..0447d7ed9 100644 --- a/packages/entity/src/pg-driver-filtered.test.ts +++ b/packages/entity/src/pg-driver-filtered.test.ts @@ -181,11 +181,12 @@ describe('deleteWhere(), in both drivers', () => { expect(lastText()).toBe('delete from "pg_test_likes" where "post_id" = $1 and "user_id" = $2'); expect(lastValues()).toEqual([POST_A, USER_A]); - // A value that looks like SQL stays a parameter, exactly as it does on the read path. + // A value that looks like SQL never reaches the text — and against a `uuid()` column it is + // no uuid, so it is not even a parameter: the predicate is "no row" (`predicate-operand.ts`). await postgresRepo(likes).deleteWhere({ postId: "x'; drop table pg_test_likes; --" }); expect(lastText()).not.toContain('drop table'); - expect(lastText()).toBe('delete from "pg_test_likes" where "post_id" = $1'); - expect(lastValues()).toEqual(["x'; drop table pg_test_likes; --"]); + expect(lastText()).toBe('delete from "pg_test_likes" where 1 = 0'); + expect(lastValues()).toEqual([]); }); test('deleteWhere respects soft delete exactly as delete(id) does', async () => { diff --git a/packages/entity/src/pg-sql-aggregate.ts b/packages/entity/src/pg-sql-aggregate.ts index 11cc638e7..f0fe49023 100644 --- a/packages/entity/src/pg-sql-aggregate.ts +++ b/packages/entity/src/pg-sql-aggregate.ts @@ -3,7 +3,7 @@ // which compiles the row reads they share their predicates with — `conditions()` is imported, never // restated, so an aggregate counts exactly the rows the matching read would return. -import { identifier, type SqlFragment, sql } from '@ultimat3/db'; +import { identifier, raw, type SqlFragment, sql } from '@ultimat3/db'; import type { AggregateFn } from './aggregate'; import { AVG_SCALE } from './aggregate'; import { kindOf } from './cursor'; @@ -57,10 +57,32 @@ export const countByStatement = ( * - `agg_count` — how many non-null values went in, which is what tells `null` ("no rows") from a * legitimate zero, and what `avg` divides by. * - * `avg` is `round(avg(...), AVG_SCALE)` rather than the server's own scale, because the in-memory - * driver has to reach the same digits and "whatever numeric division gives you" is not a rule two + * `avg` is `averageSql` rather than the server's own scale, because the in-memory driver has to + * reach the same digits and "whatever numeric division gives you" is not a rule two * implementations can share. */ +/** `10^AVG_SCALE` and its inverse, as literals: the scale is a compile-time constant. */ +const AVG_UNITS = raw(`1${'0'.repeat(AVG_SCALE)}`); +const AVG_UNIT = raw(`0.${'0'.repeat(AVG_SCALE - 1)}1`); + +/** + * The mean at `AVG_SCALE`, rounded ONCE, half away from zero — `averageDecimalText`'s arithmetic + * (`aggregate.ts`) written in SQL: `floor((2·|sum|·10^6 + count) / (2·count))`, sign restored, and + * scaled back by a MULTIPLICATION, which `numeric` does exactly. + * + * Not `round(avg(col), 6)`: a `numeric` quotient is computed to about sixteen SIGNIFICANT digits, + * so nineteen-digit `bigint`s left `avg` no fraction at all and it answered `…001.000000` for a + * mean of `…000.5`. Forcing a wider division scale only moves the defect — a quotient rounded at + * seven places and again at six rounds `.4545454…` up. `div` never rounds, so there is one rounding + * and it is this expression's. An empty set divides by NULL and answers NULL, as `avg` did. + */ +export const averageSql = (target: SqlFragment, filter: SqlFragment = sql``): SqlFragment => { + // `::numeric`: `sum(integer)` is an `int8`, and doubling it a million times over is past one. + const sum = sql`(sum(${target})${filter})::numeric`; + const count = sql`nullif(count(${target})${filter}, 0)`; + return sql`(sign(${sum}) * div(2 * abs(${sum}) * ${AVG_UNITS} + ${count}, 2 * ${count}) * ${AVG_UNIT})`; +}; + export const aggregateStatement = ( entity: EntityCore, plan: QueryPlan, @@ -74,7 +96,7 @@ export const aggregateStatement = ( fn === 'sum' ? sql`sum(${target})` : fn === 'avg' - ? sql`round(avg(${target}), ${AVG_SCALE})` + ? averageSql(target) : // An instant crosses as EPOCH MILLISECONDS, never as the session's own text: `::text` // prints in the session's zone, and `new Date` on that answered NaN for an offset with // seconds (a pre-1937 LMT) and 1999 for year 0099. Not `at time zone 'UTC'` either — diff --git a/packages/entity/src/pg-sql-in.ts b/packages/entity/src/pg-sql-in.ts new file mode 100644 index 000000000..43a397dcd --- /dev/null +++ b/packages/entity/src/pg-sql-in.ts @@ -0,0 +1,44 @@ +// Single responsibility: compile an `in` list to SQL — the `in ($1, …)` it always was, or one array +// parameter once the list is long enough to spend the statement's bind budget on its own. + +import { join, type SqlFragment, sql } from '@ultimat3/db'; +import { arrayLiteral } from './pg-row'; +import { bindsAsArray } from './predicate-operand'; +import type { ColumnKind } from './types'; + +/** Nothing matches. `in ()` is a syntax error in Postgres, so an empty set needs a constant. */ +export const NEVER = sql`1 = 0`; + +/** + * `in` reads a LIST or nothing. A scalar used to be wrapped into a one-element list, which matched + * a row here that `memoryRepo`'s `matches` refuses outright — 0 rows in memory, 1 in Postgres, from + * a call `andWhere(column, op, value: unknown)` compiles. One answer, and it is the one + * `@ultimat3/query`'s `filterClause` already gives: no rows. + * + * A NULL bound as a parameter is `col = null`, which is UNKNOWN and therefore excludes the very row + * the caller listed — while memory's `sameValue(null, null)` includes it. Postgres has no `in` that + * compares a null as a value, so the list is partitioned and the nulls are asked for as `is null`: + * the `(… in (…) or … is null)` pair `eq` and `neq` already emit. + * + * A list past `IN_LIST_AS_ARRAY_FROM` is `= any($1)`: one parameter, the array literal, typed by + * the column it is compared to. Bound one by one, 65,536 values are `08P01` — or a dropped + * connection (measured on `Bun.SQL`: `X_DB_UNAVAILABLE`) — for a list memory answers. The planner + * reads both spellings as the same `ScalarArrayOpExpr`, so the index serves either. + */ +export const inListSql = ( + column: SqlFragment, + kind: ColumnKind | undefined, + value: unknown, +): SqlFragment => { + if (!Array.isArray(value)) return NEVER; + const present = value.filter((each) => each !== null && each !== undefined); + const list = + present.length === 0 + ? undefined + : bindsAsArray(kind, present.length) + ? sql`${column} = any(${arrayLiteral(present)})` + : sql`${column} in (${join(present.map((each) => sql`${each}`))})`; + const nulls = present.length === value.length ? undefined : sql`${column} is null`; + if (list === undefined) return nulls ?? NEVER; + return nulls === undefined ? list : sql`(${list} or ${nulls})`; +}; diff --git a/packages/entity/src/pg-sql-measures.ts b/packages/entity/src/pg-sql-measures.ts index dfcb69531..9fdd018ec 100644 --- a/packages/entity/src/pg-sql-measures.ts +++ b/packages/entity/src/pg-sql-measures.ts @@ -3,12 +3,12 @@ // `pg-sql-aggregate.ts`; the predicates are `pg-sql.ts`'s, imported, never restated. import { identifier, join, type SqlFragment, sql } from '@ultimat3/db'; -import { AVG_SCALE } from './aggregate'; import { moneyColumns } from './column'; import { kindOf } from './cursor'; import type { EntityCore } from './entity'; import type { PlannedMeasure } from './measures'; import { columnRef, conditions, predicatesSql, type ReadShape } from './pg-sql'; +import { averageSql } from './pg-sql-aggregate'; import type { Predicate, QueryPlan } from './tenancy'; /** Output names are positional and fixed (`m0`, `u0`, …): a measure's name never reaches SQL. */ @@ -43,7 +43,7 @@ const measureSql = ( case 'sum': return sql`sum(${target})${filter}`; case 'avg': - return sql`round(avg(${target})${filter}, ${AVG_SCALE})`; + return averageSql(target, filter); default: { const extreme = measure.fn === 'min' ? sql`min(${target})${filter}` : sql`max(${target})${filter}`; diff --git a/packages/entity/src/pg-sql.test.ts b/packages/entity/src/pg-sql.test.ts index 844eaf99a..b8d438477 100644 --- a/packages/entity/src/pg-sql.test.ts +++ b/packages/entity/src/pg-sql.test.ts @@ -160,7 +160,11 @@ describe('predicateSql, via selectStatement', () => { }); test('a property is resolved through the entity to its physical, snake_case column', () => { - const stmt = where({ column: 'orgId', op: 'eq', value: '1' }); + const stmt = where({ + column: 'orgId', + op: 'eq', + value: '00000000-0000-7000-8000-000000000001', + }); expect(stmt.text).toContain('"org_id"'); expect(stmt.text).not.toContain('"orgId"'); }); @@ -408,7 +412,9 @@ describe('updateStatement', () => { test('sets every named column and returns the row, scoped by the same conditions as a read', () => { const stmt = updateStatement( posts, - planOf({ where: [{ column: 'id', op: 'eq', value: 'p1' }] }), + planOf({ + where: [{ column: 'id', op: 'eq', value: '00000000-0000-7000-8000-000000000001' }], + }), new Map([['title', 't2']]), SHAPE, true, @@ -416,7 +422,7 @@ describe('updateStatement', () => { expect(stmt.text).toContain('update "pgsql_posts" set "title" = $1'); expect(stmt.text).toContain('where "id" = $2 and "deleted_at" is null'); expect(stmt.text).toContain('returning *'); - expect(stmt.values).toEqual(['t2', 'p1']); + expect(stmt.values).toEqual(['t2', '00000000-0000-7000-8000-000000000001']); }); // The failure case first: a caller that reads a COUNT must not be handed the rows anyway. A @@ -441,7 +447,9 @@ describe('deleteStatement', () => { test('always includes soft-deleted rows in its own scope — there is no filter left to apply', () => { const stmt = deleteStatement( posts, - planOf({ where: [{ column: 'id', op: 'eq', value: 'p1' }] }), + planOf({ + where: [{ column: 'id', op: 'eq', value: '00000000-0000-7000-8000-000000000001' }], + }), ); expect(stmt.text).toContain('delete from "pgsql_posts" where "id" = $1'); expect(stmt.text).not.toContain('deleted_at'); @@ -450,7 +458,7 @@ describe('deleteStatement', () => { test('an entity with no soft-delete column needs no special-casing here either', () => { const stmt = deleteStatement(tags, { entity: tags.$name, - where: [{ column: 'id', op: 'eq', value: 't1' }], + where: [{ column: 'id', op: 'eq', value: '00000000-0000-7000-8000-000000000001' }], orderBy: [], limit: 1, }); diff --git a/packages/entity/src/pg-sql.ts b/packages/entity/src/pg-sql.ts index 45fd3abc8..55633e814 100644 --- a/packages/entity/src/pg-sql.ts +++ b/packages/entity/src/pg-sql.ts @@ -12,17 +12,15 @@ import { searchUndeclared } from './feature-errors'; import { microsToIso, seekAlias } from './instant'; import { operatorUnknown } from './operator'; import { allColumns, arrayLiteral, columnsOf, physicalName } from './pg-row'; +import { inListSql, NEVER } from './pg-sql-in'; import { orMembers, predicateNodeInvalid, viaValue } from './predicate-node'; -import { operandFor } from './predicate-operand'; +import { equalsNoValue, operandFor } from './predicate-operand'; import { viaTarget } from './predicate-screen'; import type { Predicate, QueryPlan, SortKey } from './tenancy'; import { isTextContains, textContainsSql } from './text-contains'; import type { ColumnKind } from './types'; import { isScopedVia } from './via-scope'; -/** Nothing matches. `in ()` is a syntax error in Postgres, so an empty set needs a constant. */ -const NEVER = sql`1 = 0`; - export interface ReadShape { /** Soft-deleted rows are hidden unless the caller asked for them. */ readonly includeDeleted: boolean; @@ -93,27 +91,13 @@ const predicateSql = (entity: EntityCore, asked: Predicate): SqlFragme case 'eq': return value === null ? sql`${column} is null` : sql`${column} = ${value}`; case 'neq': + // Text that is no uuid is distinct from every row, the NULL ones included — memory's answer; + // bound, it was `22P02` (`predicate-operand.ts`). + if (equalsNoValue(kindOf(entity, predicate.column), value)) return sql`true`; // `is distinct from` so a null on either side compares as a value, not as unknown. return sql`${column} is distinct from ${value}`; - case 'in': { - // `in` reads a LIST or nothing. A scalar used to be wrapped into a one-element list, which - // matched a row here that `memoryRepo`'s `matches` refuses outright — 0 rows in memory, 1 in - // Postgres, from a call `andWhere(column, op, value: unknown)` compiles. One answer, and it - // is the one `@ultimat3/query`'s `filterClause` already gives: no rows. - if (!Array.isArray(value)) return NEVER; - // A NULL bound as a parameter is `col = null`, which is UNKNOWN and therefore excludes the - // very row the caller listed — while memory's `sameValue(null, null)` includes it. Postgres - // has no `in` that compares a null as a value, so the list is partitioned and the nulls are - // asked for as `is null`: the `(… in (…) or … is null)` pair `eq` and `neq` already emit. - const present = value.filter((each) => each !== null && each !== undefined); - const list = - present.length === 0 - ? undefined - : sql`${column} in (${join(present.map((e) => sql`${e}`))})`; - const nulls = present.length === value.length ? undefined : sql`${column} is null`; - if (list === undefined) return nulls ?? NEVER; - return nulls === undefined ? list : sql`(${list} or ${nulls})`; - } + case 'in': + return inListSql(column, kindOf(entity, predicate.column), value); case 'gt': return sql`${column} > ${value}`; case 'gte': diff --git a/packages/entity/src/predicate-operand.live.test.ts b/packages/entity/src/predicate-operand.live.test.ts new file mode 100644 index 000000000..fa8eac569 --- /dev/null +++ b/packages/entity/src/predicate-operand.live.test.ts @@ -0,0 +1,133 @@ +// `predicate-operand.test.ts`'s claims that only a server's own client can prove, against a real +// Postgres through `Bun.SQL`: an `in` list bound as ONE array parameter reads each kind as the +// value bound alone did, and text that is no uuid never reaches the wire. Skips unless +// `TEST_DATABASE_URL` is set. + +import { afterAll, beforeAll, describe, expect, test } from 'bun:test'; +import { + generateMigration, + type PostgresClient, + postgresClient, + raw, + statementsOf, +} from '@ultimat3/db'; +import { plainDate } from '@ultimat3/time'; +import { boolean, integer, text, timestamp, uuid } from './columns'; +import { bigint, date, decimal } from './columns-data'; +import { entity } from './entity'; +import { memoryRepo } from './memory-repo'; +import { postgresRepo } from './pg-driver'; +import { IN_LIST_AS_ARRAY_FROM } from './predicate-operand'; +import { clearRegistry } from './registry'; +import type { Repo } from './repo'; +import type { Predicate } from './tenancy'; + +const adminUrl = Bun.env['TEST_DATABASE_URL']; +const hasPostgres = typeof adminUrl === 'string' && adminUrl.length > 0; + +const rows = entity('predicate_operand_live_rows', { + columns: { + id: uuid().primaryKey(), + ref: uuid().nullable(), + label: text({ max: 20 }), + n: integer(), + big: bigint(), + rate: decimal({ precision: 8, scale: 2 }), + flag: boolean(), + at: timestamp(), + day: date(), + }, +}); +type Row = typeof rows.$row; + +const idAt = (index: number): string => `00000000-0000-7000-8000-00000000000${String(index)}`; +const PAST = 70_000; + +const SEED = [0, 1, 2].map((index) => ({ + id: idAt(index), + ref: index === 1 ? null : idAt(7 + index), + label: `a${String(index)}`, + n: index + 1, + big: String(9_200_000_000_000_000_000n + BigInt(index)), + rate: `${String(index)}.50`, + flag: index !== 1, + at: new Date(Date.UTC(2026, index, 1)), + day: plainDate(`2026-0${String(index + 1)}-01`), +})); + +afterAll(() => { + clearRegistry(); +}); + +describe.skipIf(!hasPostgres)('live · postgres · a predicate operand', () => { + let client: PostgresClient; + let memory: Repo; + let postgres: Repo; + + beforeAll(async () => { + client = postgresClient({ url: adminUrl as string, profile: { max: 1 } }); + await client.execute(raw('drop table if exists predicate_operand_live_rows cascade')); + const { up } = generateMigration({ entities: [rows.$describe()], name: 'operand live' }); + for (const statement of statementsOf(up)) await client.execute(raw(statement)); + memory = memoryRepo(rows); + postgres = postgresRepo(rows, { client }); + for (const repo of [memory, postgres]) for (const row of SEED) await repo.insert(row); + }); + + afterAll(async () => { + await client.execute(raw('drop table if exists predicate_operand_live_rows cascade')); + await client.close(); + }); + + const answer = async (repo: Repo, predicate: Predicate): Promise => { + try { + const found = await repo.findMany({ + where: [predicate], + orderBy: [{ column: 'id', direction: 'asc' }], + }); + return found.rows.map((row) => Number(row.id.slice(-1))); + } catch (error: unknown) { + return (error as { code?: unknown }).code; + } + }; + const both = async (predicate: Predicate): Promise => [ + await answer(memory, predicate), + await answer(postgres, predicate), + ]; + /** `values`, repeated past the bind budget: the list's length is the case, not its variety. */ + const past = (values: readonly unknown[]): unknown[] => + Array.from({ length: PAST }, (_, at) => values[at % values.length]); + + test('the list is long enough to cross as an array', () => { + expect(PAST).toBeGreaterThan(IN_LIST_AS_ARRAY_FROM); + }); + + test.each([ + ['id', [idAt(0), idAt(2).toUpperCase(), 'nope'], [0, 2]], + ['ref', [idAt(9), null], [1, 2]], + ['label', ['a1', 'q"\\,{} NULL', ''], [1]], + ['n', [1, '3', 40], [0, 2]], + ['big', [9_200_000_000_000_000_001n, '9200000000000000002'], [1, 2]], + ['rate', ['0.5', 1.5, '002.50'], [0, 1, 2]], + ['flag', [false], [1]], + ['at', [new Date(Date.UTC(2026, 1, 1)), '2026-03-01T00:00:00Z', '2026-01-01'], [0, 1, 2]], + ['day', [new Date('2026-02-01T00:00:00Z'), '2026-03-01'], [1, 2]], + ] as const)( + 'in over %s past the bind budget answers as the short list does', + async (column, values, expected) => { + expect(await both({ column, op: 'in', value: [...values] })).toEqual([expected, expected]); + expect(await both({ column, op: 'in', value: past(values) })).toEqual([expected, expected]); + }, + ); + + test('text that is no uuid equals no row and is distinct from every row', async () => { + expect(await both({ column: 'id', op: 'eq', value: 'nope' })).toEqual([[], []]); + expect(await both({ column: 'id', op: 'eq', value: 5 })).toEqual([[], []]); + expect(await both({ column: 'ref', op: 'neq', value: 'nope' })).toEqual([ + [0, 1, 2], + [0, 1, 2], + ]); + expect(await both({ column: 'id', op: 'eq', value: `{${idAt(1)}}` })).toEqual([[1], [1]]); + for (const repo of [memory, postgres]) expect(await repo.findById('nope')).toBeNull(); + }); +}); diff --git a/packages/entity/src/predicate-operand.test.ts b/packages/entity/src/predicate-operand.test.ts index fd081efdf..aab638c9d 100644 --- a/packages/entity/src/predicate-operand.test.ts +++ b/packages/entity/src/predicate-operand.test.ts @@ -4,6 +4,7 @@ // integer. Either both drivers answer the same rows or both refuse with the same code. import { afterAll, beforeAll, describe, expect, test } from 'bun:test'; +import { ctxOf, runWithContext } from '@ultimat3/core'; import { generateMigration, type PgliteClient, @@ -11,9 +12,10 @@ import { raw, statementsOf, } from '@ultimat3/db'; +import { t } from '@ultimat3/schema'; import { plainDate } from '@ultimat3/time'; -import { integer, text, timestamp, uuid } from './columns'; -import { arrayOf, bigint, date } from './columns-data'; +import { boolean, integer, text, timestamp, uuid } from './columns'; +import { arrayOf, bigint, date, json } from './columns-data'; import { entity } from './entity'; import { memoryRepo } from './memory-repo'; import { postgresRepo } from './pg-driver'; @@ -29,6 +31,10 @@ const rows = entity('predicate_operand_rows', { tags: arrayOf(text()), n: integer(), big: bigint(), + flag: boolean(), + label: text({ max: 20 }), + ref: uuid().nullable(), + data: json(t.object({ k: t.string })), }, }); @@ -40,7 +46,14 @@ const SEED = [ { at: new Date('2026-01-01T00:00:00Z'), day: '2026-01-01', tags: ['a', 'b'], n: 1, big: '10' }, { at: new Date('2025-01-01T00:00:00Z'), day: '2025-12-31', tags: [], n: 2, big: '9' }, { at: new Date('2026-06-01T00:00:00Z'), day: '2026-02-01', tags: ['c'], n: 3, big: '-3' }, -].map((row) => ({ ...row, day: plainDate(row.day) })); +].map((row, index) => ({ + ...row, + day: plainDate(row.day), + flag: index !== 1, + label: `a${String(index)}`, + ref: index === 1 ? null : idAt(7 + index), + data: { k: 'v' }, +})); let pglite: PgliteClient; let memory: Repo; @@ -185,3 +198,121 @@ describe('integer() and bigint(): a non-integer operand is refused by both drive expect(await both({ column, op, value })).toEqual([expected, expected]); }); }); + +describe('uuid(): an operand that is no uuid equals no row, in both drivers', () => { + // Postgres answered `22P02` — a 500 — for the id a URL carries; memory answered "no such row". + test('a malformed uuid operand answers the same on memory and PGlite', async () => { + expect(await both({ column: 'id', op: 'eq', value: 'nope' })).toEqual([[], []]); + expect(await both({ column: 'id', op: 'eq', value: 5 })).toEqual([[], []]); + expect(await both({ column: 'id', op: 'eq', value: ` ${idAt(0)}` })).toEqual([[], []]); + expect(await both({ column: 'id', op: 'in', value: ['nope', idAt(1), 7] })).toEqual([[1], [1]]); + expect(await both({ column: 'id', op: 'in', value: ['nope'] })).toEqual([[], []]); + expect(await both({ column: 'id', op: 'neq', value: 'nope' })).toEqual([ + [0, 1, 2], + [0, 1, 2], + ]); + // `is distinct from`: the row holding NULL is distinct from a value no uuid equals, too. + expect(await both({ column: 'ref', op: 'neq', value: 'nope' })).toEqual([ + [0, 1, 2], + [0, 1, 2], + ]); + expect(await both({ column: 'ref', op: 'in', value: ['nope', null] })).toEqual([[1], [1]]); + }); + + test('a malformed id is a row that is not there: null to findById, X_NOT_FOUND to a write', async () => { + for (const repo of [memory, postgres]) { + expect(await repo.findById('nope')).toBeNull(); + const codeOf = (error: unknown): unknown => (error as { code?: unknown }).code; + expect(await repo.update('nope', { n: 9 }).catch(codeOf)).toBe('X_NOT_FOUND'); + expect(await repo.delete('nope').catch(codeOf)).toBe('X_NOT_FOUND'); + } + }); + + // Every spelling Postgres parses as the same sixteen bytes: memory compared the text. + test.each([idAt(0).toUpperCase(), idAt(0).replaceAll('-', ''), `{${idAt(0)}}`])( + 'the spelling %p is the row both drivers hold', + async (spelling) => { + expect(await both({ column: 'id', op: 'eq', value: spelling })).toEqual([[0], [0]]); + expect(await both({ column: 'id', op: 'in', value: [spelling] })).toEqual([[0], [0]]); + for (const repo of [memory, postgres]) { + expect((await repo.findById(spelling))?.id).toBe(idAt(0)); + } + // Batched, the answer is filed under the key the server printed (`keyOf`), not the spelling. + const batched = await runWithContext(ctxOf({}), () => postgres.findById(spelling)); + expect(batched?.id).toBe(idAt(0)); + }, + ); +}); + +describe('in: a list longer than one statement can bind', () => { + const PAST = 70_000; + + test('an in list past the bind budget answers the same on both drivers', async () => { + const numbers = Array.from({ length: PAST }, (_, at) => at - 10); + expect(await both({ column: 'n', op: 'in', value: numbers })).toEqual([ + [0, 1, 2], + [0, 1, 2], + ]); + const labels = Array.from({ length: PAST }, (_, at) => `a${String(at + 1)}`); + expect(await both({ column: 'label', op: 'in', value: [...labels, 'q"\\,{}'] })).toEqual([ + [1, 2], + [1, 2], + ]); + const instants = Array.from({ length: PAST }, (_, at) => new Date(Date.UTC(2026, 0, 1) + at)); + expect(await both({ column: 'at', op: 'in', value: instants })).toEqual([[0], [0]]); + const ids = Array.from({ length: PAST }, (_, at) => idAt(at % 2)); + expect(await both({ column: 'ref', op: 'in', value: [...ids, null, 'nope'] })).toEqual([ + [1], + [1], + ]); + const days = Array.from({ length: PAST }, () => new Date('2025-12-31T00:00:00Z')); + expect(await both({ column: 'day', op: 'in', value: days })).toEqual([[1], [1]]); + const flags = Array.from({ length: PAST }, () => false); + expect(await both({ column: 'flag', op: 'in', value: flags })).toEqual([[1], [1]]); + const bigs = Array.from({ length: PAST }, (_, at) => BigInt(at) + 10n); + expect(await both({ column: 'big', op: 'in', value: bigs })).toEqual([[0], [0]]); + }, 60_000); + + test('a kind with no array form is refused past the budget by both drivers', async () => { + const lists = Array.from({ length: PAST }, () => ['a']); + expect(await both({ column: 'tags', op: 'in', value: lists })).toEqual(REFUSED); + }); +}); + +describe('like: a pattern matches text', () => { + test.each(['id', 'at', 'day', 'tags', 'n', 'big', 'flag', 'data'] as const)( + 'like is refused on every kind but text/char, identically on both drivers: %s', + async (column) => { + expect(await both({ column, op: 'like', value: '1%' })).toEqual(REFUSED); + }, + ); + + test('a text column still matches by pattern in both', async () => { + expect(await both({ column: 'label', op: 'like', value: 'a%' })).toEqual([ + [0, 1, 2], + [0, 1, 2], + ]); + }); +}); + +describe('timestamp(): an instant Postgres cannot read as text is refused by both drivers', () => { + test.each([ + new Date('0000-12-31T23:59:59.999Z'), + new Date(Date.UTC(10_000, 0, 1)), + new Date(-8.64e15), + '0000-06-01T00:00:00Z', + '0000-06-01', + ])('lt %p', async (value) => { + expect(await both({ column: 'at', op: 'lt', value })).toEqual(REFUSED); + expect(await both({ column: 'at', op: 'in', value: [value] })).toEqual(REFUSED); + }); + + test.each([ + [new Date('0001-01-01T00:00:00.000Z'), []], + [new Date('9999-12-31T23:59:59.999Z'), [0, 1, 2]], + ['0001-01-01T00:00:00+14:00', []], + ['10000-01-01T00:00:00Z', [0, 1, 2]], + ] as const)('lt %p still answers, the same rows in both', async (value, expected) => { + expect(await both({ column: 'at', op: 'lt', value })).toEqual([expected, expected]); + }); +}); diff --git a/packages/entity/src/predicate-operand.ts b/packages/entity/src/predicate-operand.ts index 2b580a15b..6df8f5af9 100644 --- a/packages/entity/src/predicate-operand.ts +++ b/packages/entity/src/predicate-operand.ts @@ -9,21 +9,68 @@ import { got } from './column-values'; import { kindOf } from './cursor'; import type { EntityCore } from './entity'; import { EntityError } from './errors'; -import { instantMicros } from './instant'; +import { instantCrosses, instantMicros } from './instant'; import { isNullish as isNull } from './is-null'; import type { Predicate } from './tenancy'; import type { ColumnKind } from './types'; +import { canonicalUuid } from './uuid-text'; /** The operators whose operand is compared to the column's value as a value of its kind. */ const COMPARING: ReadonlySet = new Set(['eq', 'neq', 'in', 'gt', 'gte', 'lt', 'lte']); -/** Postgres has no `like` for these: `integer ~~ unknown` is "operator does not exist". */ +/** + * Postgres has no `like` for these: `integer ~~ unknown`, `uuid ~~ unknown`, `boolean ~~ unknown` + * are each "operator does not exist" (`42883`), where memory matched the value's text. `bytea` is + * NOT here: the server has a `bytea ~~ bytea`, so that call answers today and stays answered. + */ +const NO_LIKE_KINDS: ReadonlySet = new Set([ + 'integer', + 'bigint', + 'numeric', + 'uuid', + 'boolean', + 'timestamptz', + 'date', + 'jsonb', + 'array', +]); + const NUMERIC_KINDS: ReadonlySet = new Set([ 'integer', 'bigint', 'numeric', ]); +/** Postgres binds at most this many parameters in one statement (`bulk-write.ts` holds the same). */ +const MAX_BINDS = 65_535; + +/** + * An `in` list longer than this crosses as ONE array parameter (`pg-sql-in.ts`). Half the bind + * budget: every list a statement could carry before still compiles to the `in (…)` it always did, + * and one past the budget — `08P01`, or a dropped connection — now answers. + */ +export const IN_LIST_AS_ARRAY_FROM = 32_768; + +/** + * The kinds whose `in` list has an array form: each element's text is what the same value bound + * alone parses to (proved per kind, `predicate-operand.test.ts`). `bytea`, `jsonb` and an array + * column have no element literal (`arrayElement`, `pg-row.ts`). + */ +const ARRAY_BOUND_KINDS: ReadonlySet = new Set([ + 'uuid', + 'text', + 'char', + 'boolean', + 'integer', + 'bigint', + 'numeric', + 'timestamptz', + 'date', +]); + +export const bindsAsArray = (kind: ColumnKind | undefined, length: number): boolean => + length >= IN_LIST_AS_ARRAY_FROM && ARRAY_BOUND_KINDS.has(kind); + /** What an `int4`/`int8` parameter parses: digits with a sign, surrounding blanks allowed. */ const INTEGER_TEXT = /^\s*[+-]?\d+\s*$/; @@ -57,8 +104,9 @@ const instantOperand = ( predicate: Predicate, value: unknown, ): unknown => { - if (value instanceof Date && !Number.isNaN(value.getTime())) return value; - if (typeof value === 'string' && !DIGITS.test(value)) { + if (value instanceof Date && instantCrosses(value)) return value; + // Year 0000 is no year to Postgres (`22008`), whatever the offset beside it. + if (typeof value === 'string' && !DIGITS.test(value) && !value.trim().startsWith('0000-')) { const text = value.trim(); // A calendar date is its midnight; a wall time without seconds gains `:00`: the instant // reader asks for both. @@ -70,7 +118,7 @@ const instantOperand = ( throw refused( entity, predicate, - `expected an instant — a Date or ISO-8601 text — ${got(value)}`, + `expected an instant — a Date or ISO-8601 text, in years 0001–9999 — ${got(value)}`, `.andWhere(${renderFixLiteral(predicate.column, "''")}, '${predicate.op}', new Date('2026-01-01T00:00:00Z')) // ISO text without a zone is read as UTC; a calendar date is a date() column`, ); }; @@ -133,9 +181,40 @@ const scalarOperand = ( if (kind === 'timestamptz') return instantOperand(entity, predicate, value); if (kind === 'date') return dateOperand(entity, predicate, value); if (kind === 'integer' || kind === 'bigint') return integerOperand(entity, predicate, value); + // Every spelling Postgres parses to the same sixteen bytes is ONE operand: memory compared the + // text, so a braced or unhyphenated id matched there and nowhere else. Text that is no uuid is + // left as written — `operandFor` decides what it means for the operators that have an answer. + if (kind === 'uuid') return canonicalUuid(value) ?? value; return value; }; +/** + * A non-null operand no value of the column's kind can EQUAL: text that is not a uuid, against a + * `uuid()` column. Postgres refused the parameter itself (`22P02`, a 500 for an id out of a URL) + * where memory answered "no such row"; both now give memory's answer. `pg-sql.ts` asks this for + * `neq`, the one operator the rewrite below cannot spell. + */ +export const equalsNoValue = (kind: ColumnKind | undefined, value: unknown): boolean => + kind === 'uuid' && !isNull(value) && canonicalUuid(value) === undefined; + +const inList = ( + entity: EntityCore, + predicate: Predicate, + kind: ColumnKind | undefined, + list: readonly unknown[], +): readonly unknown[] => { + const operands = list + .map((each: unknown) => scalarOperand(entity, predicate, kind, each)) + .filter((each) => !equalsNoValue(kind, each)); + if (operands.length <= MAX_BINDS || ARRAY_BOUND_KINDS.has(kind)) return operands; + throw refused( + entity, + predicate, + `${String(operands.length)} values is more than one statement binds (${String(MAX_BINDS)}), and a ${String(kind)} column has no array form to send them as`, + `for (let at = 0; at < values.length; at += 10_000) await ${entity.$name}.andWhere(${renderFixLiteral(predicate.column, "''")}, 'in', values.slice(at, at + 10_000)).all() // one statement per slice`, + ); +}; + /** * The predicate with its operand in the one form both drivers read, or a refusal. Every operator * outside the comparing set passes through untouched — containment, NULL tests and search have @@ -143,18 +222,25 @@ const scalarOperand = ( */ export const operandFor = (entity: EntityCore, predicate: Predicate): Predicate => { const kind = kindOf(entity, predicate.column); - if (predicate.op === 'like' && NUMERIC_KINDS.has(kind)) { + if (predicate.op === 'like' && NO_LIKE_KINDS.has(kind)) { + const column = renderFixLiteral(predicate.column, "''"); throw refused( entity, predicate, `like matches text, and this column is ${String(kind)}`, - `.andWhere(${renderFixLiteral(predicate.column, "''")}, 'gte', 100).andWhere(${renderFixLiteral(predicate.column, "''")}, 'lt', 200) // a number is matched by range, never by pattern`, + NUMERIC_KINDS.has(kind) + ? `.andWhere(${column}, 'gte', 100).andWhere(${column}, 'lt', 200) // a number is matched by range, never by pattern` + : `.andWhere(${column}, 'eq', value) // like reads a text() or char() column; a ${String(kind)} is compared as a value — eq, in, or a gte/lt range`, ); } if (!COMPARING.has(predicate.op)) return predicate; - const value = - predicate.op === 'in' && Array.isArray(predicate.value) - ? predicate.value.map((each: unknown) => scalarOperand(entity, predicate, kind, each)) - : scalarOperand(entity, predicate, kind, predicate.value); + if (predicate.op === 'in' && Array.isArray(predicate.value)) { + return { ...predicate, value: inList(entity, predicate, kind, predicate.value) }; + } + const value = scalarOperand(entity, predicate, kind, predicate.value); + // `eq` against a value nothing equals is the empty list both drivers already answer no row for. + if (predicate.op === 'eq' && equalsNoValue(kind, value)) { + return { ...predicate, op: 'in', value: [] }; + } return value === predicate.value ? predicate : { ...predicate, value }; }; diff --git a/packages/entity/src/refuse.test.ts b/packages/entity/src/refuse.test.ts index 1646a983c..2b210bfed 100644 --- a/packages/entity/src/refuse.test.ts +++ b/packages/entity/src/refuse.test.ts @@ -13,6 +13,7 @@ import { integer, locale, money, + narrowRow, text, timestamp, tz, @@ -75,6 +76,11 @@ const SITES: readonly (readonly [string, () => unknown])[] = [ ['integer value', () => integer().$parse(1.5)], ['boolean value', () => boolean().$parse('yes')], ['timestamp value', () => timestamp().$parse('nope')], + // Refused where a row is WRITTEN (`instant-range.ts`), never where one is read. + [ + 'timestamp outside years 0001–9999', + () => narrowRow({ at: timestamp() }, { at: new Date(8.64e15) }), + ], ['enumerated value', () => enumerated(['draft', 'live']).$parse('gone')], ['enumerated empty', () => enumerated([])], ['url value', () => url().$parse('/settings')], diff --git a/packages/entity/src/search-sql.test.ts b/packages/entity/src/search-sql.test.ts index b0f3a0c59..fb848f1cc 100644 --- a/packages/entity/src/search-sql.test.ts +++ b/packages/entity/src/search-sql.test.ts @@ -28,7 +28,7 @@ const plain = entity('sql_search_plain', { const planFor = (term: string): QueryPlan => ({ entity: posts.$name, where: [ - { column: 'orgId', op: 'eq', value: 'org-1' }, + { column: 'orgId', op: 'eq', value: '00000000-0000-7000-8000-0000000000a1' }, { column: SEARCH_PROPERTY, op: 'matches', value: term }, ], orderBy: [{ column: 'id', direction: 'asc' }], @@ -40,7 +40,7 @@ describe('predicateSql · matches', () => { const fragment = conditions(posts, planFor('cats & dogs'), { includeDeleted: false }); expect(fragment.text).toContain('"search_tsv" @@ websearch_to_tsquery(\'english\', $2)'); expect(fragment.text).not.toContain('cats'); - expect(fragment.values).toEqual(['org-1', 'cats & dogs']); + expect(fragment.values).toEqual(['00000000-0000-7000-8000-0000000000a1', 'cats & dogs']); }); test('the tenant predicate is still in the statement beside the match', () => { diff --git a/packages/entity/src/uuid-text.test.ts b/packages/entity/src/uuid-text.test.ts new file mode 100644 index 000000000..a2d0cf9cc --- /dev/null +++ b/packages/entity/src/uuid-text.test.ts @@ -0,0 +1,59 @@ +// `canonicalUuid` against the server's own parser: every spelling is asked of Postgres (PGlite), +// and the two must agree on which are a uuid and on the value each one names. + +import { afterAll, beforeAll, expect, test } from 'bun:test'; +import { type PgliteClient, pgliteClient, sql } from '@ultimat3/db'; +import { canonicalUuid } from './uuid-text'; + +const ID = '0a1b2c3d-4e5f-7a6b-8c9d-0e1f2a3b4c5d'; +const BARE = ID.replaceAll('-', ''); + +const SPELLINGS: readonly string[] = [ + ID, + ID.toUpperCase(), + BARE, + `{${ID}}`, + `{${BARE}}`, + (BARE.match(/.{4}/g) ?? []).join('-'), + `${BARE.slice(0, 8)}-${BARE.slice(8, 16)}-${BARE.slice(16)}`, + ` ${ID}`, + `${ID} `, + `${ID}\n`, + `{${ID}`, + `${ID}}`, + `{{${ID}}}`, + ID.slice(1), + `${ID}0`, + `${BARE.slice(0, 2)}-${BARE.slice(2)}`, + `${BARE}-`, + `-${BARE}`, + ID.replace('-', '--'), + ID.replace('a', 'g'), + '', + '{}', + 'nope', +]; + +let pglite: PgliteClient; + +beforeAll(() => { + pglite = pgliteClient(); +}); + +afterAll(async () => { + await pglite.close(); +}); + +test.each(SPELLINGS)('%p is read as Postgres reads it', async (spelling) => { + const server = await pglite + .query<{ readonly id: string }>(sql`select ${spelling}::uuid::text as id`) + .then( + (rows) => rows[0]?.id, + () => undefined, + ); + expect(canonicalUuid(spelling)).toBe(server); +}); + +test('a value that is not text is no uuid', () => { + expect([5, null, undefined, {}, [ID]].map(canonicalUuid)).toEqual(Array(5).fill(undefined)); +}); diff --git a/packages/entity/src/uuid-text.ts b/packages/entity/src/uuid-text.ts new file mode 100644 index 000000000..61dd25a73 --- /dev/null +++ b/packages/entity/src/uuid-text.ts @@ -0,0 +1,22 @@ +// Single responsibility: the text Postgres parses as a `uuid`, and the one spelling it prints — +// so an operand no `uuid` column can hold is known before a statement carries it, and a spelling +// the server would have matched is the same value to both drivers. + +/** + * `uuid_in`'s grammar: thirty-two hex digits, a hyphen allowed after any group of four but the + * last, the whole optionally in braces. No blanks — the server refuses a padded value. + */ +const UUID_TEXT = /^(?:[0-9a-f]{4}-?){7}[0-9a-f]{4}$/i; + +/** + * The lower-cased `8-4-4-4-12` spelling of `value`, or `undefined` when it is not a `uuid`'s text. + * Bound as a parameter the latter is `22P02`, a 500 for an id straight out of a URL. + */ +export const canonicalUuid = (value: unknown): string | undefined => { + if (typeof value !== 'string') return undefined; + const braced = value.startsWith('{') && value.endsWith('}'); + const text = braced ? value.slice(1, -1) : value; + if (!UUID_TEXT.test(text)) return undefined; + const hex = text.replaceAll('-', '').toLowerCase(); + return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`; +}; diff --git a/packages/i18n/README.md b/packages/i18n/README.md index e04f2b4d4..ac1dbc506 100644 --- a/packages/i18n/README.md +++ b/packages/i18n/README.md @@ -106,7 +106,8 @@ app renders into your own catalog — that is the one path, and it is the same m ## A catalog slice for an island A translator is a function and cannot be an island's prop. `catalogSubset(t, keys)` resolves the -templates `keys` name — every plural variant included — into `{ locale, catalog }`, plain JSON; +templates `keys` name — every plural variant and every `_select_`/`_ordinal_` family member +included (found through `t.keys()`) — into `{ locale, catalog }`, plain JSON; the island builds `subsetTranslator(subset)` over it: the same lookup, interpolation, CLDR plural pick and loud `⟦key⟧` miss as the server's. Both are on `@ultimat3/i18n/subset`, an entry that installs no framework catalog (the barrel does), so an island chunk can import it. diff --git a/packages/i18n/src/subset.test.ts b/packages/i18n/src/subset.test.ts index 01a4bc826..f5c13b858 100644 --- a/packages/i18n/src/subset.test.ts +++ b/packages/i18n/src/subset.test.ts @@ -3,7 +3,7 @@ import { describe, expect, test } from 'bun:test'; import { catalogSubset, subsetTranslator } from './subset'; -import { catalogTranslator } from './translator'; +import { catalogTranslator, isMiss } from './translator'; const server = catalogTranslator( { @@ -43,6 +43,40 @@ describe('catalogSubset', () => { expect(island.locale).toBe('en'); }); + test("a subset carries a key's select and ordinal families, composed with plurals, and the island renders what the server does", () => { + const families = catalogTranslator( + { + 'app.invite_select_female': 'She invited you', + 'app.invite_select_other_one': 'They sent {count} invite', + 'app.invite_select_other_other': 'They sent {count} invites', + 'app.place_ordinal_one': '{ordinal}st', + 'app.place_ordinal_other': '{ordinal}th', + 'app.invited': 'not a member of app.invite', + 'app.other_select_a': 'another key entirely', + }, + 'en', + ); + const subset = catalogSubset(families, ['app.invite', 'app.place']); + expect(Object.keys(subset.catalog).sort()).toEqual([ + 'app.invite_select_female', + 'app.invite_select_other_one', + 'app.invite_select_other_other', + 'app.place_ordinal_one', + 'app.place_ordinal_other', + ]); + const island = subsetTranslator(JSON.parse(JSON.stringify(subset))); + for (const [key, vars] of [ + ['app.invite', { select: 'female' }], + ['app.invite', { select: 'male', count: 1 }], + ['app.invite', { select: 'male', count: 4 }], + ['app.place', { ordinal: 1 }], + ['app.place', { ordinal: 4 }], + ] as const) { + expect(island(key, vars)).toBe(families(key, vars)); + expect(isMiss(island(key, vars))).toBe(false); + } + }); + test('a __proto__ key in the parsed subset stays a key', () => { const island = subsetTranslator( JSON.parse('{"locale":"en","catalog":{"__proto__":"x","ui.retry":"Retry"}}'), diff --git a/packages/i18n/src/subset.ts b/packages/i18n/src/subset.ts index d70ffcca7..cf5295bdb 100644 --- a/packages/i18n/src/subset.ts +++ b/packages/i18n/src/subset.ts @@ -23,20 +23,37 @@ export type CatalogSubset = { /** The two members of a translator a subset is read through — any app's typed `t` has them. */ export interface RawTranslator { raw(key: string): string | undefined; + /** + * Every key of the catalog. A `select` family's values are an open set, so its members can only + * be found by listing: a translator without `keys()` yields a subset with no families. + */ + keys?(): string[]; readonly locale: Locale; } +/** The infix of a family member: `_select_`, `_ordinal_`. */ +const FAMILY = /_(?:select|ordinal)_/g; + /** - * The templates `keys` name in `t`'s locale, each with every plural variant the catalog holds, so - * `t(key, { count })` in the island picks the form the server would. A key the catalog lacks is - * left out, and renders `⟦key⟧` in the island exactly as it would on the server. + * The templates `keys` name in `t`'s locale, each with every plural variant and every `select` and + * `ordinal` family member the catalog holds, so `t(key, { count, select, ordinal })` in the island + * picks the form the server would. A key the catalog lacks is left out, and renders `⟦key⟧` in the + * island exactly as it would on the server. */ export function catalogSubset(t: RawTranslator, keys: readonly string[]): CatalogSubset { const catalog: Record = Object.create(null) as Record; + const copy = (name: string): void => { + const template = t.raw(name); + if (template !== undefined) catalog[name] = template; + }; for (const key of keys) { - for (const name of [key, ...pluralVariantsOf(key)]) { - const template = t.raw(name); - if (template !== undefined) catalog[name] = template; + for (const name of [key, ...pluralVariantsOf(key)]) copy(name); + } + const wanted = new Set(keys); + for (const name of t.keys?.() ?? []) { + // Every infix, never only the first: a named key may itself spell `_select_`. + for (const infix of name.matchAll(FAMILY)) { + if (wanted.has(name.slice(0, infix.index))) copy(name); } } return { locale: t.locale, catalog }; diff --git a/packages/i18n/src/translator.test.ts b/packages/i18n/src/translator.test.ts index e00e8cb39..a63b44b7a 100644 --- a/packages/i18n/src/translator.test.ts +++ b/packages/i18n/src/translator.test.ts @@ -148,6 +148,33 @@ describe('catalogTranslator', () => { }); }); +describe('has() answers for a select or ordinal family as t() renders it', () => { + // A guard (`t.has(key) ? t(key, vars) : fallback`, the mail render's preheader and footer) used + // to drop copy `t()` renders: a family stem authored only in plural forms read as absent. + test('has(key) is true for a select family defined only in plural forms', () => { + const t = catalogTranslator( + { + invite_select_female_one: 'She sent {count} invite', + invite_select_other_one: 'They sent {count} invite', + invite_select_other_other: 'They sent {count} invites', + place_ordinal_other_plural: '{ordinal}th of {count}', + }, + 'en', + ); + expect(t.has('invite')).toBe(true); + expect(t('invite', { select: 'female', count: 1 })).toBe('She sent 1 invite'); + expect(isMiss(t('invite', { count: 3 }))).toBe(false); + expect(t.has('place')).toBe(true); + expect(isMiss(t('place', { ordinal: 4, count: 2 }))).toBe(false); + expect(isMiss(t('place', { count: 2 }))).toBe(false); + }); + + test('a family with no _other stem is still absent: an unnamed value would miss', () => { + const t = catalogTranslator({ invite_select_female_one: 'She sent {count} invite' }, 'en'); + expect(t.has('invite')).toBe(false); + }); +}); + /** * These assertions fail at `tsc`, not at runtime: every `@ts-expect-error` below is a key an * app must not be able to write. The `expect()` calls exist so the values are not dead code. diff --git a/packages/i18n/src/translator.ts b/packages/i18n/src/translator.ts index 25f205f7c..b2697800b 100644 --- a/packages/i18n/src/translator.ts +++ b/packages/i18n/src/translator.ts @@ -64,6 +64,9 @@ export interface Translator { readonly locale: Locale; } +/** What every `pluralKeyCandidates` chain ends on, as suffixes of a stem. */ +const CHAIN_ENDS = ['', '_other', '_plural', '_one'] as const; + export function catalogTranslator(catalog: Catalog, locale: Locale = DEFAULT_LOCALE): Translator { const hasExact = (key: string): boolean => Object.hasOwn(catalog, key); @@ -84,13 +87,12 @@ export function catalogTranslator(catalog: Catalog, locale: Locale = DEFAULT_LOC }; return Object.assign(translate, { + // The stems `selectMessageKey` falls back to, each with the four forms every plural chain ends + // on: a family authored only in plural forms (`invite_select_other_one`) renders, so it is had. has: (key: string): boolean => - hasExact(key) || - hasExact(`${key}_other`) || - hasExact(`${key}_plural`) || - hasExact(`${key}_one`) || - hasExact(`${key}_select_other`) || - hasExact(`${key}_ordinal_other`), + [key, `${key}_select_other`, `${key}_ordinal_other`].some((stem) => + CHAIN_ENDS.some((end) => hasExact(stem + end)), + ), raw: (key: string): string | undefined => (hasExact(key) ? catalog[key] : undefined), keys: (): string[] => Object.keys(catalog).sort(), locale, diff --git a/packages/jobs/CLAUDE.md b/packages/jobs/CLAUDE.md index 649b413b6..f5aec6622 100644 --- a/packages/jobs/CLAUDE.md +++ b/packages/jobs/CLAUDE.md @@ -99,8 +99,8 @@ A rule or row marked `†` has its full text in [`docs/history/jobs-rules.md`](. - **One enqueue implementation**: `jobsFacade()` owns `enqueue` AND `enqueueMany`, over `enqueue-record.ts`'s row builders; the only other `driver.enqueue` sites are the outbox relay and the scheduler. `handle.as(actor, input)` QUEUES; `executeJob` is the one execution path. -- The scheduler's key is occurrence-scoped (`task:occurrenceMs:jobKey`); `task.enqueue()` uses the - job's plain key. +- The scheduler's key is occurrence-scoped (`task:occurrenceMs:jobKey`), its row under + `tenantFor(input)`; `task.enqueue()` uses the job's plain key. - **TWO shutdown hooks per worker, one per PHASE**: `accept` is `stopAccepting()` (flip state, clear the poll timer, arm the cut-off; aborts nothing); `close` is the teardown. `stop()` releases both in a `finally`; `start()` refuses while draining. @@ -204,10 +204,10 @@ Long form: [`docs/history/jobs.md`](../../docs/history/jobs.md), "Moved 2026-10- | `events-pg.ts` | `postgresEventBus` — `step.waitForEvent` across processes | | `driver.ts` | `JobDriver` contract + wire records | | `driver-pg.ts` | default driver, and `postgresLeader` | -| `driver-pg-ddl.ts` | `SQL_JOBS_TABLE` — the ONE install point — `JOBS_TABLE_STORAGE` (fillfactor 80, exported for the framework schema's drift check), and the hot tables' autovacuum settings (`x_scheduler_state`, `x_job_workers`, `x_outbox`) as `tableStorage()` declarations in `JOBS_STORAGE`, which drift checks. Its comments carry no `;` and no `'` | +| `driver-pg-ddl.ts` | `SQL_JOBS_TABLE` — the ONE install point — `JOBS_TABLE_STORAGE` (fillfactor 80), and the hot tables' autovacuum settings (`x_scheduler_state`, `x_job_workers`, `x_outbox`) as `tableStorage()` declarations in `JOBS_STORAGE`, which drift checks. Its comments carry no `;` and no `'` | | `driver-pg-rows.ts` | a Postgres row → a wire record: `JobRow`/`StepRow`/`BackfillRow` and their mappings | -| `driver-memory.ts` / `claim-exhausted.ts` | `x dev` / tests; a buried row's log line and `onSettled`, told beside the claim pass (`burialTeller`, awaited by `tick()` and the drain) and started only inside its debt's grace (else left owed) | -| `retry.ts` | the dead-letter decision; this package's option names over core's `backoffDelay`, no curve | +| `driver-memory.ts` / `claim-exhausted.ts` | `x dev` / tests; a buried row's log line and `onSettled`, told beside the claim pass (`burialTeller`) and started only inside its debt's grace | +| `retry.ts` / `retry-default.ts` | the dead-letter decision over core's `backoffDelay`; the app's default (`jobs.maxAttempts`/`backoff`), resolved when `handle.retry` is READ | | `retry-classification.ts` | the other half: what the thrown error says, and the stop reason | | `retry-jitter.ts` | `retry.jitter` refused at `job()` unless a `JitterMode` (a v30 boolean names its mapping) | | `execute-unwind.ts` / `execute-ctx.ts` | a saga failed for good; caller ctx | @@ -244,7 +244,7 @@ Long form: [`docs/history/jobs.md`](../../docs/history/jobs.md), "Moved 2026-10- | `scheduler-state.ts` | `SchedulerState`, `fire`, `readWatermarks` (one read a round), the memory watermark | | `scheduler-leader.ts` / `scheduler-occurrences.ts` | `LeaderElection` + `soleLeader`; which occurrences fall in a window | | `idle-backoff.ts` / `enqueue-signal.ts` | the wait both polling loops share, and the rest (`restAfter`); the two wake signals and `wakeIsLive` | -| `queue-wake.ts` / `driver-pg-wake-sql.ts` | the `LISTEN` session and its proof; which statement notifies | +| `queue-wake.ts` / `driver-pg-wake-sql.ts` | the `LISTEN` session, its proof and re-proof; which statement notifies | | `worker-loop.ts` | the claim loop's timer: wake, `again`, the kicks, its heartbeat stamps | | `loop-heartbeat.ts` | a long-running loop's heartbeat (`loopHeartbeat`, `staleLoops`): the bound the cli's `/healthz` on `METRICS_PORT` answers 503 past | | `errors-operator.ts` / `errors-requeue.ts` | the operator verbs' refusals; `requeue`'s | diff --git a/packages/jobs/README.md b/packages/jobs/README.md index cd04e212d..0c6605cbd 100644 --- a/packages/jobs/README.md +++ b/packages/jobs/README.md @@ -1548,6 +1548,7 @@ export const wake = startQueueWake({ listener: client, executor }); | a notification is throttled in the statement | Postgres serialises the commit of every transaction that issued a `NOTIFY` behind one lock, held through its WAL flush. One per enqueue caps enqueuing commits at one flush at a time | | a woken loop passes now, then at the floor again | that pass is what finds the row its slot kept silent — so pickup is never worse than the fixed 250 ms poll | | the wake is PROVEN before the ceiling rises | a probe sent through the pool has to come back on the session (`jobs.wake.live`). One that does not is `jobs.wake.unverified`, once, with the fix | +| a proven wake is proven AGAIN, every `reproveEveryMs` (10 s) | a session that stops delivering with no re-dial (half-open) announces nothing, and a loop would rest up to a minute on it. One notification per channel that wakes no loop; not back within `verifyTimeoutMs`, the wake is un-proven (`jobs.wake.lost`, warn) and the loops poll at the 2 s ceiling until one crosses again (`jobs.wake.live`) | | the poll is the guarantee | a notification is lost with the session that would have carried it. The driver re-dials (`jobs.wake.live` again); meanwhile jobs start on the poll | | a transaction-pooling proxy delivers nothing | PgBouncer `pool_mode = transaction`: the `LISTEN` lands on a connection the proxy takes back. The wake stays unproven and the ceiling stays 2 s — give the `worker` role a direct or session-pooled `DATABASE_URL` | | the memory driver needs none | one process: `signalEnqueued` is the whole wake | @@ -1589,6 +1590,20 @@ retrySchedule({ attempts: 5, backoff: 'exponential', delay: 1000 }) // => [1000, 2000, 4000, 8000] ``` +**A job that declares no `retry` runs under the app's default** (`As of 2026-11`): `jobs.maxAttempts` +and `jobs.backoff` in `app.config.ts`, which the boot installs in every role +(`installDefaultRetry`, on `@ultimat3/jobs/adapter`). With neither key set it is `DEFAULT_RETRY`: +3 attempts, exponential. + +| Declared | Attempts | Backoff | +|---|---|---| +| no `retry` — a factory's is optional (`purge()`, `backfill()`, `rollup()`, …), or `retry: DEFAULT_RETRY` | `jobs.maxAttempts` | `jobs.backoff` | +| `retry: { attempts: 5 }` | 5 | `jobs.backoff` | +| `retry: { attempts: 5, backoff: 'linear' }` | 5 | `'linear'` | + +`job()` itself requires `retry.attempts`, so a plain job's count is always its own. `handle.retry` +is read when used, never frozen at declaration: the handle exists before the config is loaded. + **The error decides too, not only the attempt count** (`As of 2026-08`). `executeJob` reads the thrown error's retry classification — `@ultimat3/core`'s `registerErrorRetry`, the same table `--json` and an HTTP client read — and a code nobody classified keeps the attempt-count path diff --git a/packages/jobs/src/adapter.ts b/packages/jobs/src/adapter.ts index 1c9722cea..7cb8bbfc0 100644 --- a/packages/jobs/src/adapter.ts +++ b/packages/jobs/src/adapter.ts @@ -1,6 +1,6 @@ // `@ultimat3/jobs/adapter` — what a queue, an event bus or a durable store is built and installed // from: the port interfaces (outbox, step and lease stores too), a driver's errors, the installers -// and their resets. Never the `.` barrel: an app swaps a backend in `apps//runtime.ts`, so +// and their resets — the app's default retry among them. Never the `.` barrel: an app swaps a backend in `apps//runtime.ts`, so // the callers here are the cli boot, `@ultimat3/testing` and a driver's own author. export type { @@ -33,5 +33,7 @@ export type { EventBus, JobEvent, PublishOptions } from './events'; export { freshDefaultEventBus, installEventBus, resetEventBus } from './events'; export type { LeaseStore } from './leases'; export type { OutboxRecord, OutboxStore } from './outbox'; +export type { DefaultRetry } from './retry-default'; +export { installDefaultRetry, resetDefaultRetry } from './retry-default'; export { fireThroughDriver } from './scheduler-state'; export type { StepStore } from './steps-store'; diff --git a/packages/jobs/src/driver-pg-operator-sql.ts b/packages/jobs/src/driver-pg-operator-sql.ts index 54b5e9df6..397318fb2 100644 --- a/packages/jobs/src/driver-pg-operator-sql.ts +++ b/packages/jobs/src/driver-pg-operator-sql.ts @@ -319,6 +319,10 @@ select task_name, * `greatest` ignores a null, so with no `$4` the watermark lands on the occurrence — and a `$4` * behind the occurrence can never leave the watermark short of what just fired. * + * Each job carries its `tenant_id`, `traceparent` and `enqueued_by` as `SQL_ENQUEUE` writes them: + * the conflict target's namespace includes the tenant, so a row queued for nobody dedupes every + * org of a fan-out onto the first. + * * $1 task, $2 occurrence (ms), $3 the jobs as a JSON array, $4 where the watermark lands (ms) or * null for the occurrence itself. */ @@ -335,13 +339,14 @@ with moved as ( returning task_name ), queued as ( insert into x_jobs - (id, name, queue, input, idempotency_key, run_id, max_attempts, state, run_at) + (id, name, queue, input, idempotency_key, run_id, max_attempts, state, run_at, tenant_id, + traceparent, enqueued_by) select j.id, j.name, j.queue, coalesce(j.input, 'null'::jsonb), j.idempotency_key, j.run_id, j.max_attempts, case when to_timestamp($2::bigint / 1000.0) > now() then 'delayed' else 'ready' end, - to_timestamp($2::bigint / 1000.0) + to_timestamp($2::bigint / 1000.0), j.tenant_id, j.traceparent, j.enqueued_by from jsonb_to_recordset($3::jsonb) as j( id uuid, name text, queue text, input jsonb, idempotency_key text, - run_id uuid, max_attempts int) + run_id uuid, max_attempts int, tenant_id text, traceparent text, enqueued_by text) where exists (select 1 from moved) on conflict (name, (coalesce(tenant_id, '')), idempotency_key) where state in ${LIVE} diff --git a/packages/jobs/src/driver-pg-wake-sql.ts b/packages/jobs/src/driver-pg-wake-sql.ts index 230dd9da1..dcca27d2c 100644 --- a/packages/jobs/src/driver-pg-wake-sql.ts +++ b/packages/jobs/src/driver-pg-wake-sql.ts @@ -18,6 +18,14 @@ export const JOBS_WAKE_CHANNEL = 'x_jobs_wake'; /** A row was committed to `x_outbox`. The payload is always empty: a relay serves every queue. */ export const OUTBOX_WAKE_CHANNEL = 'x_outbox_wake'; +/** + * The payload of a listener's RE-PROOF (`queue-wake.ts`): a notification that asks only whether + * the session still delivers, and wakes no loop. A control character leads it, so no queue is + * ever named it; a pod from before it reads an unknown queue on the jobs channel and passes once + * on the outbox one. + */ +export const WAKE_REPROVE_PAYLOAD = '\u0001reprove'; + /** * One notification per queue per slot, whatever the enqueue rate — save the first commits of a * slot racing each other, which may each send one (`notifyJobReady`). Declared beside the loops diff --git a/packages/jobs/src/enqueue-signal.ts b/packages/jobs/src/enqueue-signal.ts index 4c1b14d14..548f68858 100644 --- a/packages/jobs/src/enqueue-signal.ts +++ b/packages/jobs/src/enqueue-signal.ts @@ -42,8 +42,9 @@ let live = false; /** * Whether work committed by ANOTHER process reaches the two signals above — a `LISTEN` is held - * and a notification has crossed it (`queue-wake.ts`). The idle loops read it to choose their - * ceiling: with no wake, the poll is the only thing bounding a job's start. + * and a notification has crossed it, and keeps crossing it: a proven session is proven again on + * a timer and un-proven when it stops delivering (`queue-wake.ts`). The idle loops read it to + * choose their ceiling: with no wake, the poll is the only thing bounding a job's start. */ export const wakeIsLive = (): boolean => live; diff --git a/packages/jobs/src/job.ts b/packages/jobs/src/job.ts index 25937c476..2c28b698e 100644 --- a/packages/jobs/src/job.ts +++ b/packages/jobs/src/job.ts @@ -25,7 +25,7 @@ import { limiterGateFor } from './limiter-gate'; import { NO_TENANT, tenantKeyFrom } from './limits'; import type { EnqueueOptions } from './outbox'; import { jobsFacade } from './outbox'; -import { DEFAULT_RETRY } from './retry'; +import { resolvedRetry } from './retry-default'; import { assertRetryJitter } from './retry-jitter'; import type { JobSettled } from './settled'; import { ON_SETTLED_TIMEOUT_MS } from './settled'; @@ -166,7 +166,10 @@ export function job(definition: JobDefinition): JobHandle< kind: 'job', name, queue: definition.queue ?? DEFAULT_QUEUE, - retry: { ...DEFAULT_RETRY, ...definition.retry }, + // A getter: the app's default is installed by the boot, after this handle was built. + get retry() { + return resolvedRetry(definition.retry); + }, concurrency: concurrency.limit, whenBusy: concurrency.whenBusy, limiter: definition.limiter, diff --git a/packages/jobs/src/queue-wake.live.test.ts b/packages/jobs/src/queue-wake.live.test.ts index ae2359a60..74469067e 100644 --- a/packages/jobs/src/queue-wake.live.test.ts +++ b/packages/jobs/src/queue-wake.live.test.ts @@ -10,7 +10,7 @@ import type { PostgresClient } from '@ultimat3/db'; import { dbExecutor, postgresClient, raw, sql } from '@ultimat3/db'; import { postgresJobDriver } from './driver-pg'; import { SQL_JOBS_TABLE } from './driver-pg-sql'; -import { JOBS_WAKE_CHANNEL } from './driver-pg-wake-sql'; +import { JOBS_WAKE_CHANNEL, WAKE_REPROVE_PAYLOAD } from './driver-pg-wake-sql'; import { onEnqueued, setWakeLive, wakeIsLive } from './enqueue-signal'; import { resetJobs } from './job'; import { itemJob } from './operator-surface-fixture'; @@ -24,6 +24,8 @@ const LISTENER_APP = 'x-wake-live-worker'; /** How long a job gets to start: a small part of the rest its worker is first seen taking. */ const START_BUDGET_MS = 3_000; const IDLE_REST_MS = 60_000; +/** How often the event loop's lag is sampled; a stall shows as a sample this much late. */ +const LAG_SAMPLE_MS = 20; const probeUrl = (): string => { const parsed = new URL(url ?? 'postgres://localhost/postgres'); @@ -97,12 +99,27 @@ describe.skipIf(!hasPostgres)('live · postgres · the cross-process wake', () = test('a web pod enqueues, an idle worker pod starts the job; the listener is killed, and it does so again', async () => { // Issue #1167's two vantage points, read only on a miss: a second session, which says whether // Postgres delivered the notification at all, and the signal the worker's loop subscribes to. + // Each stamped `@`, beside the worst stall of + // this process's event loop: a notification that arrived on time and was read late is a + // starved loop, which no bound on the wake can tell from a lost one. + let enqueuedAt = performance.now(); + const stamp = (queue: string): string => + `${queue === WAKE_REPROVE_PAYLOAD ? '' : queue}@${Math.round(performance.now() - enqueuedAt)}ms`; const witnessed: string[] = []; - const witness = await webPod.listen(JOBS_WAKE_CHANNEL, (queue) => witnessed.push(queue)); + const witness = await webPod.listen(JOBS_WAKE_CHANNEL, (queue) => witnessed.push(stamp(queue))); cleanups.push(() => witness.unlisten()); const heard: string[] = []; - const stopHearing = onEnqueued((queue) => heard.push(queue ?? '')); + const stopHearing = onEnqueued((queue) => heard.push(stamp(queue ?? ''))); cleanups.push(() => Promise.resolve(stopHearing())); + let lagTick = performance.now(); + let worstLagMs = 0; + // real-clock: samples the real event loop's stalls, which a fake timer cannot have. + const lagSampler = setInterval(() => { + const now = performance.now(); + worstLagMs = Math.max(worstLagMs, now - lagTick - LAG_SAMPLE_MS); + lagTick = now; + }, LAG_SAMPLE_MS); + cleanups.push(() => Promise.resolve(clearInterval(lagSampler))); const wake = startQueueWake({ listener: workerPod, executor: executorFor(workerPod) }); cleanups.push(() => wake.stop()); @@ -130,6 +147,10 @@ describe.skipIf(!hasPostgres)('live · postgres · the cross-process wake', () = // No bound on how fast — a loaded machine broke that one (3 of 60 runs past 200 ms at load 85). const enqueueFromWeb = async (item: string): Promise => { await until(async () => (await worker.stats()).pollDelayMs === IDLE_REST_MS); + witnessed.length = 0; + heard.length = 0; + worstLagMs = 0; + enqueuedAt = performance.now(); await web.enqueue({ name: handle.name, queue: 'default', @@ -154,6 +175,8 @@ describe.skipIf(!hasPostgres)('live · postgres · the cross-process wake', () = ), witnessed, heard, + gaveUpAtMs: Math.round(performance.now() - enqueuedAt), + worstEventLoopLagMs: Math.round(worstLagMs), wakeIsLive: wakeIsLive(), wakeLive: wake.live(), worker: await worker.stats(), diff --git a/packages/jobs/src/queue-wake.test.ts b/packages/jobs/src/queue-wake.test.ts index a5cf0bae7..fb5a87b24 100644 --- a/packages/jobs/src/queue-wake.test.ts +++ b/packages/jobs/src/queue-wake.test.ts @@ -7,7 +7,12 @@ import { afterEach, beforeEach, describe, expect, test } from 'bun:test'; import type { PgExecutor } from '@ultimat3/core'; import { installLogSink } from '@ultimat3/core'; import { memoryJobDriver } from './driver-memory'; -import { JOBS_WAKE_CHANNEL, OUTBOX_WAKE_CHANNEL, SQL_WAKE } from './driver-pg-wake-sql'; +import { + JOBS_WAKE_CHANNEL, + OUTBOX_WAKE_CHANNEL, + SQL_WAKE, + WAKE_REPROVE_PAYLOAD, +} from './driver-pg-wake-sql'; import { onEnqueued, onStaged, setWakeLive, signalStaged, wakeIsLive } from './enqueue-signal'; import { useFakeTime } from './fake-time-fixture'; import { memoryOutboxStore } from './outbox'; @@ -148,8 +153,8 @@ describe('the cross-process wake', () => { expect(wake.live()).toBe(true); expect(wakeIsLive()).toBe(true); expect(logged('jobs.wake.live')).toHaveLength(1); - // The verdict timer went with the proof. - expect(script.pending()).toEqual([]); + // The verdict timer went with the proof; what is armed is the next one (the 10 s default). + expect(script.pending()).toEqual([10_000]); await wake.stop(); }); @@ -350,6 +355,82 @@ describe('the cross-process wake', () => { expect(wakeIsLive()).toBe(false); }); + test('a session that stops delivering is un-proven within one verify window without an onListening', async () => { + const script = scripted(); + const wake = startQueueWake({ ...script, verifyTimeoutMs: 5_000, reproveEveryMs: 10_000 }); + await settle(); + script.notify(JOBS_WAKE_CHANNEL, ''); + script.notify(OUTBOX_WAKE_CHANNEL, ''); + expect(wakeIsLive()).toBe(true); + const woken: (string | undefined)[] = []; + const stopHearing = onEnqueued((queue) => woken.push(queue)); + const stagedSeen: unknown[] = []; + const stopStaged = onStaged((committed) => stagedSeen.push(committed)); + + // Proven is not for ever: the next proof is armed, and it is sent through the pool. + expect(script.pending()).toEqual([10_000]); + script.fire(); + await settle(); + expect(script.probes.slice(2)).toEqual([ + [JOBS_WAKE_CHANNEL, WAKE_REPROVE_PAYLOAD], + [OUTBOX_WAKE_CHANNEL, WAKE_REPROVE_PAYLOAD], + ]); + // It comes back: still live, the next one armed — and no loop was woken to find nothing. + script.notify(JOBS_WAKE_CHANNEL, WAKE_REPROVE_PAYLOAD); + script.notify(OUTBOX_WAKE_CHANNEL, WAKE_REPROVE_PAYLOAD); + expect(wakeIsLive()).toBe(true); + expect(woken).toEqual([]); + expect(stagedSeen).toEqual([]); + expect(script.pending()).toEqual([10_000]); + + // The session goes half-open: no re-dial, no `onListening`, and nothing is delivered. + script.fire(); + await settle(); + expect(script.pending()).toEqual([5_000]); + expect(wakeIsLive()).toBe(true); + script.fire(); + expect(wake.live()).toBe(false); + expect(wakeIsLive()).toBe(false); + expect(logged('jobs.wake.lost')).toEqual([{ event: 'jobs.wake.lost', level: 'warn' }]); + + // Still asking, and silent while it stays lost; the proof that crosses makes it live again. + expect(script.pending()).toEqual([10_000]); + script.fire(); + await settle(); + script.fire(); + expect(logged('jobs.wake.lost')).toHaveLength(1); + script.fire(); + await settle(); + script.notify(JOBS_WAKE_CHANNEL, WAKE_REPROVE_PAYLOAD); + script.notify(OUTBOX_WAKE_CHANNEL, WAKE_REPROVE_PAYLOAD); + expect(wakeIsLive()).toBe(true); + expect(script.pending()).toEqual([10_000]); + + stopHearing(); + stopStaged(); + await wake.stop(); + expect(script.pending()).toEqual([]); + }); + + test('a re-dial ends the re-proof in flight: the new session is proven by its own probe', async () => { + const script = scripted(); + const wake = startQueueWake({ ...script, verifyTimeoutMs: 5_000, reproveEveryMs: 10_000 }); + await settle(); + script.notify(JOBS_WAKE_CHANNEL, ''); + script.notify(OUTBOX_WAKE_CHANNEL, ''); + script.fire(); + await settle(); + expect(script.pending()).toEqual([5_000]); + + script.redial(); + await settle(); + // Only the new session's own verdict is armed; the old re-proof says nothing about it. + expect(script.pending()).toEqual([5_000]); + script.fire(); + expect(logged('jobs.wake.lost')).toEqual([]); + await wake.stop(); + }); + test('a non-finite knob is refused, not read as zero', () => { const script = scripted(); expect(() => startQueueWake({ ...script, verifyTimeoutMs: Number.NaN })).toThrow(/X_INVARIANT/); diff --git a/packages/jobs/src/queue-wake.ts b/packages/jobs/src/queue-wake.ts index 127727e69..22bf616fd 100644 --- a/packages/jobs/src/queue-wake.ts +++ b/packages/jobs/src/queue-wake.ts @@ -9,7 +9,12 @@ import type { PgExecutor, Random } from '@ultimat3/core'; import { backoffDelay, failureStreak, finiteOption, logger } from '@ultimat3/core'; -import { JOBS_WAKE_CHANNEL, OUTBOX_WAKE_CHANNEL, SQL_WAKE } from './driver-pg-wake-sql'; +import { + JOBS_WAKE_CHANNEL, + OUTBOX_WAKE_CHANNEL, + SQL_WAKE, + WAKE_REPROVE_PAYLOAD, +} from './driver-pg-wake-sql'; import { setWakeLive, signalEnqueued, signalStaged } from './enqueue-signal'; /** @@ -32,6 +37,14 @@ export interface QueueWakeOptions { readonly executor: PgExecutor; /** How long a probe may take to come back before the wake is reported unproven. Default 5 s. */ readonly verifyTimeoutMs?: number; + /** + * How often a PROVEN wake is proven again. A session that dies is un-proven by the driver's + * re-dial (`onListening`) — but one that stops delivering with no re-dial (half-open, a re-dial + * refused before its cue) says nothing, and the loops would rest on it. Each period one + * notification per channel is sent that wakes no loop; not back within `verifyTimeoutMs`, the + * wake is un-proven and the loops poll. Default 10 s: six statements a minute, none on a table. + */ + readonly reproveEveryMs?: number; /** First and longest gap between attempts to subscribe or probe. Default 1 s doubling to 30 s. */ readonly retryBaseMs?: number; readonly retryMaxMs?: number; @@ -69,6 +82,7 @@ export function startQueueWake(options: QueueWakeOptions): QueueWake { ); const retryBaseMs = finiteOption(subject, 'retryBaseMs', options.retryBaseMs ?? 1_000); const retryMaxMs = finiteOption(subject, 'retryMaxMs', options.retryMaxMs ?? 30_000); + const reproveEveryMs = finiteOption(subject, 'reproveEveryMs', options.reproveEveryMs ?? 10_000); const setTimer = options.setTimer ?? armTimer; let stopped = false; @@ -78,6 +92,14 @@ export function startQueueWake(options: QueueWakeOptions): QueueWake { const proven = new Set(); let cancelTimer: (() => void) | undefined; let cancelVerdict: (() => void) | undefined; + /** The re-proof's one armed timer: the wait for the next one, or the verdict on the one sent. */ + let cancelReprove: (() => void) | undefined; + /** Channels a notification has crossed since the last re-proof was sent. */ + const since = new Set(); + /** A re-proof is sent and not yet answered. */ + let reproving = false; + /** Moved by every new session and by `stop()`: a re-proof sent before it is nobody's. */ + let session = 0; /** Every channel has been subscribed once: from here an `onListening` is a re-dial. */ let subscribed = false; let probing = false; @@ -111,7 +133,58 @@ export function startQueueWake(options: QueueWakeOptions): QueueWake { ); }; + /** Arm the next re-proof, in place of whichever of its timers is armed. */ + const reproveLater = (): void => { + cancelReprove?.(); + cancelReprove = setTimer(reprove, reproveEveryMs); + }; + + /** + * Prove a proven session AGAIN. Any notification counts, a peer's included: what is asked is + * whether this session still delivers. A send the pool refused is no verdict on the session. + */ + function reprove(): void { + if (stopped) return; + const sentOn = session; + since.clear(); + reproving = true; + cancelReprove = undefined; + void Promise.all( + CHANNELS.map((channel) => options.executor.query(SQL_WAKE, [channel, WAKE_REPROVE_PAYLOAD])), + ) + .then(() => { + probeFailures.passed(); + // Answered already (`crossed` re-armed), or a new session's own probe has taken over. + if (stopped || sentOn !== session || !reproving) return; + cancelReprove = setTimer(() => { + if (stopped || sentOn !== session || !reproving) return; + reproving = false; + if (proven.size === CHANNELS.length) { + proven.clear(); + setWakeLive(false); + logger.warn('jobs.wake.lost', { + waitedMs: verifyTimeoutMs, + missing: CHANNELS.filter((channel) => !since.has(channel)), + }); + } + // Keep asking: the notification that crosses next proves the session again. + reproveLater(); + }, verifyTimeoutMs); + }) + .catch((error: unknown) => { + if (stopped || sentOn !== session) return; + reproving = false; + probeFailures.failed(error, { attempt: 1 }); + reproveLater(); + }); + } + const crossed = (channel: Channel): void => { + since.add(channel); + if (reproving && since.size === CHANNELS.length) { + reproving = false; + if (!stopped) reproveLater(); + } if (proven.has(channel)) return; proven.add(channel); if (proven.size < CHANNELS.length || stopped) return; @@ -119,6 +192,7 @@ export function startQueueWake(options: QueueWakeOptions): QueueWake { cancelVerdict = undefined; setWakeLive(true); logger.info('jobs.wake.live', { channels: CHANNELS }); + if (!reproving) reproveLater(); }; /** @@ -163,6 +237,10 @@ export function startQueueWake(options: QueueWakeOptions): QueueWake { if (stopped) return; proven.clear(); setWakeLive(false); + session += 1; + reproving = false; + cancelReprove?.(); + cancelReprove = undefined; // Not before every channel is subscribed: a probe sent ahead of a `LISTEN` proves nothing. if (!subscribed) return; if (probing) reprobe = true; @@ -175,14 +253,15 @@ export function startQueueWake(options: QueueWakeOptions): QueueWake { JOBS_WAKE_CHANNEL, (payload) => { crossed(JOBS_WAKE_CHANNEL); - signalEnqueued(payload === '' ? undefined : payload); + // A re-proof — this pod's or a peer's — announces no work: it must not end a rest. + if (payload !== WAKE_REPROVE_PAYLOAD) signalEnqueued(payload === '' ? undefined : payload); }, ], [ OUTBOX_WAKE_CHANNEL, - () => { + (payload) => { crossed(OUTBOX_WAKE_CHANNEL); - signalStaged(true); + if (payload !== WAKE_REPROVE_PAYLOAD) signalStaged(true); }, ], ]; @@ -223,8 +302,10 @@ export function startQueueWake(options: QueueWakeOptions): QueueWake { stop() { stopping ??= (async () => { stopped = true; + session += 1; cancelTimer?.(); cancelVerdict?.(); + cancelReprove?.(); setWakeLive(false); await release(); })(); diff --git a/packages/jobs/src/retry-default.test.ts b/packages/jobs/src/retry-default.test.ts new file mode 100644 index 000000000..59695e66e --- /dev/null +++ b/packages/jobs/src/retry-default.test.ts @@ -0,0 +1,92 @@ +// The retry a job that declares none runs under: `DEFAULT_RETRY` until the boot installs the +// app's own (`jobs.maxAttempts`, `jobs.backoff`), and a job's own `retry` over either. + +import { afterEach, beforeEach, describe, expect, test } from 'bun:test'; +import type { StandardSchemaV1 } from '@ultimat3/schema'; +import { + installDefaultRetry, + installJobDriver, + resetDefaultRetry, + resetJobDriver, +} from './adapter'; +import { memoryJobDriver } from './driver-memory'; +import { job, resetJobs } from './job'; +import { resetJobsFacade } from './outbox'; +import { purge } from './purge'; +import { DEFAULT_RETRY, retrySchedule } from './retry'; + +function passthrough(): StandardSchemaV1 { + return { + '~standard': { + version: 1, + vendor: 'ultimate-test', + validate: (value: unknown) => ({ value: value as T }), + }, + }; +} + +const declared = (retry: Parameters[0]['retry']) => + job({ + tenant: 'none', + name: 'declared', + input: passthrough>(), + idempotencyKey: () => 'k', + retry, + run: () => Promise.resolve(), + }); + +beforeEach(() => { + resetJobs(); + resetJobDriver(); + resetJobsFacade(); +}); + +afterEach(() => { + resetDefaultRetry(); + resetJobDriver(); + resetJobsFacade(); +}); + +describe('the retry of a job that declares none', () => { + test('with nothing installed it is DEFAULT_RETRY: 3 attempts, exponential', () => { + const sweep = purge({ name: 'sweep', targets: () => [] }); + expect(sweep.retry).toEqual(DEFAULT_RETRY); + expect(retrySchedule(sweep.retry)).toEqual([1_000, 2_000]); + }); + + test("the installed default reaches it — installed AFTER the handle was built, as a boot's is", () => { + const sweep = purge({ name: 'sweep', targets: () => [] }); + installDefaultRetry({ attempts: 5, backoff: 'fixed' }); + expect(sweep.retry).toEqual({ ...DEFAULT_RETRY, attempts: 5, backoff: 'fixed' }); + expect(retrySchedule(sweep.retry)).toEqual([1_000, 1_000, 1_000, 1_000]); + resetDefaultRetry(); + expect(sweep.retry).toEqual(DEFAULT_RETRY); + }); + + test('the row it is enqueued as carries the installed attempts', async () => { + const driver = memoryJobDriver(); + installJobDriver(driver); + const sweep = purge({ name: 'sweep', targets: () => [] }); + installDefaultRetry({ attempts: 5, backoff: 'exponential' }); + await sweep.enqueue({}); + const [row] = (await driver.introspect?.list()) ?? []; + expect(row?.maxAttempts).toBe(5); + }); + + test("a job's own retry wins: its attempts always, its backoff when it names one", () => { + installDefaultRetry({ attempts: 5, backoff: 'fixed' }); + expect(declared({ attempts: 2 }).retry).toEqual({ + ...DEFAULT_RETRY, + attempts: 2, + backoff: 'fixed', + }); + resetJobs(); + expect(declared({ attempts: 2, backoff: 'linear' }).retry.backoff).toBe('linear'); + }); + + test('an installed count that is not a whole number of at least 1 is refused', () => { + expect(() => installDefaultRetry({ attempts: 0, backoff: 'fixed' })).toThrow(/X_INVARIANT/); + expect(() => installDefaultRetry({ attempts: 2.5, backoff: 'fixed' })).toThrow(/X_INVARIANT/); + expect(purge({ name: 'sweep', targets: () => [] }).retry).toEqual(DEFAULT_RETRY); + }); +}); diff --git a/packages/jobs/src/retry-default.ts b/packages/jobs/src/retry-default.ts new file mode 100644 index 000000000..b6d0c7570 --- /dev/null +++ b/packages/jobs/src/retry-default.ts @@ -0,0 +1,45 @@ +// The retry a job that declares none runs under: `DEFAULT_RETRY`, or what the app's boot installed +// over it from `jobs.maxAttempts` / `jobs.backoff`. Resolved on READ, never at declaration: a handle +// is built when its module is imported, which is before the boot has read the config. + +import { finiteCount } from '@ultimat3/core'; +import type { BackoffStrategy, RetryPolicy } from './retry'; +import { DEFAULT_RETRY } from './retry'; + +/** The two retry facts an app sets for every job at once. */ +export interface DefaultRetry { + /** Total attempts including the first, for a job that declares no `retry`. */ + readonly attempts: number; + /** The curve of a `retry` that names no `backoff`. */ + readonly backoff: BackoffStrategy; +} + +let installed: DefaultRetry | undefined; + +/** + * Install the app's default, process-wide. EVERY role installs it, not the worker alone: the + * process that enqueues stamps the row's `max_attempts` from the same policy the worker retries + * by, and two answers bury a lapsed lease on an attempt the worker would have retried. + */ +export function installDefaultRetry(policy: DefaultRetry): void { + installed = { + attempts: finiteCount('installDefaultRetry', 'attempts', policy.attempts, 1), + backoff: policy.backoff, + }; +} + +export function resetDefaultRetry(): void { + installed = undefined; +} + +/** + * The policy a handle runs under, given what its definition was handed. `DEFAULT_RETRY` ITSELF is + * "declares none" — what every factory passes for an omitted `retry` — and takes the installed + * attempts and curve. A declared policy keeps its own attempts, and the installed curve only when + * it names none. + */ +export function resolvedRetry(declared: RetryPolicy): RetryPolicy { + if (installed === undefined) return { ...DEFAULT_RETRY, ...declared }; + if (declared === DEFAULT_RETRY) return { ...DEFAULT_RETRY, ...installed }; + return { ...DEFAULT_RETRY, backoff: installed.backoff, ...declared }; +} diff --git a/packages/jobs/src/scheduler-dispatch.ts b/packages/jobs/src/scheduler-dispatch.ts index 9530f7558..e1d8e59b7 100644 --- a/packages/jobs/src/scheduler-dispatch.ts +++ b/packages/jobs/src/scheduler-dispatch.ts @@ -40,6 +40,9 @@ export async function dispatchOccurrence( const requests = handle.entries(occurrenceMs).map(([handleForJob, input]) => { // The facade's refusal, at the one enqueue that does not go through it: an empty key. handleForJob.concurrencyKeyFor(input); + // The org the payload names, as the facade queues it (`enqueue-record.ts`): the key's + // namespace is `(name, tenant, key)`, so a fan-out per org queued for nobody is ONE row. + const tenantId = handleForJob.tenantFor(input); return { name: handleForJob.name, queue: handleForJob.queue, @@ -49,6 +52,7 @@ export async function dispatchOccurrence( idempotencyKey: `${handle.name}:${occurrenceMs}:${handleForJob.idempotencyKeyFor(input)}`, maxAttempts: enqueuedAttempts(handleForJob.retry, handleForJob.compensates), runAt: occurrenceMs, + ...(tenantId === undefined ? {} : { tenantId }), }; }); target.firing(handle.name); diff --git a/packages/jobs/src/scheduler-pg-fire.job.test.ts b/packages/jobs/src/scheduler-pg-fire.job.test.ts index 5f1f4d1e8..af44a723d 100644 --- a/packages/jobs/src/scheduler-pg-fire.job.test.ts +++ b/packages/jobs/src/scheduler-pg-fire.job.test.ts @@ -50,4 +50,43 @@ describe('a pg fire reports each job by the row it inserted', () => { expect(results?.map((result) => result.id)).toEqual([idOf('digest'), idOf('cleanup')]); expect(new Set(results?.map((result) => result.runId) ?? []).size).toBe(2); }); + + test('a fire queues each job under its declared tenant: two orgs with one key are two rows', async () => { + const driver = postgresJobDriver({ executor: pg.executor }); + const state = postgresSchedulerState(pg.executor); + + const results = await state.fire(driver, { + task: 'nightly', + occurrenceMs: T0, + jobs: [ + { ...job('digest'), tenantId: 'A' }, + { ...job('digest'), tenantId: 'B' }, + ], + }); + + expect(results?.map((result) => result.deduped)).toEqual([false, false]); + const rows = (await driver.introspect?.list()) ?? []; + expect(rows.map((row) => row.tenantId).sort()).toEqual(['A', 'B']); + }); + + test("a fired row carries the producer span's traceparent, and who it is attributed to", async () => { + const driver = postgresJobDriver({ executor: pg.executor }); + const state = postgresSchedulerState(pg.executor); + const trace = '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01'; + + await state.fire(driver, { + task: 'nightly', + occurrenceMs: T0, + jobs: [{ ...job('digest'), traceparent: trace, enqueuedBy: 'scheduler' }, job('cleanup')], + }); + + const rows = (await driver.introspect?.list()) ?? []; + const digest = rows.find((row) => row.name === 'digest'); + const cleanup = rows.find((row) => row.name === 'cleanup'); + expect(digest?.traceparent).toBe(trace); + expect(digest?.enqueuedBy).toBe('scheduler'); + // Absent stays absent: a request with no trace opens a root, as it did. + expect(cleanup?.traceparent).toBeUndefined(); + expect(cleanup?.tenantId).toBeUndefined(); + }); }); diff --git a/packages/jobs/src/scheduler-pg.ts b/packages/jobs/src/scheduler-pg.ts index 1c3a88108..bc89911d2 100644 --- a/packages/jobs/src/scheduler-pg.ts +++ b/packages/jobs/src/scheduler-pg.ts @@ -74,6 +74,10 @@ export function postgresSchedulerState(executor: PgExecutor): SchedulerState { idempotency_key: request.idempotencyKey, run_id: request.runId ?? uuidV7(), max_attempts: request.maxAttempts, + // Absent is null in the recordset: no tenant, no trace, nobody to attribute. + tenant_id: request.tenantId, + traceparent: request.traceparent, + enqueued_by: request.enqueuedBy, })), ), // Where the watermark lands when that is past the occurrence (`run-once`): ONE statement. diff --git a/packages/jobs/src/scheduler-tenant.test.ts b/packages/jobs/src/scheduler-tenant.test.ts new file mode 100644 index 000000000..fb399029b --- /dev/null +++ b/packages/jobs/src/scheduler-tenant.test.ts @@ -0,0 +1,116 @@ +// A scheduler fire queues each job under the tenant its handle declares. The idempotency namespace +// is `(name, tenant, key)`, so a fan-out per org that left the tenant off deduped every org onto +// the first one's row — and `perTenant` counted the survivor as nobody's. + +import { afterEach, beforeEach, describe, expect, test } from 'bun:test'; +import type { Clock } from '@ultimat3/core'; +import type { StandardSchemaV1 } from '@ultimat3/schema'; +import { resetJobDriver } from './adapter'; +import { memoryJobDriver } from './driver-memory'; +import { job, resetJobs } from './job'; +import { resetJobsFacade } from './outbox'; +import type { CronResolver } from './scheduler'; +import { jobScheduler } from './scheduler'; +import { resetTasks, task } from './task'; + +interface OrgInput { + readonly orgId: string; +} + +function passthrough(): StandardSchemaV1 { + return { + '~standard': { + version: 1, + vendor: 'ultimate-test', + validate: (value: unknown) => ({ value: value as T }), + }, + }; +} + +function fakeClock(startMs: number): Clock & { advance(ms: number): void } { + let current = startMs; + return { + now: () => new Date(current), + advance(ms: number) { + current += ms; + }, + } as Clock & { advance(ms: number): void }; +} + +/** Deterministic stand-in for @ultimat3/time: fires daily at 03:00 UTC. */ +const dailyAt3: CronResolver = (_cron, options) => { + const dayMs = 86_400_000; + const from = options.from.getTime(); + const at3 = Math.floor(from / dayMs) * dayMs + 3 * 3_600_000; + return new Date(at3 > from ? at3 : at3 + dayMs); +}; + +// 2026-07-26T00:00:00Z. +const T0 = Date.UTC(2026, 6, 26, 0, 0, 0); + +beforeEach(() => { + resetJobs(); + resetTasks(); + resetJobDriver(); + resetJobsFacade(); +}); + +afterEach(() => { + resetJobDriver(); + resetJobsFacade(); +}); + +describe('a scheduler fire and the tenant a job declares', () => { + test('a fire queues each job under its declared tenant: two orgs with one key are two rows', async () => { + const digest = job({ + tenant: (input) => input.orgId, + name: 'digest', + input: passthrough(), + idempotencyKey: () => 'digest', + retry: { attempts: 1 }, + run: () => Promise.resolve(), + }); + task({ + name: 'nightlyDigest', + cron: '0 3 * * *', + tz: 'UTC', + enqueue: () => [ + [digest, { orgId: 'A' }], + [digest, { orgId: 'B' }], + ], + }); + const clock = fakeClock(T0); + const driver = memoryJobDriver({ clock }); + const scheduler = jobScheduler({ driver, clock, cron: dailyAt3 }); + + await scheduler.tick(); + clock.advance(4 * 3_600_000); + const [dispatched] = await scheduler.tick(); + + expect(dispatched?.jobs.map((entry) => entry.result.deduped)).toEqual([false, false]); + const rows = (await driver.introspect?.list()) ?? []; + expect(rows.map((row) => row.tenantId).sort()).toEqual(['A', 'B']); + }); + + test('a job declared for no tenant is queued for none', async () => { + const sweep = job({ + tenant: 'none', + name: 'sweep', + input: passthrough>(), + idempotencyKey: () => 'sweep', + retry: { attempts: 1 }, + run: () => Promise.resolve(), + }); + task({ name: 'nightlySweep', cron: '0 3 * * *', tz: 'UTC', enqueue: () => [[sweep, {}]] }); + const clock = fakeClock(T0); + const driver = memoryJobDriver({ clock }); + const scheduler = jobScheduler({ driver, clock, cron: dailyAt3 }); + + await scheduler.tick(); + clock.advance(4 * 3_600_000); + await scheduler.tick(); + + const [row] = (await driver.introspect?.list()) ?? []; + expect(row?.tenantId).toBeUndefined(); + }); +}); diff --git a/packages/mail/src/driver-ses.test.ts b/packages/mail/src/driver-ses.test.ts index b6bfbb3e1..eb6a84ad5 100644 --- a/packages/mail/src/driver-ses.test.ts +++ b/packages/mail/src/driver-ses.test.ts @@ -135,6 +135,28 @@ describe('sesMailDriver — the request', () => { expect(request.headers['x-amz-date']).toBe('20261006T120000Z'); }); + test('a non-ASCII display name reaches Destination and FromEmailAddress 7-bit', async () => { + const { fetch, seen } = stub(() => Response.json({ MessageId: 'ses-id' })); + const driver = driverWith(fetch, { from: 'José Muñoz ' }); + await driver.send( + message({ + to: ['Zoë Ünal '], + cc: ['Grace '], + bcc: ['Ops Désk '], + }), + ); + const body = JSON.parse(seen[0]?.body ?? '{}'); + // SES's envelope takes 7-bit ASCII only: a friendly-from name as an RFC 2047 encoded word, + // and the destinations as the mailboxes the raw message's own headers already name. + expect(body.FromEmailAddress).toBe('=?UTF-8?B?Sm9zw6kgTXXDsW96?= '); + expect(body.Destination).toEqual({ + ToAddresses: ['zoe@example.test'], + CcAddresses: ['grace@example.test'], + BccAddresses: ['ops@example.test'], + }); + expect(/^[\x20-\x7e]*$/.test(seen[0]?.body ?? '')).toBe(true); + }); + test('a session token is sent and signed; an endpoint override replaces the host', async () => { const { fetch, seen } = stub(() => Response.json({ MessageId: 'm-1' })); await driverWith(fetch, { diff --git a/packages/mail/src/driver-ses.ts b/packages/mail/src/driver-ses.ts index 9762ce2be..175e76e96 100644 --- a/packages/mail/src/driver-ses.ts +++ b/packages/mail/src/driver-ses.ts @@ -25,7 +25,7 @@ import { resultFor } from './driver'; import type { MailFetch } from './driver-resend'; import { sendFailed } from './errors'; import { mailMessageIdToken } from './idempotency'; -import { addressDomain, buildMimeMessage } from './mime'; +import { addressDomain, addressSpec, buildMimeMessage, encodeAddressPhrase } from './mime'; import { type RetainMimeOptions, resolveRetainMime, withRetainedMime } from './retain-mime'; import { sesFailure } from './ses-failure'; @@ -104,15 +104,17 @@ function requireFrom(from: string): string { /** * `Destination` is the envelope, and it is sent even though the raw message holds `To:` and `Cc:` - * — `Bcc` is never a header (`mime.ts`), so without it the blind list would receive nothing. + * — `Bcc` is never a header (`mime.ts`), so without it the blind list would receive nothing. SES + * takes envelope addresses as 7-bit ASCII only (its raw-email guide, "MIME Encoding"): the + * destinations go as bare mailboxes, and the friendly-from name as an RFC 2047 encoded word. */ function bodyFor(message: MailMessage, from: string, raw: string, set: string | undefined): string { return JSON.stringify({ - FromEmailAddress: from, + FromEmailAddress: encodeAddressPhrase(from), Destination: { - ToAddresses: message.to, - ...(message.cc === undefined ? {} : { CcAddresses: message.cc }), - ...(message.bcc === undefined ? {} : { BccAddresses: message.bcc }), + ToAddresses: message.to.map(addressSpec), + ...(message.cc === undefined ? {} : { CcAddresses: message.cc.map(addressSpec) }), + ...(message.bcc === undefined ? {} : { BccAddresses: message.bcc.map(addressSpec) }), }, Content: { Raw: { Data: base64Utf8(raw) } }, ...(set === undefined ? {} : { ConfigurationSetName: set }), diff --git a/packages/mail/src/smtp-socket.test.ts b/packages/mail/src/smtp-socket.test.ts index 5e5431da7..530b55871 100644 --- a/packages/mail/src/smtp-socket.test.ts +++ b/packages/mail/src/smtp-socket.test.ts @@ -468,3 +468,33 @@ test('an upgrade that returns no TLS socket is refused, and the raw socket stays runtime.pushRaw('250 still in the clear\r\n'); expect(await stream.read()).toBe('250 still in the clear\r\n'); }); + +test('a connect that never resolves fails at timeoutMs with stage connect', async () => { + let ended = 0; + let land!: (socket: SocketLike) => void; + const late: SocketLike = { + write: (data) => data.length, + end: () => { + ended += 1; + }, + upgradeTLS: () => [], + }; + const stalled: BunConnect = { + connect: () => + new Promise((resolve) => { + land = resolve; + }), + }; + + const error = await caught(smtpStreamOver(stalled, { ...FAKE_TARGET, timeoutMs: 20 })); + + expect(codeOf(error)).toBe('X_MAIL_SEND_FAILED'); + expect(metaOf(error)['stage']).toBe('connect'); + expect(metaOf(error)['retryable']).toBe(true); + expect(causeOf(error)).toContain('20ms'); + // The socket that lands after the deadline is closed, never leaked. + land(late); + await Promise.resolve(); + await Promise.resolve(); + expect(ended).toBe(1); +}); diff --git a/packages/mail/src/smtp-socket.ts b/packages/mail/src/smtp-socket.ts index 1da4d546d..e5c9e00d6 100644 --- a/packages/mail/src/smtp-socket.ts +++ b/packages/mail/src/smtp-socket.ts @@ -213,12 +213,18 @@ export function smtpStreamOver(runtime: BunConnect, target: SmtpTarget): Promise // Registered on the TLS socket at `upgradeTLS`; every event on it is real, so no guard. const tlsHandlers = makeHandlers(() => true); - const opening = runtime.connect({ - hostname: target.host, - port: target.port, - tls: target.tls, - socket: handlers, - }); + const opening = connectWithin( + runtime.connect({ + hostname: target.host, + port: target.port, + tls: target.tls, + socket: handlers, + }), + target, + target.tls + ? `openssl s_client -connect ${endpoint}` + : `openssl s_client -starttls smtp -connect ${endpoint}`, + ); return opening.then((opened): SmtpStream => { let socket = opened; @@ -302,3 +308,41 @@ export function smtpStreamOver(runtime: BunConnect, target: SmtpTarget): Promise }; }); } + +/** + * The dial, bounded by the same deadline as every read and write: a host that swallows the SYN + * would otherwise hold the pool slot for the kernel's own timeout. A socket that lands after the + * deadline is closed at once — nobody holds it. + */ +function connectWithin( + dialing: Promise, + target: SmtpTarget, + fix: string, +): Promise { + return new Promise((resolve, reject) => { + let late = false; + const timer = setTimeout(() => { + late = true; + reject( + sendFailed({ + driver: 'smtp', + stage: 'connect', + detail: `${target.host}:${String(target.port)} did not accept a connection within ${String(target.timeoutMs)}ms`, + retryable: true, + fix, + }), + ); + }, target.timeoutMs); + dialing.then( + (socket) => { + clearTimeout(timer); + if (late) socket.end(); + else resolve(socket); + }, + (error: unknown) => { + clearTimeout(timer); + reject(error); + }, + ); + }); +} diff --git a/packages/manifest/src/build.test.ts b/packages/manifest/src/build.test.ts index 3c0eddd2c..82be1ecab 100644 --- a/packages/manifest/src/build.test.ts +++ b/packages/manifest/src/build.test.ts @@ -126,6 +126,31 @@ describe('the manifest is deterministic', () => { expect(verifyBuildId(buildManifest(sources))).toBe(true); }); + // A schema default reaches a fact verbatim (`sources.ts`'s `asJson` is a cast), so a `Date`, a + // sparse array or an `undefined` member is hashed as itself and WRITTEN as what JSON makes of it. + test('a fact holding a Date round-trips: verifyBuildId(JSON.parse(manifestJson(m))) is true', () => { + const sparse: unknown[] = ['a']; + sparse[2] = 'c'; + const input = { + type: 'object', + properties: { + at: { type: 'string', default: new Date('2026-01-02T03:04:05.000Z') }, + tags: { type: 'array', default: sparse }, + note: { type: 'string', default: undefined }, + }, + } as unknown as JsonValue; + const manifest = buildManifest({ + ...sources, + actions: [{ ...(sources.actions?.[0] as ActionFact), input }], + }); + + const onDisk = JSON.parse(manifestJson(manifest)) as Manifest; + expect(verifyBuildId(onDisk)).toBe(true); + expect(onDisk.buildId).toBe(manifest.buildId); + // The manifest in memory is the one the file holds, so a drift check compares like with like. + expect(canonicalJson(manifest.actions)).toBe(canonicalJson(onDisk.actions)); + }); + // Every buildId ever stamped into an app's `x.manifest.json` was SHA-256/16 over canonicalJson; // that is core's `fingerprint`, so the copy was deleted rather than the value changed. // 25.0.0 (plan 101, M3): `contentHash` was `fingerprint` under a second name, exported from here diff --git a/packages/manifest/src/build.ts b/packages/manifest/src/build.ts index 2eb8cb6c1..07de901a4 100644 --- a/packages/manifest/src/build.ts +++ b/packages/manifest/src/build.ts @@ -101,7 +101,7 @@ export function buildManifest(sources: ManifestSources): Manifest { ...channels.flatMap((c) => c.permissions), ]); - const body = { + const declared = { manifestVersion: MANIFEST_VERSION, app: sources.app, routes, @@ -125,7 +125,11 @@ export function buildManifest(sources: ManifestSources): Manifest { }; // Before the hash: a fact the written file cannot hold must never get a buildId at all. - assertFiniteFacts(body, ''); + assertFiniteFacts(declared, ''); + // What the FILE will hold, and so what is hashed: a schema default reaches a fact verbatim, and + // `JSON.stringify` writes a `Date` as a string, a sparse slot as `null` and drops an `undefined` + // member — hashed as declared, a freshly written manifest failed its own buildId on read-back. + const body: typeof declared = JSON.parse(JSON.stringify(declared)); // The build id is `@ultimat3/core`'s `fingerprint` of the body — SHA-256/16 over the same // INJECTIVE `canonicalJson` the diff compares on, so a fact that changed cannot hash the same as // the fact it replaced — and deliberately excludes `buildId` itself. A HASH, never the published diff --git a/packages/mcp/README.md b/packages/mcp/README.md index 5629a8544..3f0ae8cc6 100644 --- a/packages/mcp/README.md +++ b/packages/mcp/README.md @@ -799,7 +799,7 @@ lists resources per caller — what `extraRecipes` is built on. | output | `{ untrusted, isError }`: the remote's text inside ``, middle cut past `maxResultChars`; invisible format characters (`\p{Cf}`) stripped, then every `<` (and full-width `<`, small `﹤`) written `<` — no tag-shaped pattern left to bypass | | `expose` | default `false`: the actions are this app's, not its `/mcp`'s — `include: 'exposed'` leaves them out, while an in-app `agent()` is still offered them (`agents: true`). `expose: true` opts one remote server in, making this app's `/mcp` answer for a third party's tools | | `reverifyMs` | default 3,600,000: one verdict against the live server stands this long (read on `clock`, default `systemClock`), then the next call re-lists and holds it to the lock again — a remote that changes and announces nothing is caught within the hour | -| `mcpClient({ name, url, dial, deadlineMs, auth })` | over core's `outbound()`; modern era first, the legacy handshake when the server refuses it for its era. A text-only result is a success. `X_MCP_REMOTE_REFUSED`'s `meta.failure` tells `transport` / `status` / `rpc` / `malformed` apart; a tool's own `isError` is a result. A 401 is `X_MCP_REMOTE_AUTH_REQUIRED` with `meta.resourceMetadata` | +| `mcpClient({ name, url, dial, deadlineMs, auth })` | over core's `outbound()`; modern era first, the legacy handshake when the server refuses it for its era (a 400/404/405, an unknown-version/method/request JSON-RPC code, a body that is no answer — never a 429, 408 or 403; one handshake shared by concurrent first calls, and a failed one decides nothing). A `tools/list` whose cursor outlasts 50 pages is `malformed`, never a truncated list. A text-only result is a success. `X_MCP_REMOTE_REFUSED`'s `meta.failure` tells `transport` / `status` / `rpc` / `malformed` apart; a tool's own `isError` is a result. A 401 is `X_MCP_REMOTE_AUTH_REQUIRED` with `meta.resourceMetadata` | | `mcpOAuthClient({ clientId, clientName, redirectUri, scopes? })` | the upstream's OAuth: `begin(serverUrl)` reads RFC 9728 then RFC 8414 metadata and answers `{ authorizeUrl, handshake }` (PKCE S256 from `@ultimat3/auth`, `resource` per RFC 8707); `exchange(handshake, { code, state })` and `refresh(handshake, token)` answer `{ accessToken, refreshToken, expiresIn }`. `clientId` is the HTTPS URL this app serves `metadata()` at (a client ID metadata document). Keep the handshake server-side; return the token from `auth` | ## Errors diff --git a/packages/mcp/src/remote-client.test.ts b/packages/mcp/src/remote-client.test.ts index 36ab23da2..1127bb2d4 100644 --- a/packages/mcp/src/remote-client.test.ts +++ b/packages/mcp/src/remote-client.test.ts @@ -8,6 +8,7 @@ import { ctxOf, runWithContext, userActor } from '@ultimat3/core'; import { mcpClient } from './remote-client'; import { writeToolsLock } from './remote-lock'; import { mcpTools } from './remote-tools'; +import { MCP_MODERN_VERSIONS } from './wire'; const URL = 'http://remote.test/mcp'; type Answer = (body: { id?: number; method: string }) => Response | Promise; @@ -314,3 +315,153 @@ describe('the call itself', () => { expect(notices).toEqual([{ requestId: 4 }]); }); }); + +describe('era negotiation and request ids', () => { + /** A 2025-era server that counts its handshakes; `onCall` decides each session-bound call. */ + const legacyPeer = (onCall?: (id: number, method: string) => Promise | undefined) => { + const seen = { initialize: 0, notices: [] as unknown[] }; + const fetch = async (_url: string, init: RequestInit) => { + const body = JSON.parse(String(init.body)) as { + id?: number; + method: string; + params?: unknown; + }; + if (body.method === 'notifications/cancelled') seen.notices.push(body.params); + if (body.method === 'initialize') { + seen.initialize += 1; + return Response.json( + { jsonrpc: '2.0', id: body.id, result: { protocolVersion: '2025-06-18' } }, + { headers: { 'mcp-session-id': 'sess-1' } }, + ); + } + if (body.id === undefined) return new Response(null, { status: 202 }); + if (new Headers(init.headers).get('mcp-session-id') === null) { + return Response.json({ + jsonrpc: '2.0', + id: body.id, + error: { code: -32022, message: 'v' }, + }); + } + return onCall?.(body.id, body.method) ?? rpcResult(body.id, { tools: [], content: [] }); + }; + return { fetch, seen }; + }; + + test('a cancelled call names its own requestId while a sibling call is in flight', async () => { + const controller = new AbortController(); + const ids = new Map(); + let releaseSibling!: () => void; + const siblingHeld = new Promise((resolve) => { + releaseSibling = resolve; + }); + let siblingPosted!: () => void; + const siblingSent = new Promise((resolve) => { + siblingPosted = resolve; + }); + const { fetch, seen } = legacyPeer((id, method) => { + if (method !== 'tools/call') return undefined; + if (ids.size === 0) { + ids.set('slow', id); + // The slow call is aborted only once its sibling has taken the next id. + return siblingSent.then(() => { + controller.abort(); + return Promise.reject(controller.signal.reason); + }); + } + ids.set('sibling', id); + siblingPosted(); + return siblingHeld.then(() => rpcResult(id, { content: [] })); + }); + const peer = mcpClient({ name: 'old', url: URL, dial: 'named', fetch }); + await peer.listTools(); + const slow = failureOf(peer.callTool('slow', {}, { signal: controller.signal })); + await Promise.resolve(); + const sibling = peer.callTool('sibling', {}); + await slow; + releaseSibling(); + await sibling; + for (let turn = 0; turn < 10 && seen.notices.length === 0; turn += 1) await Promise.resolve(); + expect(seen.notices).toEqual([{ requestId: ids.get('slow') }]); + }); + + test('a call that finished before its signal aborted sends no cancellation', async () => { + const controller = new AbortController(); + const { fetch, seen } = legacyPeer(); + const peer = mcpClient({ name: 'old', url: URL, dial: 'named', fetch }); + await peer.listTools(); + await peer.callTool('quick', {}, { signal: controller.signal }); + controller.abort(); + for (let turn = 0; turn < 10; turn += 1) await Promise.resolve(); + expect(seen.notices).toEqual([]); + }); + + test('a 429 on the first request is retried as modern, never latches legacy', async () => { + let first = true; + const methods: string[] = []; + const peer = client((body) => { + methods.push(body.method); + if (first) { + first = false; + return new Response('slow down', { status: 429 }); + } + if (body.method === 'initialize') { + return Response.json({ + jsonrpc: '2.0', + id: body.id, + error: { code: -32601, message: 'm' }, + }); + } + return rpcResult(body.id, { content: [{ type: 'text', text: 'ok' }] }); + }); + const failure = await failureOf(peer.callTool('t', {})); + expect(failure.meta).toMatchObject({ failure: 'status', status: 429 }); + expect(await peer.callTool('t', {})).toEqual({ isError: false, text: 'ok' }); + expect(methods).toEqual(['tools/call', 'tools/call']); + }); + + test('a failed handshake leaves the era undecided: the next call tries modern again', async () => { + let down = true; + const sent: string[] = []; + const peer = mcpClient({ + name: 'peer', + url: URL, + dial: 'named', + fetch: async (_url, init) => { + const body = JSON.parse(String(init.body)) as { id?: number; method: string }; + const era = new Headers(init.headers).get('mcp-protocol-version'); + sent.push(`${body.method}@${String(era)}`); + if (down) { + if (body.method === 'initialize') down = false; + return new Response('no', { status: 404 }); + } + return rpcResult(body.id, { content: [{ type: 'text', text: 'ok' }] }); + }, + }); + await failureOf(peer.callTool('t', {})); + expect(await peer.callTool('t', {})).toEqual({ isError: false, text: 'ok' }); + const modern = `tools/call@${MCP_MODERN_VERSIONS[0]}`; + expect(sent).toEqual([modern, 'initialize@null', modern]); + }); + + test('two concurrent first calls to a legacy server open one session', async () => { + const { fetch, seen } = legacyPeer(); + const peer = mcpClient({ name: 'old', url: URL, dial: 'named', fetch }); + await Promise.all([peer.listTools(), peer.listTools(), peer.callTool('t', {})]); + expect(seen.initialize).toBe(1); + }); + + test('a cursor that never ends is refused, not truncated', async () => { + let pages = 0; + const failure = await failureOf( + client((body) => { + pages += 1; + return rpcResult(body.id, { + tools: [{ name: `t${String(pages)}` }], + nextCursor: 'again', + }); + }).listTools(), + ); + expect(failure.code).toBe('X_MCP_REMOTE_REFUSED'); + expect(failure.meta?.['failure']).toBe('malformed'); + }); +}); diff --git a/packages/mcp/src/remote-client.ts b/packages/mcp/src/remote-client.ts index eb3c905ca..ed5a8ccc3 100644 --- a/packages/mcp/src/remote-client.ts +++ b/packages/mcp/src/remote-client.ts @@ -76,12 +76,15 @@ const DEFAULT_DEADLINE_MS = 30_000; const DEFAULT_LISTEN_MS = 300_000; const MODERN = MCP_MODERN_VERSIONS[0]; const LEGACY = MCP_LEGACY_VERSIONS[0]; +const MAX_TOOL_PAGES = 50; export function mcpClient(options: McpClientOptions): McpClient { const state: { era?: 'modern' | 'legacy'; session?: string | null; next: number } = { next: 1 }; const listenMs = finiteCount('mcpClient', 'listenMs', options.listenMs ?? DEFAULT_LISTEN_MS, 1); /** The open `GET` stream; `'unsupported'` once the server answered it 405, `'closed'` after close(). */ let listener: Listener | 'unsupported' | 'closed' | undefined; + /** The one handshake in flight: concurrent calls that need a session share it, never race two. */ + let negotiating: Promise | undefined; const refused = ( reason: string, failure: McpRemoteFailure, @@ -157,8 +160,10 @@ export function mcpClient(options: McpClientOptions): McpClient { method: string, params: Record, signal: AbortSignal | undefined, + sent?: { id?: number }, ): Promise> => { const id = state.next++; + if (sent !== undefined) sent.id = id; let body: Record; let headers: Record; if (state.era === 'legacy') { @@ -192,9 +197,8 @@ export function mcpClient(options: McpClientOptions): McpClient { return message['result']; }; + /** The legacy handshake. The era is decided only once it succeeds: a failure leaves it open. */ const initialize = async (signal: AbortSignal | undefined): Promise => { - state.era = 'legacy'; - state.session = null; const id = state.next++; const answer = await post( { @@ -217,10 +221,32 @@ export function mcpClient(options: McpClientOptions): McpClient { 'malformed', ); } - state.session = answer.headers.get('mcp-session-id'); + const opened = answer.headers.get('mcp-session-id'); const notify = { jsonrpc: '2.0', method: 'notifications/initialized' }; - const session = state.session === null ? {} : { 'mcp-session-id': state.session }; + const session = opened === null ? {} : { 'mcp-session-id': opened }; await post(notify, { 'mcp-protocol-version': LEGACY, ...session }, signal); + state.era = 'legacy'; + state.session = opened; + }; + + /** + * Joins the handshake in flight, or starts one. A handshake another caller's abort ended is + * started again under this caller's own signal — someone else's abort is never this call's. + */ + const negotiate = async (signal: AbortSignal | undefined): Promise => { + for (;;) { + negotiating ??= initialize(signal).finally(() => { + negotiating = undefined; + }); + const shared = negotiating; + try { + await shared; + return; + } catch (error) { + const theirs = isUltimateError(error) && error.code === 'X_ABORTED'; + if (!theirs || signal?.aborted === true) throw error; + } + } }; /** @@ -265,21 +291,26 @@ export function mcpClient(options: McpClientOptions): McpClient { method: string, params: Record, signal: AbortSignal | undefined, + sent?: { id?: number }, ): Promise> => { listen(); - if (state.era === undefined) { + if (state.era === undefined && negotiating === undefined) { try { - const result = await rpc(method, params, signal); + const result = await rpc(method, params, signal, sent); state.era = 'modern'; return result; } catch (error) { if (!(error instanceof McpRemoteRefusedError) || !eraRefusal(error)) throw error; - await initialize(signal); - listen(); + // A sibling's first call settled the era while this one was out: its answer stands. + if (state.era === 'modern') throw error; } } + if (state.era === undefined) { + await negotiate(signal); + listen(); + } try { - return await rpc(method, params, signal); + return await rpc(method, params, signal, sent); } catch (error) { // A legacy session the server forgot (404) is re-opened ONCE, as the transport spec says. if (!(error instanceof McpRemoteRefusedError) || error.meta?.['status'] !== 404) throw error; @@ -289,9 +320,9 @@ export function mcpClient(options: McpClientOptions): McpClient { listener.close(); listener = undefined; } - await initialize(signal); + await negotiate(signal); listen(); - return rpc(method, params, signal); + return rpc(method, params, signal, sent); } }; @@ -301,8 +332,9 @@ export function mcpClient(options: McpClientOptions): McpClient { async listTools(listOptions = {}) { const tools: RemoteTool[] = []; let cursor: string | undefined; - // Paged; bounded so a server that loops its cursor cannot hold the boot forever. - for (let page = 0; page < 50; page += 1) { + // Paged; bounded so a server that loops its cursor cannot hold the boot forever — and a list + // still unfinished at the bound is refused, never handed back as if it were whole. + for (let page = 0; page < MAX_TOOL_PAGES; page += 1) { const result = await call( 'tools/list', cursor === undefined ? {} : { cursor }, @@ -312,9 +344,12 @@ export function mcpClient(options: McpClientOptions): McpClient { if (isJsonObject(tool) && typeof tool['name'] === 'string') tools.push(remoteTool(tool)); } cursor = typeof result['nextCursor'] === 'string' ? result['nextCursor'] : undefined; - if (cursor === undefined) break; + if (cursor === undefined) return tools; } - return tools; + throw refused( + `paged past ${String(MAX_TOOL_PAGES)} tools/list pages without an end`, + 'malformed', + ); }, close() { if (typeof listener === 'object') listener.close(); @@ -322,23 +357,28 @@ export function mcpClient(options: McpClientOptions): McpClient { }, async callTool(tool, args, callOptions = {}) { const { signal } = callOptions; + const sent: { id?: number } = {}; try { - const result = await call('tools/call', { name: tool, arguments: args }, signal); + const result = await call('tools/call', { name: tool, arguments: args }, signal, sent); return { isError: result['isError'] === true, text: resultText(result) }; - } finally { - if (signal?.aborted === true && state.era === 'legacy') cancelled(tool); + } catch (error) { + // Only an abort that interrupted a request already sent is news to the server. + if (signal?.aborted === true && state.era === 'legacy' && sent.id !== undefined) { + cancelled(tool, sent.id); + } + throw error; } }, }; /** Legacy servers hear a cancellation as a notification; best effort, and said so in the log. */ - function cancelled(tool: string): void { + function cancelled(tool: string, requestId: number): void { const headers: Record = { 'mcp-protocol-version': LEGACY }; if (typeof state.session === 'string') headers['mcp-session-id'] = state.session; const notice = { jsonrpc: '2.0', method: 'notifications/cancelled', - params: { requestId: state.next - 1 }, + params: { requestId }, }; post(notice, headers, undefined).catch((error: unknown) => { tryUseContext()?.logger.warn('mcp.remote.cancel_unsent', { @@ -361,18 +401,19 @@ function remoteTool(raw: Record): RemoteTool { } /** - * Whether a first modern request was refused for its ERA — a 4xx a legacy server gives an unknown - * shape, a body that is no answer, or the codes for an unknown version, method or request — rather - * than for its content. Only then is the legacy handshake tried; a modern server's own failure - * (`-32603`, a 503) is that failure. + * Whether a first modern request was refused for its ERA — the 400/404/405 a legacy server gives an + * unknown shape, a body that is no answer, or the codes for an unknown version, method or request — + * rather than for its content. Only then is the legacy handshake tried; a modern server's own + * failure (`-32603`, a 503) and a refusal of the moment (429, 408, 403) are that failure. */ const ERA_RPC_CODES: ReadonlySet = new Set([-32022, -32601, -32600, -32602]); +const ERA_STATUSES: ReadonlySet = new Set([400, 404, 405]); function eraRefusal(error: McpRemoteRefusedError): boolean { const failure = error.meta?.['failure']; const status = error.meta?.['status']; const code = error.meta?.['rpcCode']; if (failure === 'malformed') return true; - if (failure === 'status') return typeof status === 'number' && status >= 400 && status < 500; + if (failure === 'status') return typeof status === 'number' && ERA_STATUSES.has(status); return failure === 'rpc' && typeof code === 'number' && ERA_RPC_CODES.has(code); } diff --git a/packages/money/src/arithmetic.test.ts b/packages/money/src/arithmetic.test.ts index 0b0c19ff6..227d7519f 100644 --- a/packages/money/src/arithmetic.test.ts +++ b/packages/money/src/arithmetic.test.ts @@ -282,3 +282,30 @@ describe('divide by zero', () => { expect(divide(fromMinor(100, 'USD'), -1)).toEqual({ minor: -100, currency: 'USD' }); }); }); + +describe('a hand-built Money with a non-integer minor', () => { + // `Money` is a type, not a check: `{ minor: 12.5 }` reached `BigInt()` and left as a bare + // `RangeError`. Every operation refuses it with the constructor's own code. + const broken = { minor: 12.5, currency: 'USD' } as const; + const whole = fromMinor(100, 'USD'); + + test('every arithmetic entry refuses it with X_MONEY_NOT_INTEGER', () => { + const calls: readonly (() => unknown)[] = [ + () => add(broken, whole), + () => add(whole, broken), + () => subtract(whole, broken), + () => sum([whole, broken]), + () => multiply(broken, 2), + () => divide(broken, 2), + () => compare(broken, whole), + () => greaterThan(whole, broken), + () => max(broken, whole), + () => rescale(broken, 6), + () => rescale({ ...broken, scale: 6 }, 2, 'half-up'), + () => negate(broken), + () => absolute({ minor: Number.NaN, currency: 'USD' }), + () => multiply({ minor: Number.POSITIVE_INFINITY, currency: 'USD' }, 2), + ]; + for (const call of calls) expect(codeOf(call)).toBe('X_MONEY_NOT_INTEGER'); + }); +}); diff --git a/packages/money/src/arithmetic.ts b/packages/money/src/arithmetic.ts index 03c25c934..dd3168f00 100644 --- a/packages/money/src/arithmetic.ts +++ b/packages/money/src/arithmetic.ts @@ -7,7 +7,7 @@ import { allocationInvalid, currencyMismatch, currencyRequired } from './errors' import { factorFraction } from './factor'; import { fromMinor, type Money } from './money'; import { DEFAULT_ROUNDING, type RoundingMode, roundRatio } from './rounding'; -import { commonScale, minorAt, toMinor } from './scale'; +import { commonScale, minorAt, minorOf, toMinor } from './scale'; /** Throws `X_CURRENCY_MISMATCH` unless both operands carry the same currency. */ export function assertSameCurrency(left: Money, right: Money): string { @@ -74,7 +74,7 @@ export function multiply( const ratio = factorFraction(factor); // Scale-preserving: a fee on a micro-priced amount stays a micro-priced amount. return fromMinor( - roundRatio(BigInt(amount.minor) * ratio.numerator, ratio.denominator, mode), + roundRatio(minorOf(amount) * ratio.numerator, ratio.denominator, mode), amount.currency, amount.scale, ); @@ -95,7 +95,7 @@ export function divide( } const ratio = factorFraction(divisor); return fromMinor( - roundRatio(BigInt(amount.minor) * ratio.denominator, ratio.numerator, mode), + roundRatio(minorOf(amount) * ratio.denominator, ratio.numerator, mode), amount.currency, amount.scale, ); diff --git a/packages/money/src/format.test.ts b/packages/money/src/format.test.ts index e719fb1dc..07e0ec9f0 100644 --- a/packages/money/src/format.test.ts +++ b/packages/money/src/format.test.ts @@ -1,7 +1,7 @@ import { describe, expect, test } from 'bun:test'; import { isUltimateError, MAX_CACHED_FORMATTERS, type UltimateError } from '@ultimat3/core'; import { currencySymbol, formatMoney, formatMoneyDecimal, formatMoneyParts } from './format'; -import { fromDecimal, fromMinor } from './money'; +import { fromDecimal, fromMinor, toDecimalString } from './money'; /** Intl inserts narrow no-break spaces; compare on the digits, not the whitespace. */ const normalize = (value: string) => value.replace(/[  ]/g, ' '); @@ -325,3 +325,26 @@ describe('fractionDigits is screened before Intl sees it', () => { expect(formatMoney(fromMinor(1299, 'USD'), 'en-US', { fractionDigits: 4 })).toBe('$12.9900'); }); }); + +describe('a hand-built Money with a non-integer minor is refused, never rendered', () => { + const codeOf = (run: () => unknown): unknown => { + try { + run(); + } catch (error) { + return isUltimateError(error) ? error.code : error; + } + return undefined; + }; + + test('formatMoney, its parts, the decimal form and toDecimalString answer X_MONEY_NOT_INTEGER', () => { + // Was `$NaN` for NaN and `12..5` out of `toDecimalString` for 12.5: a wrong amount on a page. + const half = { minor: 12.5, currency: 'USD' } as const; + const nan = { minor: Number.NaN, currency: 'USD' } as const; + for (const amount of [half, nan]) { + expect(codeOf(() => formatMoney(amount, 'en-US'))).toBe('X_MONEY_NOT_INTEGER'); + expect(codeOf(() => formatMoneyParts(amount, 'en-US'))).toBe('X_MONEY_NOT_INTEGER'); + expect(codeOf(() => formatMoneyDecimal(amount, 'en-US'))).toBe('X_MONEY_NOT_INTEGER'); + expect(codeOf(() => toDecimalString(amount))).toBe('X_MONEY_NOT_INTEGER'); + } + }); +}); diff --git a/packages/money/src/money.ts b/packages/money/src/money.ts index 3bdea299c..1541c3808 100644 --- a/packages/money/src/money.ts +++ b/packages/money/src/money.ts @@ -7,7 +7,7 @@ import { isMoneyScale, type MoneyValue } from '@ultimat3/schema'; import { assertCurrency, type CurrencyCode, exponentOf } from './currency'; import { decimalNotNumeric, decimalTooPrecise, moneyNotInteger } from './errors'; import { type RoundingMode, roundRatio } from './rounding'; -import { assertScale, commonScale, minorAt, moneyScale } from './scale'; +import { assertScale, commonScale, minorAt, minorOf, moneyScale } from './scale'; /** * `{ minor: 129900, currency: 'EUR' }` is €1,299.00. Instances are immutable, and now enforced @@ -106,10 +106,9 @@ export function fromDecimal( /** `1299 EUR` → `'12.99'`; `1200 JPY` → `'1200'`; `2 USD @ scale 6` → `'0.000002'`. */ export function toDecimalString(amount: Money): string { const exponent = moneyScale(amount); - const sign = amount.minor < 0 ? '-' : ''; - const digits = Math.abs(amount.minor) - .toString() - .padStart(exponent + 1, '0'); + const minor = minorOf(amount); + const sign = minor < 0n ? '-' : ''; + const digits = (minor < 0n ? -minor : minor).toString().padStart(exponent + 1, '0'); if (exponent === 0) return `${sign}${digits}`; return `${sign}${digits.slice(0, digits.length - exponent)}.${digits.slice(-exponent)}`; } diff --git a/packages/money/src/parse-input.test.ts b/packages/money/src/parse-input.test.ts index 3b9601337..828269e53 100644 --- a/packages/money/src/parse-input.test.ts +++ b/packages/money/src/parse-input.test.ts @@ -24,6 +24,9 @@ describe('parseAmount', () => { ['١٬٢٣٤٫٥٦', 'ar-EG', 'EGP', 123_456], ['1,200', 'ja-JP', 'JPY', 1_200], ['¥1200', 'ja-JP', 'JPY', 1_200], + // `ja-JP` writes the full-width ¥ (U+FFE5); a keyboard types the half-width ¥ (U+00A5). + ['¥1200', 'ja-JP', 'JPY', 1_200], + ['1,200¥', 'ja-JP', 'JPY', 1_200], ])('%s in %s as %s', (text, locale, currency, minor) => { expect(read(text, locale, currency)).toEqual({ minor, currency }); }); diff --git a/packages/money/src/parse-numerals.ts b/packages/money/src/parse-numerals.ts index 4c4322129..e62e376d0 100644 --- a/packages/money/src/parse-numerals.ts +++ b/packages/money/src/parse-numerals.ts @@ -131,8 +131,10 @@ function buildNotation(tag: string, code: string): AmountNotation { let parenthesised = false; for (const { parts } of candidates) { for (const each of parts) { - if (each.type === 'currency') marks.add(each.value); - else if (each.type === 'minusSign') minus.add(each.value); + if (each.type === 'currency') { + // And its compatibility form: `ja-JP` writes the full-width ¥, a keyboard types ¥. + marks.add(each.value).add(each.value.normalize('NFKC')); + } else if (each.type === 'minusSign') minus.add(each.value); else if (each.type === 'literal' && each.value.includes('(')) parenthesised = true; } } diff --git a/packages/money/src/rescale.ts b/packages/money/src/rescale.ts index 2399423c0..2457bab1b 100644 --- a/packages/money/src/rescale.ts +++ b/packages/money/src/rescale.ts @@ -7,7 +7,7 @@ import { rescaleNotExact } from './errors'; import { fromMinor, type Money } from './money'; import { type RoundingMode, roundRatio } from './rounding'; -import { assertScale, minorAt, moneyScale, toMinor } from './scale'; +import { assertScale, minorAt, minorOf, moneyScale, toMinor } from './scale'; /** * `rescale(fromMinor(80, 'USD'), 8)` → 80,000,000 hundred-millionths, the granularity a per-token @@ -26,7 +26,7 @@ export function rescale(amount: Money, scale: number, mode?: RoundingMode): Mone } const divisor = 10n ** BigInt(from - scale); - const numerator = BigInt(amount.minor); + const numerator = minorOf(amount); // An exact narrowing needs no mode: nothing is being decided, so nothing has to be declared. if (mode === undefined && numerator % divisor !== 0n) { throw rescaleNotExact(amount, from, scale); diff --git a/packages/money/src/scale.ts b/packages/money/src/scale.ts index 251df35f7..cc6a3fb11 100644 --- a/packages/money/src/scale.ts +++ b/packages/money/src/scale.ts @@ -6,7 +6,7 @@ import { isMoneyScale } from '@ultimat3/schema'; import { exponentOf } from './currency'; -import { scaleInvalid, scaleNotWidening, scaleOverflow } from './errors'; +import { moneyNotInteger, scaleInvalid, scaleNotWidening, scaleOverflow } from './errors'; import type { Money } from './money'; /** @@ -25,6 +25,16 @@ export function assertScale(scale: number): number { return scale; } +/** + * `amount.minor` as the bigint every exact operation works in, screened as `fromMinor()` screens + * it. `Money` is a type, not a check: a hand-built `{ minor: 12.5 }` reached `BigInt()` as a bare + * `RangeError`, and `NaN` reached a page as `$NaN`. + */ +export function minorOf(amount: Money): bigint { + if (!Number.isSafeInteger(amount.minor)) throw moneyNotInteger(amount.minor, amount.currency); + return BigInt(amount.minor); +} + /** * `amount.minor` restated at `scale`, exactly, as a bigint. * @@ -39,7 +49,7 @@ export function minorAt(amount: Money, scale: number): bigint { assertScale(scale); const from = moneyScale(amount); if (scale < from) throw scaleNotWidening(from, scale); - return BigInt(amount.minor) * 10n ** BigInt(scale - from); + return minorOf(amount) * 10n ** BigInt(scale - from); } /** The finer of two scales: where two values have to meet before they can be one number. */ diff --git a/packages/pwa/CLAUDE.md b/packages/pwa/CLAUDE.md index c3a44f80f..d282a80f8 100644 --- a/packages/pwa/CLAUDE.md +++ b/packages/pwa/CLAUDE.md @@ -29,7 +29,7 @@ role's boot loads, `@ultimat3/mcp/schema`'s shape; `serve-graph.test.ts` exempts | Rule patterns | built from the DECODED route path, matched against the PERCENT-ENCODED `url.pathname`: a literal segment is `@ultimat3/core`'s `literalSegmentPattern` — render's compiler too, never a local one. Raw or escaped, either hex case, so `/a\|b` owns `canonicalPath`'s `/a%7Cb` (the WHATWG-serializer copy here missed it until 31.40). A catch-all is `(?:/.*)?`, so `/docs/*path` owns `/docs`. `route-rules.test.ts`; the e2e drives both in Chrome. | | Runtime assets | `ServiceWorkerConfig.runtimeAssets` prefixes (`/islands/`) are `cache-first` runtime rules AHEAD of every page rule (`assetRules`, `route-rules.ts`), and go to the network as the browser asked — no build-id header, because a classic script is a `no-cors` request whose headers a worker may not extend. The precache names only what a precached page boots (the CLI chooses: `sw-precache-plan.ts`); all 43 islands (~1 MB) were precached on a first anonymous visit until 22.3.3. | | Precached assets | answered from the precache AHEAD of every rule (`precached-asset-source.ts`): first when revision = url, else network first. No rule read them before, `As of 2026-11`: offline documents rendered unstyled. | -| Pages cache | ≤ `PAGES_CACHE_MAX` (50) documents per cache, oldest written evicted (`putPage`). | +| Pages cache | ≤ `PAGES_CACHE_MAX` (50) documents per cache, oldest written evicted (`putPage`). A `redirected` answer is stored via `plain(r)`: as fetched, a navigation errors. | | Locales | the worker matches pathnames and the server strips `/en/` before it matches, so the CALLER spells every route once per routed locale (`@ultimat3/cli`'s `sw-precache-plan.ts`). `localePrefixes` is only for the offline document: a navigation under `/en/` tries `/en` + `OFFLINE_DOC` first. | | What is a navigation | to `offlineFallback`: `mode === 'navigate'`, or the client router's soft visit — a `fetch` carrying `CLIENT_NAVIGATION_HEADER: soft` (core's constant, interpolated). Its `prefetch` is a guess: the 503, or the offline page would be cached as a later click's answer. `offline-fallback.test.ts`. | | Precache revision | content hash. Never the build id — that re-downloads everything per deploy. | diff --git a/packages/pwa/src/pages-cache-source.ts b/packages/pwa/src/pages-cache-source.ts index 1d07dcd0b..9cbe42aaf 100644 --- a/packages/pwa/src/pages-cache-source.ts +++ b/packages/pwa/src/pages-cache-source.ts @@ -46,7 +46,7 @@ function isPrivate(r){ } // Every cache but the pages cache is GUARDED in both modes: a private response is never stored there. // A pages cache (\`bounded\`) is capped at PAGES_MAX documents, oldest WRITTEN out first. -function guarded(c,bounded){return{match:(req)=>c.match(req),put:async(req,r)=>{if(!isPrivate(r))return bounded?putPage(c,req,r):c.put(req,r)}}} +function guarded(c,bounded){return{match:(req)=>c.match(req),put:async(req,r)=>{if(!isPrivate(r))return bounded?putPage(c,req,r):c.put(req,plain(r))}}} // keys() is insertion order and a put re-appends, so the head is the page least recently stored. // One write at a time: a trim reads keys() and deletes by URL, so a refresh landing between the two // re-appended a page the trim then deleted — the page just written gone, an older one kept. @@ -54,7 +54,8 @@ const PAGES_MAX=${String(PAGES_CACHE_MAX)}; let paging=Promise.resolve(); function putPage(c,req,r){const run=paging.then(()=>putTrim(c,req,r));paging=run.catch(()=>{});return run} async function putTrim(c,req,r){ - await c.put(req,r); + // plain (the install block's): a redirected copy is a network error to a later navigation. + await c.put(req,plain(r)); const keys=await c.keys(); if(keys.length>PAGES_MAX)await Promise.all(keys.slice(0,keys.length-PAGES_MAX).map((k)=>c.delete(k))); } diff --git a/packages/pwa/src/service-worker-activate.test.ts b/packages/pwa/src/service-worker-activate.test.ts index 402cb3a84..ec86aa768 100644 --- a/packages/pwa/src/service-worker-activate.test.ts +++ b/packages/pwa/src/service-worker-activate.test.ts @@ -2,7 +2,8 @@ import { describe, expect, test } from 'bun:test'; import { generateServiceWorker } from './service-worker'; -import { config, SW_ORIGIN, swHarness } from './service-worker-harness-fixture'; +import type { StubCache } from './service-worker-harness-fixture'; +import { config, redirectedResponse, SW_ORIGIN, swHarness } from './service-worker-harness-fixture'; import type { PwaRoute } from './strategies'; /** One macrotask. The harness runs on promises alone, so a turn lets every pending step run. */ @@ -48,6 +49,21 @@ describe('the emitted activate block, executed', () => { expect(await response.text()).toBe('bytes for /feed'); }); + // The warm-up's request is the worker's own (`follow`), unlike the navigation it stands in for. + test('a warmed page that answered through a redirect is stored as a non-redirected response', async () => { + const sw = swHarness(); + sw.load(generateServiceWorker(runtimeRoutes, config, 'build-1').source); + sw.answerWith(() => redirectedResponse('the feed')); + sw.openWindows(`${SW_ORIGIN}/feed`); + await sw.activate(); + const holding = (): StubCache | undefined => + [...sw.caches.values()].find((cache) => cache.entries.has(`${SW_ORIGIN}/feed`)); + for (let turn = 0; turn < 50 && holding() === undefined; turn += 1) await settle(); + + expect(await (await holding()?.match('/feed'))?.text()).toBe('the feed'); + expect([...(holding()?.redirected ?? [])]).toEqual([]); + }); + test('a network-only route, another origin and a window with no URL are left alone', async () => { const sw = swHarness(); sw.load(generateServiceWorker(runtimeRoutes, config, 'build-1').source); diff --git a/packages/pwa/src/service-worker-harness-fixture.ts b/packages/pwa/src/service-worker-harness-fixture.ts index 02882f004..1be4fd11b 100644 --- a/packages/pwa/src/service-worker-harness-fixture.ts +++ b/packages/pwa/src/service-worker-harness-fixture.ts @@ -51,6 +51,11 @@ export class NavigationRequest extends SwRequest { /** Keyed by absolute URL, exactly as `Cache` is with `ignoreSearch` at its default `false`. */ export class StubCache { readonly entries = new Map(); + /** + * Keys stored from a response that was `redirected`. A browser refuses such an entry as the + * answer to a navigation (redirect mode `manual`): the tab gets a network error, not the page. + */ + readonly redirected = new Set(); #fetch: (request: Request) => Promise; constructor(fetcher: (request: Request) => Promise) { @@ -72,6 +77,8 @@ export class StubCache { // Delete, then set: the real `put` drops the matching entry and appends the new one, so a // re-stored URL moves to the END of `keys()` — the order the pages cache's eviction reads. this.entries.delete(this.#key(request)); + if (response.redirected) this.redirected.add(this.#key(request)); + else this.redirected.delete(this.#key(request)); this.entries.set( this.#key(request), new Response(bytes, { status: response.status, headers: response.headers }), @@ -98,6 +105,19 @@ export class StubCache { } } +/** What `fetch` answers after following a redirect: the target's bytes, flagged `redirected`. */ +export function redirectedResponse(body: string): Response { + return flagRedirected(new Response(body, { status: 200 })); +} + +/** A clone of a redirected response is redirected too, as a browser's is. */ +function flagRedirected(response: Response): Response { + const clone = response.clone.bind(response); + Object.defineProperty(response, 'redirected', { value: true }); + Object.defineProperty(response, 'clone', { value: () => flagRedirected(clone()) }); + return response; +} + export function swHarness() { const fetched: string[] = []; /** The `x-ultimate-build` each proxied request carried, in order. `null` means unstamped. */ diff --git a/packages/pwa/src/service-worker-runtime.test.ts b/packages/pwa/src/service-worker-runtime.test.ts index 70037fd3c..78f56e58c 100644 --- a/packages/pwa/src/service-worker-runtime.test.ts +++ b/packages/pwa/src/service-worker-runtime.test.ts @@ -8,7 +8,7 @@ import { OUTBOX_DRAIN_MESSAGE } from '@ultimat3/core'; import { PAGES_CACHE_MAX } from './pages-cache-source'; import type { ServiceWorkerConfig } from './service-worker'; import { generateServiceWorker } from './service-worker'; -import { config, swHarness } from './service-worker-harness-fixture'; +import { config, redirectedResponse, swHarness } from './service-worker-harness-fixture'; import type { PwaRoute } from './strategies'; import { cacheNamespace } from './version-skew'; @@ -95,6 +95,22 @@ describe('the emitted install block, executed', () => { expect(keys).toContain('https://app.test/offline'); }); + // Fetch's rule: a response whose URL list is longer than one answers a request with redirect + // mode `follow` only, and a navigation's is `manual` — so `/offline` precached through a + // trailing-slash or locale redirect was a network error exactly when it was needed. + test('a precache entry that answered through a redirect is stored as a non-redirected response', async () => { + const sw = swHarness(); + sw.load(generateServiceWorker(precached, config, 'build-1').source); + sw.answerWith((request) => + new URL(request.url).pathname === '/offline' ? redirectedResponse('offline page') : undefined, + ); + await sw.install(); + + const cache = sw.caches.get(cacheNamespace('build-1', 'precache')); + expect(await (await cache?.match('/offline'))?.text()).toBe('offline page'); + expect([...(cache?.redirected ?? [])]).toEqual([]); + }); + test('fetches each entry revision-addressed, so a deploy re-downloads only what changed', async () => { const sw = swHarness(); sw.load(generateServiceWorker(precached, config, 'build-1').source); diff --git a/packages/pwa/src/service-worker.ts b/packages/pwa/src/service-worker.ts index 246b35c3a..caf44ebce 100644 --- a/packages/pwa/src/service-worker.ts +++ b/packages/pwa/src/service-worker.ts @@ -275,13 +275,17 @@ self.addEventListener('install',(event)=>{ const r=await fetch(new Request(e.url+(e.url.indexOf('?')<0?'?':'&')+'v='+e.revision,{cache:'reload'})); // Mid-rollout an OLD pod may answer: its document is not this build's offline copy. const b=r.headers.get(BUILD_HEADER); - if(r.ok&&(b===null||b===BUILD_ID))await cache.put(new Request(e.url),r); + if(r.ok&&(b===null||b===BUILD_ID))await cache.put(new Request(e.url),plain(r)); }catch(err){} } }; await Promise.all(Array.from({length:${PRECACHE_CONCURRENCY}},next)); })()); -});`.trim(); +}); +// A response that followed a redirect answers a \`follow\` request only, and a navigation's mode is +// \`manual\`: stored as fetched, a precached or warmed document was a network error to the tab that +// navigated to it offline. Stored as a response of its own, with the same body, status and headers. +function plain(r){return r.redirected?new Response(r.body,{status:r.status,statusText:r.statusText,headers:r.headers}):r}`.trim(); function activateBlock(): string { return ` diff --git a/packages/query/src/download-http.test.ts b/packages/query/src/download-http.test.ts index 5e7a51f9b..61031c832 100644 --- a/packages/query/src/download-http.test.ts +++ b/packages/query/src/download-http.test.ts @@ -3,7 +3,7 @@ // the policy at mint, an expired, forged or re-pointed token at serve — answers its own status. import { describe, expect, test } from 'bun:test'; -import { ctxOf, frozenClock, open, seal, userActor } from '@ultimat3/core'; +import { collectMetrics, ctxOf, frozenClock, open, seal, userActor } from '@ultimat3/core'; import type { HttpConfig } from '@ultimat3/http'; import { defineHttpConfig, httpServer } from '@ultimat3/http'; import type { Actor } from '@ultimat3/policy'; @@ -354,3 +354,36 @@ describe('the token', () => { } }); }); + +describe('a deprecated download', () => { + const calls = (): number => + collectMetrics() + .metrics.find((entry) => entry.descriptor.name === 'deprecated_calls_total') + ?.points.find( + (point) => + point.attributes['primitive'] === 'query' && point.attributes['name'] === 'oldRecording', + )?.value ?? 0; + + test("a deprecated download's mint is counted once", async () => { + const old = query({ + input: Input, + policy: can('recording:read'), + deprecated: { since: '2026-08-01T00:00:00Z', sunset: '2027-01-01T00:00:00Z' }, + download: { + async handle() { + return { body: VIDEO, contentType: 'video/mp4', filename: 'old.mp4' }; + }, + }, + }).named('oldRecording'); + const server = serve(old, viewer); + const before = calls(); + const minted = await get(server, `/_x/query/old-recording?runId=${RUN}`); + expect(minted.status).toBe(200); + expect(minted.headers.get('deprecation')).not.toBeNull(); + expect(calls()).toBe(before + 1); + // The serve is the player's fetch of a URL the counted mint handed out — never a second call. + const { url } = (await minted.json()) as { url: string }; + expect((await get(server, url)).status).toBe(200); + expect(calls()).toBe(before + 1); + }); +}); diff --git a/packages/query/src/download-http.ts b/packages/query/src/download-http.ts index a5dabc2b4..3bec3b460 100644 --- a/packages/query/src/download-http.ts +++ b/packages/query/src/download-http.ts @@ -5,7 +5,7 @@ * `content-disposition`, one `Range:` window, and `no-store` — the bytes are one actor's. */ -import { assert, queryPath, useContext } from '@ultimat3/core'; +import { assert, queryPath, recordDeprecatedCall, useContext } from '@ultimat3/core'; import type { RateLimitDecision, Route, RouteMeta, UltimateRequest } from '@ultimat3/http'; import { byteWindow, @@ -46,6 +46,9 @@ export function toDownloadRoute( } const input = absentArraysOf(target.input, coerceQuery(target.input, rest)); if (token === undefined) { + // The MINT is the call a caller makes; a serve is a player's fetch, often many `Range:` + // windows, of a URL this already counted — so only the mint counts, as a rows read does. + if (sunsetting !== undefined) recordDeprecatedCall('query', name); const minted = await mintDownloadUrl(target, input, { surface: 'http', clientAddress: request.ctx.ip, diff --git a/packages/query/src/download.test.ts b/packages/query/src/download.test.ts index c2a75c2ef..b25cb30f1 100644 --- a/packages/query/src/download.test.ts +++ b/packages/query/src/download.test.ts @@ -4,11 +4,13 @@ import { describe, expect, test } from 'bun:test'; import { ctxOf, frozenClock, isUltimateError, userActor } from '@ultimat3/core'; +import { defineHttpConfig, httpServer } from '@ultimat3/http'; import type { Actor } from '@ultimat3/policy'; import { can } from '@ultimat3/policy'; import { t } from '@ultimat3/schema'; import type { DownloadQuery, DownloadQueryDef } from './download'; import { serveDownloadFile } from './download'; +import { toQueryRoute } from './http'; import { query, sourceFor } from './query'; import { describeSql } from './sql'; @@ -213,3 +215,56 @@ describe('what a token binds', () => { expect(tokenOf(url)).toMatch(/^x1\.[0-9a-f]{16}\./); }); }); + +describe('a URL is minted for the input it re-parses to', () => { + const Filtered = t.object({ + runId: t.uuid, + note: t.string.nullable().optional(), + tags: t.array(t.string).optional(), + }); + const filtered = () => + query({ + input: Filtered, + policy: can('recording:read'), + download: { + async handle() { + return { body: BYTES, contentType: 'video/mp4', filename: 'run.mp4' }; + }, + }, + }).named('runFiltered'); + + test('a URL minted with a null or empty-array optional member serves', async () => { + const target = filtered(); + const server = httpServer({ + routes: [toQueryRoute(target)], + config: defineHttpConfig({ rateLimit: { scope: 'process' } }), + hooks: { authenticate: () => null }, + }); + const ctx = { ctx: ctxOf({ actor: viewer() }) }; + for (const input of [ + { runId: RUN, note: null }, + { runId: RUN, tags: [] }, + { runId: RUN, note: null, tags: [] }, + { runId: RUN, tags: ['a', 'b'] }, + ]) { + const { url } = await target.url(input, ctx); + const response = await server.fetch(new Request(`http://dev.test${url}`)); + expect([input, response.status]).toEqual([input, 200]); + } + }); + + test('the URL still binds its input: a member added to it is refused', async () => { + const target = filtered(); + const server = httpServer({ + routes: [toQueryRoute(target)], + config: defineHttpConfig({ rateLimit: { scope: 'process' } }), + hooks: { authenticate: () => null }, + }); + const { url } = await target.url({ runId: RUN, tags: [] }, { ctx: ctxOf({ actor: viewer() }) }); + const response = await server.fetch(new Request(`http://dev.test${url}&tags=x`)); + expect(response.status).toBe(403); + expect(((await response.json()) as { code: string }).code).toBe( + 'X_QUERY_DOWNLOAD_TOKEN_INVALID', + ); + }); +}); diff --git a/packages/query/src/download.ts b/packages/query/src/download.ts index 021be487b..482956ae3 100644 --- a/packages/query/src/download.ts +++ b/packages/query/src/download.ts @@ -15,6 +15,7 @@ import type { Ctx, Deprecation } from '@ultimat3/core'; import { queryPath, useContext } from '@ultimat3/core'; import type { RequestedRange } from '@ultimat3/http'; import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema'; +import { coerceQuery } from '@ultimat3/schema'; import type { DownloadUrl, QueryCallOptions, QueryClientOptions } from './client'; import { downloadClientFor } from './client'; import { QueryDownloadInvalidError, QueryDownloadOnlyError } from './download-errors'; @@ -24,10 +25,12 @@ import { mintDownloadToken, openDownloadToken, } from './download-token'; +import { absentArraysOf } from './input-shape'; import type { QueryPolicy } from './policy-gate'; import type { AnyQuery, AnyQueryDef, QueryDescriptor, QueryOptions, QueryRateLimit } from './query'; import { admittedCall, defOf, queryName, stashDef } from './read'; import { searchOf } from './search-string'; +import { parsedOrNothing } from './validate'; export type { DownloadUrl } from './client'; @@ -212,7 +215,10 @@ export function readDownloadFile( /** * Admit the caller exactly as a read would, then seal the decision. The URL carries the input as - * it was HANDED in (the route re-parses it to the same value) and the token binds the PARSED one. + * it was HANDED in, and the token binds what the ROUTE will parse that URL back to — never the + * admitted value itself: a search string has no `null` and no empty list, so `{ note: null }` or + * `{ tags: [] }` on an optional member arrives absent, and a token bound to the admitted value + * refused every URL minted with one. */ export function mintDownloadUrl( target: AnyQuery, @@ -223,8 +229,9 @@ export function mintDownloadUrl( const ttl = handlerOf(target).expiresInMs ?? DEFAULT_DOWNLOAD_TTL_MS; return admittedCall(target, raw, options, async (input, ctx) => { const expiresAtMs = ctx.now().getTime() + ttl; - const token = await mintDownloadToken(name, input, ctx.actor, expiresAtMs); const search = searchOf(raw); + const granted = (await wireInputOf(target.input, search)) ?? input; + const token = await mintDownloadToken(name, granted, ctx.actor, expiresAtMs); const tokenParam = `${DOWNLOAD_GRANT_PARAM}=${encodeURIComponent(token)}`; return { url: `${queryPath(name)}?${search === '' ? '' : `${search}&`}${tokenParam}`, @@ -233,6 +240,23 @@ export function mintDownloadUrl( }); } +/** + * The input `toDownloadRoute` parses `search` back to — the same `coerceQuery` + `absentArraysOf` + * + schema parse, over the same repeated-key-is-a-list reading of the string. `undefined` when it + * does not parse: that URL is refused at serve whatever the token binds, so the admitted value + * stands, as it did before. + */ +async function wireInputOf(schema: StandardSchemaV1, search: string): Promise { + const values: Record = Object.create(null); + for (const [key, value] of new URLSearchParams(search)) { + const seen = values[key]; + if (seen === undefined) values[key] = value; + else if (Array.isArray(seen)) seen.push(value); + else values[key] = [seen, value]; + } + return parsedOrNothing(schema, absentArraysOf(schema, coerceQuery(schema, values))); +} + /** * The file a token grants: the token opened against THIS query and THIS input on the context's * clock, then `handle` as the minting actor. The input is still parsed — `handle` is owed the diff --git a/packages/realtime/CLAUDE.md b/packages/realtime/CLAUDE.md index 690b050a9..586285e61 100644 --- a/packages/realtime/CLAUDE.md +++ b/packages/realtime/CLAUDE.md @@ -172,7 +172,8 @@ A rule marked `†` has its full text in [`docs/history/realtime-rules.md`](../. - **A channel is a DECLARATION, no primitive** (docs/history/primitive-factories.md): `channel(name, { params, policy, catchUp, records?, events? })`, deny by default; `policy` REQUIRED (`X_CHANNEL_DECLARATION_INVALID`; public: `allow('public')`). Presence: `events`. -- **A param naming a records entity's `$tenantColumn` is the subscriber's org** (`channel-tenant.ts`, before the policy). † +- **A `$tenantColumn` param is the subscriber's org; elsewhere a tenanted row reaches only its + tenant** (`channel-tenant.ts`). † - **A guard that FAILS on re-auth SUSPENDS the seat** (`guardFailures`): kept, silent until a pass. A `null` actor on a `row` channel and a tenancy refusal are DENIALS. - **A seat is decided for the actor ON the socket when the guard resolves** (`#settle`); a denied diff --git a/packages/realtime/src/channel-authz.ts b/packages/realtime/src/channel-authz.ts index 9fd14a452..1d51ffc58 100644 --- a/packages/realtime/src/channel-authz.ts +++ b/packages/realtime/src/channel-authz.ts @@ -2,11 +2,12 @@ // with the params as input and the row the channel's own loader answered. Through // `@ultimat3/query`'s `guardQuery`, the package's one authz seam — the call `policy-gate.ts` makes. -import { type Actor, type Ctx, ctxOf, runWithContext } from '@ultimat3/core'; +import { type Actor, type Ctx, runWithContext } from '@ultimat3/core'; import { guardQuery, QueryDeniedError } from '@ultimat3/query'; import type { Channel } from './channel-decl'; import { assertChannelTenant } from './channel-tenant'; import { isTenancyDenial, TopicForbiddenError } from './errors'; +import { subscriberContext } from './policy-gate'; /** * A denial is `X_TOPIC_FORBIDDEN`. A loader or a rule that RAISED is not a denial and leaves as it @@ -74,15 +75,3 @@ function decide( }); } } - -/** The node's context, re-made for one subscriber: same deploy, role and clock, their actor. */ -function subscriberContext(node: Ctx, actor: Actor): Ctx { - return ctxOf({ - actor, - role: node.role, - buildId: node.buildId, - clock: node.clock, - locale: node.locale, - tz: node.tz, - }); -} diff --git a/packages/realtime/src/channel-decl.ts b/packages/realtime/src/channel-decl.ts index 23f90f846..ca31ee6b0 100644 --- a/packages/realtime/src/channel-decl.ts +++ b/packages/realtime/src/channel-decl.ts @@ -72,8 +72,8 @@ export interface ChannelServerInit { * Evaluated on subscribe: the params are the input, and `row` is what the loader below answered * (`null` without one). REQUIRED, as on an `action` and a `query`: it was optional, and an omitted * one let any socket — anonymous included — join with any param and receive every committed row. - * A public channel says so with `allow('public')`. Records are NOT gated per row — the topic's - * params are the scope, so a channel that must hide rows is declared narrower. + * A public channel says so with `allow('public')`. Records are NOT gated per row by the policy — + * the topic's params are its scope; only a row's TENANT is checked per member (`rowTenant`). */ readonly policy: QueryPolicy; /** diff --git a/packages/realtime/src/channel-logs.ts b/packages/realtime/src/channel-logs.ts index 5f92ab4c9..1ca027d02 100644 --- a/packages/realtime/src/channel-logs.ts +++ b/packages/realtime/src/channel-logs.ts @@ -7,9 +7,10 @@ import type { ChangeEvent } from './changefeed'; import type { Channel } from './channel-decl'; import { carriesTable, updatesFor } from './channel-records'; import { renderRecords } from './channel-render'; -import { ChannelRing } from './channel-ring'; +import { ChannelRing, type RecordsEntry } from './channel-ring'; +import { type Audience, admitsTenant, rowTenant } from './channel-tenant'; import type { ChannelSince, ReplayGapFrame } from './channel-wire'; -import type { SocketRegistry, SyncSocket } from './socket'; +import { deliverRecordsTo, type SocketRegistry, type SyncSocket } from './socket'; import { PROTOCOL_VERSION } from './sync-protocol'; /** What a joined topic resolves to. A topic is `name.params…`, so it names both exactly. */ @@ -79,9 +80,22 @@ export class ChannelLogs { frames += this.#reopen(update.topic, open.target); continue; } - const entry = open.ring.append(update.adopt, update.remove, change.write ?? undefined); - const frame = renderRecords(update.topic, open.ring.epoch, entry); - frames += this.#sockets.deliverRecords(update.topic, open.ring.epoch, frame); + const tenant = rowTenant(update.channel, change.table, update.row); + const write = change.write ?? undefined; + const entry = open.ring.append(update.adopt, update.remove, write, tenant); + const epoch = open.ring.epoch; + const frame = renderRecords(update.topic, epoch, entry); + const audience: Audience | undefined = + tenant === undefined + ? undefined + : { + admits: (actor) => admitsTenant(actor, tenant), + withheld: renderRecords(update.topic, epoch, withheld(entry)), + }; + frames += + audience === undefined + ? this.#sockets.deliverRecords(update.topic, epoch, frame) + : deliverRecordsTo(this.#sockets, update.topic, epoch, frame, audience); } return frames; } @@ -127,6 +141,9 @@ export class ChannelLogs { * A `since` that is already CURRENT is answered too: the frame AT its cursor, carrying nothing. * Sent nothing, the client had no frame to leave `joining` on — a channel that was up to date * read as never joined. The seq is one it already holds, so its cursor does not move. + * + * A replayed entry holding another tenant's rows (`RecordsEntry.tenant`) is sent as its seq alone, + * exactly as the live frame was: a later joiner is never shown what a live member was not. */ resume(socket: SyncSocket, topic: string, since: ChannelSince | undefined, fresh: boolean): void { const open = this.#byTopic.get(topic); @@ -146,10 +163,19 @@ export class ChannelLogs { } const answer = entries.length > 0 ? entries : [{ seq: open.ring.seq, adopt: [], remove: [] }]; for (const entry of answer) { - if (!socket.send(renderRecords(topic, open.ring.epoch, entry))) { + const shown = admitsTenant(socket.actor, entry.tenant) ? entry : withheld(entry); + if (!socket.send(renderRecords(topic, open.ring.epoch, shown))) { socket.gaps.set(topic, open.ring.epoch); return; } } } } + +/** + * One entry as a member outside its tenant receives it: the seq, so the cursor stays contiguous and + * no `replay-gap` is owed, and nothing else — no row, no key, and no write id to match an echo on. + */ +function withheld(entry: RecordsEntry): RecordsEntry { + return { seq: entry.seq, adopt: [], remove: [] }; +} diff --git a/packages/realtime/src/channel-records.ts b/packages/realtime/src/channel-records.ts index 6d89e6bc5..e0e4596ac 100644 --- a/packages/realtime/src/channel-records.ts +++ b/packages/realtime/src/channel-records.ts @@ -1,6 +1,6 @@ // A committed change → the record updates each declared channel owes its subscribers. Pure: no -// socket, no seq, no policy — `ChannelHub` does those per node and per socket. The only derivation -// of "which channel carries this row" lives here, so a write never names a channel (axiom 2). +// socket, no seq, no policy, no tenant — `ChannelHub` does those per node and per socket. The only +// derivation of "which channel carries this row" lives here, so a write never names a channel. import { type Counter, counter, logger } from '@ultimat3/core'; import type { Row } from '@ultimat3/core/page'; @@ -9,7 +9,10 @@ import type { ChangeEvent } from './changefeed'; import type { Channel, Topic } from './channel-decl'; import type { RecordPart } from './channel-ring'; -/** One topic's share of one change. `row` is what a per-row policy decides on. */ +/** + * One topic's share of one change. `row` is the image it came from: no policy re-decides it, but + * its tenant decides which of the topic's members are shown it (`rowTenant`, `channel-tenant.ts`). + */ export interface TopicUpdate { readonly channel: Channel; readonly topic: Topic; diff --git a/packages/realtime/src/channel-render.ts b/packages/realtime/src/channel-render.ts index 6fbe02850..63ca82f2d 100644 --- a/packages/realtime/src/channel-render.ts +++ b/packages/realtime/src/channel-render.ts @@ -1,5 +1,5 @@ -// One ring entry → the `records` frame every member of its topic receives. The same frame for all -// of them: a channel's scope is its params, decided once at subscribe, never re-decided per row. +// One ring entry → the `records` frame its topic's members receive. The same frame for all of them, +// but for an entry holding another tenant's rows (`RecordsEntry.tenant`): that member gets its seq. import type { Row } from '@ultimat3/core/page'; import type { RecordsEntry } from './channel-ring'; diff --git a/packages/realtime/src/channel-ring.ts b/packages/realtime/src/channel-ring.ts index ab3890a5f..8a33a230d 100644 --- a/packages/realtime/src/channel-ring.ts +++ b/packages/realtime/src/channel-ring.ts @@ -12,6 +12,11 @@ export interface RecordsEntry { readonly remove: readonly { readonly type: string; readonly key: string }[]; /** The write that produced the change (`ChangeEvent.write`), kept so a replay still names it. */ readonly write?: string; + /** + * Present when the rows are one tenant's on a topic that is not that tenant's (`rowTenant`): only + * its members are shown them, live or replayed. `null`: the row named no tenant — nobody is. + */ + readonly tenant?: string | null; } export interface RecordPart { @@ -48,6 +53,7 @@ export class ChannelRing { adopt: readonly RecordPart[], remove: RecordsEntry['remove'], write?: string, + tenant?: string | null, ): RecordsEntry { this.#seq += 1; const entry: RecordsEntry = { @@ -55,6 +61,7 @@ export class ChannelRing { adopt, remove, ...(write === undefined ? {} : { write }), + ...(tenant === undefined ? {} : { tenant }), }; this.#entries.push(entry); if (this.#entries.length > this.#capacity) this.#entries.shift(); diff --git a/packages/realtime/src/channel-tenant.test.ts b/packages/realtime/src/channel-tenant.test.ts index e97c67771..0497b87a0 100644 --- a/packages/realtime/src/channel-tenant.test.ts +++ b/packages/realtime/src/channel-tenant.test.ts @@ -11,8 +11,10 @@ import { ChannelHub } from './channel'; import { channel } from './channel-decl'; import { presenceEvent } from './channel-presence'; import { clearChannels } from './channel-registry'; +import type { ChannelRecordsFrame } from './channel-wire'; import { TopicForbiddenError } from './errors'; import { InProcessTransport } from './fanout'; +import type { LiveRow } from './json'; import { SocketRegistry, SyncSocket, type WsLike } from './socket'; const ORG_A = '00000000-0000-4000-8000-00000000000a'; @@ -21,6 +23,14 @@ const ORG_B = '00000000-0000-4000-8000-00000000000b'; const posts = entity('channel_tenant_posts', { columns: { id: uuid().primaryKey(), orgId: uuid(), title: text() }, }); +/** Tenanted rows routed by a param that is NOT the tenant column: one room, any org's rows. */ +const messages = entity('channel_tenant_messages', { + columns: { id: uuid().primaryKey(), orgId: uuid(), roomId: text(), body: text() }, +}); +/** An untenanted table: no org column, so nothing about its rows is any tenant's. */ +const notes = entity('channel_tenant_notes', { + columns: { id: uuid().primaryKey(), roomId: text(), body: text() }, +}); afterAll(() => { clearRegistry(); @@ -54,6 +64,14 @@ const room = channel('tenant-room', { events: true, }); +/** Keyed by `roomId`, so the subscribe decides nothing about the rows' tenant. */ +const roomFeed = channel('tenant-room-feed', { + params: ['roomId'], + catchUp: { name: 'tenantRoomFeed' }, + policy: anyReader, + records: [messages, notes], +}); + type Wire = { readonly type: string } & Record; class FakeWs implements WsLike { @@ -78,7 +96,11 @@ let hub: ChannelHub; beforeEach(() => { sockets = new SocketRegistry(); - hub = new ChannelHub({ transport: new InProcessTransport(), sockets, channels: [orgFeed, room] }); + hub = new ChannelHub({ + transport: new InProcessTransport(), + sockets, + channels: [orgFeed, room, roomFeed], + }); }); function connect(actor: Actor): { socket: SyncSocket; ws: FakeWs } { @@ -165,3 +187,94 @@ describe('a channel with no tenant param', () => { expect(orphan.ws.of('events')).toHaveLength(1); }); }); + +const MESSAGE_ID = '00000000-0000-4000-8000-0000000000b1'; +const message = (orgId: string): LiveRow => ({ + id: MESSAGE_ID, + orgId, + roomId: 'lobby', + body: 'org B payroll', +}); +const change = ( + table: string, + op: 'insert' | 'delete', + row: LiveRow, + lsn: string, + orgId: string | null = null, +): ChangeEvent => ({ + table, + op, + before: op === 'delete' ? row : null, + after: op === 'delete' ? null : row, + lsn, + txid: lsn, + orgId, + at: 0, + write: 'w-1', +}); +const joinRoom = (socket: SyncSocket, since?: { epoch: string; seq: number }) => + hub.subscribeChannel(socket, { + kind: 'channel', + channel: 'tenant-room-feed', + params: { roomId: 'lobby' }, + ...(since === undefined ? {} : { since }), + }); +const isRecords = (frame: Wire): frame is Wire & ChannelRecordsFrame => frame.type === 'records'; +/** The `records` frames a socket received, typed as the wire declares them. */ +const recordsOf = (ws: FakeWs): ChannelRecordsFrame[] => ws.frames.filter(isRecords); +/** Every record key a socket was handed, adopted or removed, across its `records` frames. */ +const keysSeen = (ws: FakeWs): string[] => + recordsOf(ws).flatMap((frame) => [ + ...Object.values(frame.adopt ?? {}).flatMap((byKey) => Object.keys(byKey)), + ...Object.values(frame.remove ?? {}).flat(), + ]); + +describe('a records channel keyed by a non-tenant param', () => { + test("a records channel keyed by a non-tenant param carries no other tenant's rows", async () => { + const alice = connect(userActor({ id: 'alice', orgId: ORG_A })); + const bob = connect(userActor({ id: 'bob', orgId: ORG_B })); + await joinRoom(alice.socket); + await joinRoom(bob.socket); + + hub.deliverChange(change('channel_tenant_messages', 'insert', message(ORG_B), '1', ORG_B)); + hub.deliverChange(change('channel_tenant_messages', 'delete', message(ORG_B), '2', ORG_B)); + + // Org B's member is handed both: the witness that the traffic was real. + expect(keysSeen(bob.ws)).toEqual([MESSAGE_ID, MESSAGE_ID]); + // Org A's member sees the seq advance and nothing else: no row, no key, no write id. + expect(keysSeen(alice.ws)).toEqual([]); + const withheld = recordsOf(alice.ws); + expect(withheld.map((frame) => frame.seq)).toEqual([1, 2]); + expect(withheld.some((frame) => 'write' in frame)).toBe(false); + + // A later org-A joiner resuming from before both changes is replayed the same nothing. + const epoch = withheld[0]?.epoch ?? ''; + const carol = connect(userActor({ id: 'carol', orgId: ORG_A })); + await joinRoom(carol.socket, { epoch, seq: 0 }); + expect(recordsOf(carol.ws).map((frame) => frame.seq)).toEqual([1, 2]); + expect(keysSeen(carol.ws)).toEqual([]); + // ...while an org-B joiner resuming the same way is replayed both. + const dave = connect(userActor({ id: 'dave', orgId: ORG_B })); + await joinRoom(dave.socket, { epoch, seq: 0 }); + expect(keysSeen(dave.ws)).toEqual([MESSAGE_ID, MESSAGE_ID]); + }); + + test("an untenanted table's rows reach every member, org or none, exactly as before", async () => { + const alice = connect(userActor({ id: 'alice', orgId: ORG_A })); + const orphan = connect(userActor({ id: 'orphan' })); + await joinRoom(alice.socket); + await joinRoom(orphan.socket); + const note = { id: MESSAGE_ID, roomId: 'lobby', body: 'hello' }; + hub.deliverChange(change('channel_tenant_notes', 'insert', note, '1')); + expect(keysSeen(alice.ws)).toEqual([MESSAGE_ID]); + expect(keysSeen(orphan.ws)).toEqual([MESSAGE_ID]); + expect(recordsOf(alice.ws)[0]?.write).toBe('w-1'); + }); + + test('a member with no org is handed no tenanted row', async () => { + const orphan = connect(userActor({ id: 'orphan' })); + await joinRoom(orphan.socket); + hub.deliverChange(change('channel_tenant_messages', 'insert', message(ORG_B), '1', ORG_B)); + expect(keysSeen(orphan.ws)).toEqual([]); + }); +}); diff --git a/packages/realtime/src/channel-tenant.ts b/packages/realtime/src/channel-tenant.ts index 8d0c59f3d..a4efebdb0 100644 --- a/packages/realtime/src/channel-tenant.ts +++ b/packages/realtime/src/channel-tenant.ts @@ -1,12 +1,14 @@ -// The tenant half of a channel subscribe: a param that names a records entity's tenant column must -// be the subscriber's own org. Decided by `@ultimat3/entity`'s own guard (`assertScoped`), so a -// socket is held to the rule an HTTP read is — never a second copy of it, and never left to a policy. +// The tenant half of a channel: a param that names a records entity's tenant column must be the +// subscriber's own org, decided at subscribe by `@ultimat3/entity`'s own guard (`assertScoped`); a +// tenanted row on a topic NOT keyed by its tenant column reaches only that tenant's members. import { type Actor, type Ctx, isUltimateError, runWithContext } from '@ultimat3/core'; import { assertScoped, type QueryPlan } from '@ultimat3/entity'; -import { tenantColumnOfTable } from './change-tenant'; +import { tenantColumnOfTable, tenantIn } from './change-tenant'; import type { Channel } from './channel-decl'; +import type { ChannelRecordsFrame } from './channel-wire'; import { isTenancyDenial, TopicForbiddenError } from './errors'; +import type { SocketRegistry } from './socket'; /** * A row is routed to the topic its own params name (`channel-records.ts`), so a topic keyed by the @@ -53,3 +55,50 @@ export function assertChannelTenant( } } } + +/** + * Who may read one change's rows on `channel`: `undefined` for everyone on the topic — an untenanted + * table, or a channel keyed by the tenant column, whose subscribe already proved the tenant + * (`assertChannelTenant`) — else the tenant `row` names, `null` when it names none (no member). + * + * A topic keyed by `roomId` carries every org's rows that name that room, and its policy decided a + * permission, not a tenant: `can('message:read')` admitted org A to org B's room. The subscribe + * cannot decide this (the rows are not known yet), so delivery and ring replay do, per row. + */ +export function rowTenant( + channel: Channel, + table: string, + row: Readonly>, +): string | null | undefined { + const column = tenantColumnOfTable(table); + if (column === null || channel.params.includes(column)) return undefined; + return tenantIn(column, row); +} + +/** + * `assertScoped`'s verdict for a plan naming `tenant`, without a context to run it in: the actor's + * own org, and nothing else. A `crossTenant()` scope is never open around a delivery — it is a + * change, not a call — so there is no proof of one to honour here. + */ +export function admitsTenant(actor: Actor | null, tenant: string | null | undefined): boolean { + if (tenant === undefined) return true; + return tenant !== null && actor !== null && actor.orgId !== undefined && actor.orgId === tenant; +} + +/** + * A records frame's audience when it carries one tenant's rows (`rowTenant`): a member `admits` + * takes gets the frame, every other member `withheld` — the same seq, carrying nothing. + */ +export interface Audience { + readonly admits: (actor: Actor | null) => boolean; + readonly withheld: ChannelRecordsFrame; +} + +/** `socket.ts`'s `deliverRecordsTo`: one records frame to a topic's members, scoped by `to`. */ +export type DeliverRecordsTo = ( + registry: SocketRegistry, + topic: string, + epoch: string, + frame: ChannelRecordsFrame, + to: Audience, +) => number; diff --git a/packages/realtime/src/fanout.ts b/packages/realtime/src/fanout.ts index e1dc877f0..163845630 100644 --- a/packages/realtime/src/fanout.ts +++ b/packages/realtime/src/fanout.ts @@ -69,17 +69,34 @@ export interface InProcessTransportOptions { class InProcessSet implements TransportSet { readonly #keys = new Map>(); readonly #clock: Clock; + #prunedAt = 0; constructor(clock: Clock) { this.#clock = clock; } async put(key: string, member: string, value: string, ttlMs: number): Promise { + const now = this.#clock.now().getTime(); + if (now >= this.#prunedAt + ttlMs) this.#prune(now); const bucket = this.#keys.get(key) ?? new Map(); - bucket.set(member, { member, value, expiresAt: this.#clock.now().getTime() + ttlMs }); + bucket.set(member, { member, value, expiresAt: now + ttlMs }); this.#keys.set(key, bucket); } + /** + * Expiry on the store's own clock, as the KV's server does it (`nats-kv.ts`). Read-time expiry + * alone kept every key nobody reads again — a forgotten room's sweep lease, which must outlive + * the room by one TTL so a follower reads its last roster — for the life of the process. A full + * pass at most once per TTL, the interval `sweepAll` already walks every room on. + */ + #prune(now: number): void { + this.#prunedAt = now; + for (const [key, bucket] of this.#keys) { + for (const entry of bucket.values()) if (entry.expiresAt <= now) bucket.delete(entry.member); + if (bucket.size === 0) this.#keys.delete(key); + } + } + async touch(key: string, member: string, ttlMs: number): Promise { const entry = this.#keys.get(key)?.get(member); if (!entry || entry.expiresAt <= this.#clock.now().getTime()) return false; @@ -104,18 +121,24 @@ class InProcessSet implements TransportSet { } return live; } + + get size(): number { + return this.#keys.size; + } } /** Single-node default: `x dev`, tests, and small deployments that have not earned a bus yet. */ export class InProcessTransport implements Transport { readonly name = 'in-process'; readonly shared: TransportSet; + readonly #set: InProcessSet; readonly #handlers = new Map>(); readonly #onError: (error: unknown, subject: string) => void; #closed = false; constructor(options: InProcessTransportOptions = {}) { - this.shared = new InProcessSet(options.clock ?? systemClock); + this.#set = new InProcessSet(options.clock ?? systemClock); + this.shared = this.#set; this.#onError = options.onError ?? (() => undefined); } @@ -161,6 +184,11 @@ export class InProcessTransport implements Transport { return this.#handlers.size; } + /** Keys `shared` holds, emptied ones included: the in-process read a leak test needs. */ + get sharedKeys(): number { + return this.#set.size; + } + #assertOpen(): void { if (this.#closed) { throw new TransportUnavailableError({ transport: this.name, reason: 'transport is closed' }); diff --git a/packages/realtime/src/live-definition.test.ts b/packages/realtime/src/live-definition.test.ts index 1a06d1c2b..8b24cb999 100644 --- a/packages/realtime/src/live-definition.test.ts +++ b/packages/realtime/src/live-definition.test.ts @@ -219,6 +219,30 @@ describe('a declared live query is subscribable, per subscriber', () => { expect(allowed.frame.type).toBe('snapshot'); }); + test("a live policy's ctx.actor is the subscriber", async () => { + // Written against `ctx`, as an HTTP rule may be: there `ctx.actor` IS the caller. Handed the + // node's context it read the node's actor — anonymous here, a system actor on a real node. + const seen: string[] = []; + const byCtx: QueryPolicy = { + ...ownRowsOnly, + run: ({ ctx, row }) => { + seen.push(`${row === null ? 'subscribe' : 'row'}:${String(ctx?.actor.id)}`); + return ctx?.actor.id === 'alice' + ? { allowed: true } + : { allowed: false, reason: 'not alice', code: 'X_FORBIDDEN' }; + }, + }; + const registry = registryFor(byCtx); + const alice = socketFor('s-alice', userActor({ id: 'alice', orgId: 'o1' })); + const answer = await registry.subscribe({ + socket: alice.socket, + name: 'liveFeed', + input: INPUT, + }); + expect(answer.frame.type).toBe('snapshot'); + expect(new Set(seen)).toEqual(new Set(['subscribe:alice', 'row:alice'])); + }); + test('a patch reaches only the subscriber whose policy admits the row', async () => { const registry = registryFor(); const alice = socketFor('s-alice', userActor({ id: 'alice', orgId: 'o1' })); diff --git a/packages/realtime/src/policy-gate.ts b/packages/realtime/src/policy-gate.ts index 3d9bb9580..ef5f3c405 100644 --- a/packages/realtime/src/policy-gate.ts +++ b/packages/realtime/src/policy-gate.ts @@ -6,8 +6,9 @@ // policy is dropped, never sent. That is the rule from the live-query pipeline, implemented once. // A *denial* only — a gate that could not reach a decision raises, because "denied" and "the // database is down" are different facts and one of them has to page someone. +// Both gates decide in the SUBSCRIBER's context: `ctx.actor` is who asked, as it is over HTTP. -import type { Actor, Ctx } from '@ultimat3/core'; +import { type Actor, anonymousActor, type Ctx, ctxOf } from '@ultimat3/core'; import { guardQuery, QueryDeniedError, type QueryPolicy, type QuerySubject } from '@ultimat3/query'; import type { JsonValue, LiveRow } from './json'; @@ -60,5 +61,39 @@ function subjectOf( input: unknown, row: unknown, ): QuerySubject { - return { actor, input, row, ctx: options.ctx, query: options.query }; + // Anonymous is the anonymous actor, as over HTTP — never the node's own, which may be a system one. + const ctx = + actor === null ? subscriberContext(options.ctx, anonymousActor()) : ctxFor(options.ctx, actor); + return { actor, input, row, ctx, query: options.query }; +} + +/** + * Keyed by the actor OBJECT a socket holds — a re-auth puts a new one there — so no other actor + * can be answered from it; a row gate runs per subscriber per row, and `ctxOf` builds services. + */ +const contexts = new WeakMap>(); + +function ctxFor(node: Ctx, actor: Actor): Ctx { + let byActor = contexts.get(node); + if (byActor === undefined) { + byActor = new WeakMap(); + contexts.set(node, byActor); + } + const known = byActor.get(actor); + if (known !== undefined) return known; + const made = subscriberContext(node, actor); + byActor.set(actor, made); + return made; +} + +/** The node's context, re-made for one subscriber: same deploy, role and clock, their actor. */ +export function subscriberContext(node: Ctx, actor: Actor): Ctx { + return ctxOf({ + actor, + role: node.role, + buildId: node.buildId, + clock: node.clock, + locale: node.locale, + tz: node.tz, + }); } diff --git a/packages/realtime/src/presence.test.ts b/packages/realtime/src/presence.test.ts index d10fb0ac2..079bc8c89 100644 --- a/packages/realtime/src/presence.test.ts +++ b/packages/realtime/src/presence.test.ts @@ -42,6 +42,24 @@ describe('presence', () => { expect((await presence.list(room))[0]?.meta).toEqual({ x: 9 }); }); + test('a room whose members all expired leaves no key in the in-process set after it is forgotten', async () => { + const clock = frozenClock(0); + const transport = new InProcessTransport({ clock }); + const presence = new PresenceRegistry({ transport, clock, ttlMs: 30_000 }); + for (let i = 0; i < 3; i += 1) { + await presence.join(topic('org', 'o1', `room-${i}`), { id: `m${i}`, actorId: 'alice' }); + } + await presence.sweepAll(); + expect(transport.sharedKeys).toBeGreaterThan(0); + clock.advance(31_000); + // The pass that announces the leaves forgets each room. Its sweep lease outlives the room by + // one TTL — a follower reads the last roster off it — and is then gone with nobody reading it. + expect(await presence.sweepAll()).toHaveLength(3); + clock.advance(31_000); + await presence.join(topic('org', 'o1', 'next'), { id: 'm9', actorId: 'bob' }); + expect(transport.sharedKeys).toBe(1); + }); + test('a sweep turns silent expiry into explicit leave events', async () => { const { presence, tick } = harness(); await presence.join(room, { id: 'm1', actorId: 'alice' }); diff --git a/packages/realtime/src/socket-channel-drops.ts b/packages/realtime/src/socket-channel-drops.ts new file mode 100644 index 000000000..17eb7f2b5 --- /dev/null +++ b/packages/realtime/src/socket-channel-drops.ts @@ -0,0 +1,21 @@ +// The node-wide series for channel frames socket backpressure refused. Split from `socket.ts`, which +// counts the drops at the one place they happen; this is only the series' declaration. + +import { type Counter, counter } from '@ultimat3/core'; + +/** + * Channel frames this process dropped under backpressure. A dropped `records` frame is now marked + * and REPAIRED — the socket is sent `replay-gap` once it drains and re-reads the channel's catch-up + * query (`channel_replay_gaps_total` counts those) — while a dropped `events` frame is ephemeral + * by definition and is only counted. The two series side by side are the whole delivery story. + * + * Declared here rather than in `@ultimat3/core`'s `runtime-metrics.ts` because that file is the + * series EVERY Ultimate process emits and the deploy chart scales on; this one exists only where + * channels do. **No attributes**: a topic is client-chosen (`topic()` admits any + * `[A-Za-z0-9_-]+` segment), so a per-topic label is an unbounded series count one socket can mint + * — the topic goes in the log line, where cardinality is somebody else's index. + */ +export const channelFramesDropped: Counter = counter('channel_frames_dropped_total', { + unit: '{frame}', + description: 'Channel frames dropped by socket backpressure', +}); diff --git a/packages/realtime/src/socket.ts b/packages/realtime/src/socket.ts index fc69f31ef..a49968d48 100644 --- a/packages/realtime/src/socket.ts +++ b/packages/realtime/src/socket.ts @@ -10,8 +10,6 @@ import { type Actor, type Clock, - type Counter, - counter, finiteOption, logger, recordConnection, @@ -19,8 +17,10 @@ import { uuidV7, } from '@ultimat3/core'; import { GapRepairs } from './channel-gaps'; +import type { Audience, DeliverRecordsTo } from './channel-tenant'; import type { ChannelRecordsFrame } from './channel-wire'; import { CLOSE } from './close-codes'; +import { channelFramesDropped } from './socket-channel-drops'; import { DropWindow } from './socket-drops'; import { DEFAULT_IDLE_TIMEOUT_MS } from './socket-idle'; import { encode, type Frame } from './sync-protocol'; @@ -80,21 +80,10 @@ import { } from './socket-defaults'; /** - * Channel frames this process dropped under backpressure. A dropped `records` frame is now marked - * and REPAIRED — the socket is sent `replay-gap` once it drains and re-reads the channel's catch-up - * query (`channel_replay_gaps_total` counts those) — while a dropped `events` frame is ephemeral - * by definition and is only counted. The two series side by side are the whole delivery story. - * - * Declared here rather than in `@ultimat3/core`'s `runtime-metrics.ts` because that file is the - * series EVERY Ultimate process emits and the deploy chart scales on; this one exists only where - * channels do. **No attributes**: a topic is client-chosen (`topic()` admits any - * `[A-Za-z0-9_-]+` segment), so a per-topic label is an unbounded series count one socket can mint - * — the topic goes in the log line, where cardinality is somebody else's index. + * `deliverRecords` to an `Audience`. A function rather than a parameter: `SocketRegistry` is public + * API, and a changed member signature is a break (`scripts/public-api.ts`). Set by the class below. */ -const channelFramesDropped: Counter = counter('channel_frames_dropped_total', { - unit: '{frame}', - description: 'Channel frames dropped by socket backpressure', -}); +export let deliverRecordsTo: DeliverRecordsTo; export function actorIdOf(actor: Actor | null): string | null { return actor === null ? null : actor.id; @@ -431,9 +420,20 @@ export class SocketRegistry { * marked for the next one. `deliver`'s twin, because only a records stream can be repaired. */ deliverRecords(topic: string, epoch: string, frame: ChannelRecordsFrame): number { + return this.#records(topic, epoch, frame, undefined); + } + + static { + deliverRecordsTo = (registry, topic, epoch, frame, to) => + registry.#records(topic, epoch, frame, to); + } + + /** A member `to` does not admit is sent `to.withheld` instead (`channel-tenant.ts`). */ + #records(topic: string, epoch: string, frame: ChannelRecordsFrame, to?: Audience): number { const members = this.#byTopic.get(topic); if (!members) return 0; const text = encode(frame); + const other = to === undefined ? text : encode(to.withheld); let sent = 0; let dropped = 0; for (const socket of members) { @@ -442,7 +442,7 @@ export class SocketRegistry { continue; } this.gapRepairs.repair(socket, topic); - if (socket.sendEncoded(text)) { + if (socket.sendEncoded(to === undefined || to.admits(socket.actor) ? text : other)) { sent += 1; continue; } diff --git a/packages/render/CLAUDE.md b/packages/render/CLAUDE.md index 13b2b751e..883404bb8 100644 --- a/packages/render/CLAUDE.md +++ b/packages/render/CLAUDE.md @@ -61,9 +61,9 @@ axiom 6). Never `cli` (upward). | A byte count in a message | `formatBytes` from `@ultimat3/core`, never a local one. | | Island bytes | **not this package's**: `@ultimat3/cli`'s `packages/cli/src/budgets.ts` measures the EMITTED document and is the gate. What stays here is the budget grammar (`parseByteBudget`) and `defaultIslandBudget`. | | The hydration runtime's CSP | `HYDRATE_RUNTIME_BODIES` — every inline body `hydrateRuntime` can emit, hashed by `@ultimat3/cli`'s `script-csp.ts`; `runtimeBody` is the one string served and hashed † | -| Island markup | the props `', ''); + await writeFile(runtime, source, 'utf8'); + await import(Bun.pathToFileURL(runtime).href); + for (let i = 0; i < 1_000 && wrappers.some((el) => el.__x === undefined); i += 1) { + await new Promise((resolve) => { + setTimeout(resolve, 1); + }); + } + await Promise.all(wrappers.map((el) => el.__x)); + return wrappers.map((el) => got.get(el)); + } finally { + globals['document'] = undefined; + globals['window'] = undefined; + globals['__xTestMount'] = undefined; + await rm(dir, { recursive: true, force: true }); + } + } + + const wrapper = (entry: string, id: string, own: PropsScript | null): Wrapper => { + const attributes = new Map([ + ['data-x-entry', entry], + ['data-x-island', id], + ]); + return { + getAttribute: (name) => attributes.get(name) ?? null, + setAttribute: (name, value) => { + attributes.set(name, value); + }, + querySelector: (selector) => (selector === ':scope>script[data-x-props]' ? own : null), + addEventListener: () => undefined, + removeEventListener: () => undefined, + }; + }; + + const script = (props: object, inside: object | null): PropsScript => ({ + textContent: JSON.stringify(props), + closest: (selector) => (selector === '[data-x-island]' ? inside : null), + }); + + test('two wrappers with one island id each boot with the props script inside themselves', async () => { + const props = await bootWith((entry) => { + const pageScript = script({ post: 'page' }, {}); + const modalScript = script({ post: 'modal' }, {}); + return { + wrappers: [wrapper(entry, 'like-1', pageScript), wrapper(entry, 'like-1', modalScript)], + documentScripts: [ + { id: 'like-1', script: pageScript }, + { id: 'like-1', script: modalScript }, + ], + }; + }); + + expect(props).toEqual([{ post: 'page' }, { post: 'modal' }]); + }); + + test('a wrapper carrying no props script never takes the one inside another wrapper', async () => { + const props = await bootWith((entry) => { + const pageScript = script({ post: 'page' }, {}); + return { + wrappers: [wrapper(entry, 'like-1', pageScript), wrapper(entry, 'like-1', null)], + documentScripts: [{ id: 'like-1', script: pageScript }], + }; + }); + + expect(props).toEqual([{ post: 'page' }, {}]); + }); + + // A hand-assembled document (`emitIslandProps` is public) may put the script beside the wrapper. + test('a props script loose in the document still reaches the wrapper that has none', async () => { + const props = await bootWith((entry) => ({ + wrappers: [wrapper(entry, 'settings', null)], + documentScripts: [{ id: 'settings', script: script({ tab: 'profile' }, null) }], + })); + + expect(props).toEqual([{ tab: 'profile' }]); + }); +}); diff --git a/packages/render/src/hydrate.ts b/packages/render/src/hydrate.ts index b4747fb37..735405c1c 100644 --- a/packages/render/src/hydrate.ts +++ b/packages/render/src/hydrate.ts @@ -126,13 +126,20 @@ export function requiredStrategies( // runtime below would then flush its replay queue into an island that never mounted — the bug // `el.__x`-as-a-promise was introduced to fix, reintroduced one layer further out. // +// The props are the script INSIDE this wrapper (`render-walk.ts` emits it as a child), never the +// first one in the document carrying the id: an id is `-` per RENDER, so the +// page under a modal and the modal's document both hold `like-1`, and so does an island carried +// across a swap (`data-x-persist`). A script loose in the document — a hand-assembled page — +// is still read by id, and one that sits in another island's wrapper is that island's. +// // `el.__x` resolves to whatever `mount()` returned. An island's `mount` may return `() => void`, // its disposer (Solid's `render` answers one); the runtime keeps it there and // `@ultimat3/testing`'s `mountIsland` calls it on dispose. Nothing here ever calls it. const RUNTIME_PRELUDE = ` function boot(el){var e=el.getAttribute('data-x-entry'); if(!e)return Promise.resolve();if(el.__x)return el.__x; -var p=document.querySelector('script[data-x-props="'+el.getAttribute('data-x-island')+'"]'); +var p=el.querySelector(':scope>script[data-x-props]'); +if(!p){p=document.querySelector('script[data-x-props="'+el.getAttribute('data-x-island')+'"]');if(p&&p.closest('[data-x-island]'))p=null} var props=p?JSON.parse(p.textContent||'{}'):{}; return el.__x=import(e).then(function(m){return m.mount(el,props)}).then( function(r){el.setAttribute('${ISLAND_MOUNTED_ATTRIBUTE}','');return r}, diff --git a/packages/render/src/island-budget.test.ts b/packages/render/src/island-budget.test.ts index e81a455dc..14b7676db 100644 --- a/packages/render/src/island-budget.test.ts +++ b/packages/render/src/island-budget.test.ts @@ -40,8 +40,11 @@ describe('DEFAULT_ISLAND_JS_BYTES', () => { * 1,784 -> 1,843 on 2026-10-05 (+59 B in the shared `catchUp`): a capture listener lets go on * the first event after a mount something else made — a held island (`island-hold.ts`) is * booted by the hold, so its first click after the reveal was replayed into it, running twice. + * 1,843 -> 1,943 on 2026-11-19 (+100 B in the shared prelude, every strategy): `boot` reads the + * props script inside its own wrapper, and one by id only when it sits in no other island's — a + * modal's island otherwise booted with the props of the page under it, the same id per render. */ - hydrateRuntimeIdle: 1_843, + hydrateRuntimeIdle: 1_943, /** * `DEFAULT_ISLAND_HYDRATE` is `'interaction'` (`route.ts:33`), so THIS is the runtime an island * route declaring no `hydrate` actually ships. The budget derivation used `idle` and understated @@ -69,8 +72,10 @@ describe('DEFAULT_ISLAND_JS_BYTES', () => { * * Moved 1,669 -> 1,728 on 2026-10-05: `catchUp`'s `on` detaches once the island is mounted * (+59 B, the same bytes as `idle`'s) — the held-island double run, above. + * + * Moved 1,728 -> 1,828 on 2026-11-19: the prelude's wrapper-first props lookup (+100 B), above. */ - hydrateRuntimeDefault: 1_728, + hydrateRuntimeDefault: 1_828, } as const; /** What the allowance has to clear: the costlier of the two runtimes an island gets unasked. */ diff --git a/packages/render/src/island-hold-replay.test.ts b/packages/render/src/island-hold-replay.test.ts index ebf081a53..7d73958d9 100644 --- a/packages/render/src/island-hold-replay.test.ts +++ b/packages/render/src/island-hold-replay.test.ts @@ -107,6 +107,7 @@ async function held(strategy: Exclude): Promise node === el, children: [], + querySelector: (): unknown => null, addEventListener: (name: string, fn: (event: FakeEvent) => void): void => { listeners.set(name, [...(listeners.get(name) ?? []), fn]); }, diff --git a/packages/render/src/island-hold.test.ts b/packages/render/src/island-hold.test.ts index 6b2958c42..ccf3ecacf 100644 --- a/packages/render/src/island-hold.test.ts +++ b/packages/render/src/island-hold.test.ts @@ -150,6 +150,7 @@ describe('held islands, executed', () => { styles.delete(name); }, }, + querySelector: (): unknown => null, addEventListener: (): void => undefined, removeEventListener: (): void => undefined, } as Held; diff --git a/packages/render/src/modes.ts b/packages/render/src/modes.ts index ec9013dff..f9af5ec4d 100644 --- a/packages/render/src/modes.ts +++ b/packages/render/src/modes.ts @@ -244,7 +244,7 @@ export function defaultHydrate(surface: Surface): HydrateStrategy { * runtimes an island gets unasked; `DEFAULT_ISLAND_HYDRATE`'s `'interaction'` is 1,669) = * **19,581**. That is the worst case an app reaches without writing a number down. 20,480 is the * next whole kilobyte above it, leaving 899 B of headroom and still under 2x 19,581, so a route - * bundling the same island twice is refused. `island-budget.test.ts` asserts all three. `visible` costs 886, so an island route + * bundling the same island twice is refused. `island-budget.test.ts` asserts all three. `visible` costs 986, so an island route * that declares it pays less; the default is what the budget has to clear. * * All three grew by 129 B on 2026-08-21 (from 881 / 615 / 687), when the prelude learned to mark a @@ -257,7 +257,9 @@ export function defaultHydrate(surface: Surface): HydrateStrategy { * shared `catchUp`, and both learned to aim a keyboard press by the pressed node's path (774 -> 1,744; * `interaction` 1,251 -> 1,629), and `idle` became the worst case. The * headroom absorbed all four and the conclusion is unchanged, which is the point of stating the - * arithmetic here rather than the answer alone. It is not + * arithmetic here rather than the answer alone. As of 2026-11-19 `idle` is 1,943 (+59 B on + * 2026-10-05, a held island's listeners; +100 B in the shared prelude, `boot` reading the props + * script inside its own wrapper): 17,797 + 1,943 = 19,740, 740 B under the default. It is not * derived from Solid's own size on purpose — this package may not import or name `solid-js` * (`CLAUDE.md`), so a constant tracking the runtime's version would be a dependency in a comment. * diff --git a/packages/render/src/render-html.test.ts b/packages/render/src/render-html.test.ts index 6408f2efe..ebe26eee4 100644 --- a/packages/render/src/render-html.test.ts +++ b/packages/render/src/render-html.test.ts @@ -17,6 +17,38 @@ describe('renderToHtml', () => { expect(await renderToHtml(h('p', null, ' { + expect(await renderToHtml(h('style', null, 'a > b::after { content: "&" }'))).toBe( + '', + ); + expect(await renderToHtml(h('script', null, 'if (a && b > 1) x(" diff --git a/docs/architecture/guards.md b/docs/architecture/guards.md index d7b753f25..025cce123 100644 --- a/docs/architecture/guards.md +++ b/docs/architecture/guards.md @@ -93,7 +93,7 @@ The codes are in | `bun run scripts/pack-cli-wiki.ts` | `@ultimat3/cli`'s `prepack` and `postpack`: the wiki pages `x docs` answers from, copied into the CLI package's own `wiki/` directory for the tarball and removed after it. | `X_PACKAGE_SHAPE` | | `bun run scripts/package-front.ts` | Enforce, on `x verify`'s `manifest` step, the npm page of every publishable package: its README's first screen holds one sentence, an install line, the smallest example and the package's wiki page (its `homepage`), and its `package.json` carries `keywords`. | `X_PACKAGE_KEYWORDS_MISSING` `X_PACKAGE_README_SHAPE` | | `bun run package-map-graph` | Enforce, as a gate rule, that the dependency graph `docs/architecture/01-package-map.md` DRAWS is the dependency graph the manifests declare: every arrow is a dependency the `from` package's own `package.json` holds, and every publishable workspace is a node on it. | `X_DOC_PACKAGE_GRAPH_STALE` `X_DOC_PACKAGE_GRAPH_UNSCANNED` | -| `bun run pin-raises` | A ratchet pin that goes UP needs its reason in the same diff — `budget-raises`' rule, applied to every `scripts/lib/*-pins.ts` table and to the ratchets kept inside scripts (`PIN_FILES`). | `X_PIN_BASE_MISSING` `X_PIN_EDIT_UNPLACED` `X_PIN_RAISE_UNSTATED` | +| `bun run pin-raises` | A ratchet pin that goes UP needs its reason in the same diff — `budget-raises`' rule, applied to every `scripts/lib/*-pins.ts` table, to the ratchets kept inside scripts (`PIN_FILES`) and to the byte ceilings pinned inside bundle and `*-bytes` tests (`lib/test-byte-ceilings.ts`). | `X_PIN_BASE_MISSING` `X_PIN_EDIT_UNPLACED` `X_PIN_RAISE_UNSTATED` | | `bun run plan-status` | Enforce that every `docs/plans/**/status.yml` parses, and that its top-level `status` and each slice's `status` is one of the plan template's values. | `X_PLAN_STATUS_INVALID` `X_PLAN_STATUS_UNSCANNED` | | `bun run scripts/port-probe.ts` | Enforce, as a ratchet, that a test never takes a port by probing it: bind port 0, read the port, release it, hand the number on. | `X_CORPUS_UNSCANNED` `X_TEST_PORT_PROBED` `X_TEST_PORT_PROBE_PIN_STALE` | | `bun run posix-relative` | Enforce that a host `relative()` answer is written POSIX through `toPosix` before it is used. | `X_RELATIVE_PATH_NOT_POSIX` | diff --git a/packages/action/src/errors.test.ts b/packages/action/src/errors.test.ts index e85074243..7a35ea4db 100644 --- a/packages/action/src/errors.test.ts +++ b/packages/action/src/errors.test.ts @@ -6,6 +6,7 @@ import { describe, expect, test } from 'bun:test'; import { describeErrorCode, ERROR_DOCS_URL, statedDelayMs } from '@ultimat3/core'; import { + ActionDeniedError, ActionDuplicateError, ActionPolicyMissingError, ActionUnregisteredError, @@ -117,3 +118,28 @@ describe('unit · RemoteActionError states a delay only from the header', () => expect(error.retry).toBe('retry-after'); }); }); + +// A predicate that reads the request input is never decided without one: `x policy explain` +// answers `needs input` and evaluates on `--input`. The fix pastes that flag as a PLACEHOLDER — +// a fix line is logged and returned to callers, so the real input never rides in it. +describe('unit · X_FORBIDDEN names --input as a placeholder', () => { + test('the fix carries the --input form and no request value', () => { + const error = new ActionDeniedError({ + kind: 'action', + name: 'publishPost', + surface: 'job', + code: 'X_FORBIDDEN', + reason: 'not the author', + denial: { + surface: 'job', + outcome: 'failed', + retryable: false, + code: 'X_FORBIDDEN', + reason: 'not the author', + }, + }); + expect(error.fix).toStartWith( + "x policy explain publishPost --input '' --json", + ); + }); +}); diff --git a/packages/action/src/errors.ts b/packages/action/src/errors.ts index c498b9d05..ab0fd0812 100644 --- a/packages/action/src/errors.ts +++ b/packages/action/src/errors.ts @@ -81,7 +81,7 @@ export class ActionDeniedError extends UltimateError { super({ code: refused.code, cause: `${refused.name} denied: ${refused.reason}`, - fix: `x policy explain ${renderFixShellArg(refused.name, '')} --json # shows which clause decided and why`, + fix: `x policy explain ${renderFixShellArg(refused.name, '')} --input '' --json # shows which clause decided and why; --input decides a predicate that reads the request`, callerFix: deniedCallerFix(), }); this.denial = refused.denial; diff --git a/packages/admin/src/dev/facts.ts b/packages/admin/src/dev/facts.ts index 715cd65e0..92977b5da 100644 --- a/packages/admin/src/dev/facts.ts +++ b/packages/admin/src/dev/facts.ts @@ -264,8 +264,14 @@ export interface InvalidationFact { export interface PolicyFact { readonly permission: string; readonly actorId: string; + /** `false` for a `needs-input` cell too: nothing allowed it, though nothing denied it either. */ readonly allowed: boolean; readonly trace: readonly string[]; + /** + * `needs-input`: a predicate read the request input the panel has none of, so the cell is not + * decided. Absent from a source that predates it, which then reads as `allowed` says. + */ + readonly verdict?: 'allow' | 'deny' | 'needs-input'; } export interface ManifestFact { diff --git a/packages/admin/src/dev/panel-policy.test.ts b/packages/admin/src/dev/panel-policy.test.ts index 477f28533..669b9b0ea 100644 --- a/packages/admin/src/dev/panel-policy.test.ts +++ b/packages/admin/src/dev/panel-policy.test.ts @@ -68,6 +68,23 @@ describe('unreachable permissions', () => { expect(panel.unreachable).toEqual(['post:purge']); }); + // A cell whose predicate read the request input it was not given is UNDECIDED, not a deny: + // calling its permission unreachable sent the reader to fix a correct, input-scoped rule. + test('a permission undecided for want of request input is pending, never unreachable', async () => { + const panel = await policyPanel.data( + staticDevSources({ + policyMatrix: () => + Promise.resolve([ + fact({ permission: 'post:edit', actorId: 'admin', verdict: 'needs-input' }), + fact({ permission: 'post:edit', actorId: 'anonymous', verdict: 'deny' }), + ]), + }), + new URLSearchParams(), + ); + expect(panel.unreachable).toEqual([]); + expect(panel.needsInput).toEqual(['post:edit']); + }); + test('an empty matrix has no unreachable rows to report', async () => { const panel = await policyPanel.data(staticDevSources(), new URLSearchParams()); expect(panel.actors).toEqual([]); diff --git a/packages/admin/src/dev/panel-policy.ts b/packages/admin/src/dev/panel-policy.ts index 607f1aafa..b9f4a79c0 100644 --- a/packages/admin/src/dev/panel-policy.ts +++ b/packages/admin/src/dev/panel-policy.ts @@ -20,6 +20,11 @@ export interface PolicyPanelData { readonly trace: readonly string[]; /** Permissions no actor holds — usually a policy nobody can satisfy. */ readonly unreachable: readonly string[]; + /** + * Permissions with a cell no request decided: a predicate there reads the request input. + * Optional only so a value built against 31.48.0's shape still type-checks; this panel sets it. + */ + readonly needsInput?: readonly string[]; } export const policyPanel: DevPanel = { @@ -52,6 +57,10 @@ export const policyPanel: DevPanel = { (fact) => fact.permission === wantedPermission && fact.actorId === wantedActor, ); + const needsInput = permissions.filter((permission) => + facts.some((fact) => fact.permission === permission && fact.verdict === 'needs-input'), + ); + return { actors, permissions, @@ -60,7 +69,9 @@ export const policyPanel: DevPanel = { trace: selected?.trace ?? [], unreachable: matrix .filter((row) => Object.values(row.byActor).every((allowed) => !allowed)) - .map((row) => row.permission), + .map((row) => row.permission) + .filter((permission) => !needsInput.includes(permission)), + needsInput, }; }, }; diff --git a/packages/cli/src/cmd-policy.ts b/packages/cli/src/cmd-policy.ts index 67d21708a..32e17d41b 100644 --- a/packages/cli/src/cmd-policy.ts +++ b/packages/cli/src/cmd-policy.ts @@ -10,8 +10,9 @@ import type { CliCommand, CommandContext } from './command'; import { BadFlagError, DeclarationUnknownError, MissingPositionalError } from './errors'; import { msg } from './messages'; import type { CommandResult, Finding, JsonValue } from './output'; -import type { DeclarationExplanation, ExplainOptions, ExplainVerdict } from './policy-facts'; +import type { DeclarationExplanation, ExplainOptions } from './policy-facts'; import { explainPolicy, knownPolicySubjects, listPolicy } from './policy-facts'; +import type { ExplainVerdict } from './policy-row'; import { quoteArg } from './shell-quote'; import { renderTable } from './table'; diff --git a/packages/cli/src/db-migrate-through-dev.ts b/packages/cli/src/db-migrate-through-dev.ts index a50789a07..b5160f74b 100644 --- a/packages/cli/src/db-migrate-through-dev.ts +++ b/packages/cli/src/db-migrate-through-dev.ts @@ -2,7 +2,7 @@ // that holds `.x/pgdata` (`dev-db-migrate.ts`'s POST), never applied by a second opener. A holder // that cannot answer is `X_DEV_ALREADY_RUNNING`, its fix the stop, migrate, start that does work. -import { renderThrowable, UltimateError } from '@ultimat3/core'; +import { renderThrowable, stringField, UltimateError } from '@ultimat3/core'; import { t } from '@ultimat3/schema'; import type { DevMigrateData } from './dev-db-migrate'; import { DevAlreadyRunningError, type DevLock } from './dev-lock'; @@ -96,11 +96,10 @@ const waitFor = (stateDir: string): DevWait => ({ * pass twice. Anything else (a socket closed mid-answer, a timeout) may have reached the holder, * and a rollback asked twice reverses two migrations. */ -const neverSent = (error: unknown): boolean => - typeof error === 'object' && - error !== null && - 'code' in error && - (error.code === 'ECONNREFUSED' || error.code === 'ConnectionRefused'); +const neverSent = (error: unknown): boolean => { + const code = stringField(error, 'code'); + return code === 'ECONNREFUSED' || code === 'ConnectionRefused'; +}; /** * Asked of the holder, and answered by it. Its own refusal (a failed migration, a forked ledger) diff --git a/packages/cli/src/dev-lock-errors.ts b/packages/cli/src/dev-lock-errors.ts new file mode 100644 index 000000000..796e92fb6 --- /dev/null +++ b/packages/cli/src/dev-lock-errors.ts @@ -0,0 +1,78 @@ +// The three refusals `x dev`'s lock claim raises that are NOT another `x dev`: an unreadable lock, +// a state directory that refuses the claim, and a port a stranger holds. Split from `dev-lock.ts`, +// which keeps the claim itself and `X_DEV_ALREADY_RUNNING`. + +import { stringField, UltimateError } from '@ultimat3/core'; +import { ownerText, type PortOwner } from './dev-lock-holder-dir'; +import { quoteArg } from './shell-quote'; + +/** + * The lock file exists, this process could not read it and could not remove it — which is not + * "another x dev is running", and was reported as exactly that. + * + * `DevAlreadyRunningError` needs a `DevLock`, and the only one in hand on that path was `mine`: + * the refusal then read `pid is already running x dev` with `fix: … kill `, a remedy that kills the reader and a cause naming the wrong holder. Axiom 4 wants a + * runnable fix and an honest cause, so the honest answer is its own code — the file is the + * problem, and removing it is what a reader can actually do. + */ +export class DevLockUnreadableError extends UltimateError { + constructor(input: { readonly path: string; readonly stateDir: string }) { + super({ + code: 'X_DEV_LOCK_UNREADABLE', + cause: `${input.path} could not be parsed as a dev lock and could not be removed, so x dev cannot tell whether another process owns ${input.stateDir}`, + fix: `rm ${quoteArg(input.path)} # then re-run x dev`, + meta: { path: input.path, stateDir: input.stateDir }, + }); + } +} + +/** + * The state directory refused the claim itself: it could not be created, the lock could not be + * staged in it, or the filesystem would not hard-link the staged file into place. None of that is + * another `x dev` — only `EEXIST` is — and escaping raw it reached the operator as + * `X_CLI_UNEXPECTED` with `fix: x doctor --json`, which says nothing about `.x/`. + */ +export class DevStateUnwritableError extends UltimateError { + constructor(input: { readonly stateDir: string; readonly error: unknown }) { + // Read the field, never cast and dereference: `unknown` is what a catch hands over. + const errno = stringField(input.error, 'code') ?? 'an unreported errno'; + super({ + code: 'X_DEV_STATE_UNWRITABLE', + cause: `${input.stateDir} could not be created, written, or hard-linked into (${errno}), so x dev cannot take its lock — a read-only checkout, a .x/ this user may not write, or a filesystem without hard links`, + fix: `ls -ld ${quoteArg(input.stateDir)} # make it writable by this user, on a filesystem that supports hard links, then re-run x dev`, + meta: { stateDir: input.stateDir, errno }, + sourceError: input.error, + }); + } +} + +/** + * The port is bound by something that is not us. Named separately from the lock case because the + * remedy is different: a stranger's port is worked around with `--port`, while a second `x dev` on + * this checkout is not a port problem at all and moving it would still fail on the database. + * + * The holder is NAMED when the OS will say. On a developer machine :3000 is usually another + * project's dev server, and "pid 41234, bun" is the difference between knowing that and guessing — + * which decides whether the right move is `--port` or stopping the other thing. Both are offered, + * `--port` first: moving your own server is always safe, and killing someone else's is not. + */ +export class DevPortInUseError extends UltimateError { + constructor(input: { + readonly port: number; + readonly suggestion: number; + readonly holder?: PortOwner; + }) { + const holder = input.holder ?? {}; + const named = ownerText(holder) ?? 'another process'; + super({ + code: 'X_PORT_IN_USE', + cause: `:${input.port} is already bound by ${named}, so the web role cannot listen — on a machine running several projects this is usually another one's dev server, not a stale copy of this one`, + fix: + holder.pid === undefined + ? `x dev --port ${quoteArg(String(input.suggestion))}` + : `x dev --port ${quoteArg(String(input.suggestion))} # or free it, if that pid is yours: kill ${holder.pid}`, + meta: { port: input.port, ...holder }, + }); + } +} diff --git a/packages/cli/src/dev-lock.test.ts b/packages/cli/src/dev-lock.test.ts index 0cb8803b4..f643e2fb7 100644 --- a/packages/cli/src/dev-lock.test.ts +++ b/packages/cli/src/dev-lock.test.ts @@ -14,14 +14,13 @@ import { clearLock, DEV_LOCK_FILE, DevAlreadyRunningError, - DevLockUnreadableError, - DevPortInUseError, isProcessAlive, lockPath, parseLock, preflight, writeLock, } from './dev-lock'; +import { DevLockUnreadableError, DevPortInUseError } from './dev-lock-errors'; const scratch = (): string => mkdtempSync(join(tmpdir(), 'ultimate-dev-lock-')); diff --git a/packages/cli/src/dev-lock.ts b/packages/cli/src/dev-lock.ts index cfc2cd50e..efbae977a 100644 --- a/packages/cli/src/dev-lock.ts +++ b/packages/cli/src/dev-lock.ts @@ -20,7 +20,12 @@ import { linkSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'; import { join } from 'node:path'; import { stringField, UltimateError } from '@ultimat3/core'; -import { ownerText, type PortOwner, portOwner } from './dev-lock-holder-dir'; +import { + DevLockUnreadableError, + DevPortInUseError, + DevStateUnwritableError, +} from './dev-lock-errors'; +import { type PortOwner, portOwner } from './dev-lock-holder-dir'; import { reusedPid, startedOf } from './dev-lock-identity'; import type { PortHolder } from './dev-lock-port-holder'; import { stealStale } from './dev-lock-steal'; @@ -148,77 +153,6 @@ export class DevAlreadyRunningError extends UltimateError { } } -/** - * The lock file exists, this process could not read it and could not remove it — which is not - * "another x dev is running", and was reported as exactly that. - * - * `DevAlreadyRunningError` needs a `DevLock`, and the only one in hand on that path was `mine`: - * the refusal then read `pid is already running x dev` with `fix: … kill `, a remedy that kills the reader and a cause naming the wrong holder. Axiom 4 wants a - * runnable fix and an honest cause, so the honest answer is its own code — the file is the - * problem, and removing it is what a reader can actually do. - */ -export class DevLockUnreadableError extends UltimateError { - constructor(input: { readonly path: string; readonly stateDir: string }) { - super({ - code: 'X_DEV_LOCK_UNREADABLE', - cause: `${input.path} could not be parsed as a dev lock and could not be removed, so x dev cannot tell whether another process owns ${input.stateDir}`, - fix: `rm ${quoteArg(input.path)} # then re-run x dev`, - meta: { path: input.path, stateDir: input.stateDir }, - }); - } -} - -/** - * The state directory refused the claim itself: it could not be created, the lock could not be - * staged in it, or the filesystem would not hard-link the staged file into place. None of that is - * another `x dev` — only `EEXIST` is — and escaping raw it reached the operator as - * `X_CLI_UNEXPECTED` with `fix: x doctor --json`, which says nothing about `.x/`. - */ -export class DevStateUnwritableError extends UltimateError { - constructor(input: { readonly stateDir: string; readonly error: unknown }) { - // Read the field, never cast and dereference: `unknown` is what a catch hands over. - const errno = stringField(input.error, 'code') ?? 'an unreported errno'; - super({ - code: 'X_DEV_STATE_UNWRITABLE', - cause: `${input.stateDir} could not be created, written, or hard-linked into (${errno}), so x dev cannot take its lock — a read-only checkout, a .x/ this user may not write, or a filesystem without hard links`, - fix: `ls -ld ${quoteArg(input.stateDir)} # make it writable by this user, on a filesystem that supports hard links, then re-run x dev`, - meta: { stateDir: input.stateDir, errno }, - sourceError: input.error, - }); - } -} - -/** - * The port is bound by something that is not us. Named separately from the lock case because the - * remedy is different: a stranger's port is worked around with `--port`, while a second `x dev` on - * this checkout is not a port problem at all and moving it would still fail on the database. - * - * The holder is NAMED when the OS will say. On a developer machine :3000 is usually another - * project's dev server, and "pid 41234, bun" is the difference between knowing that and guessing — - * which decides whether the right move is `--port` or stopping the other thing. Both are offered, - * `--port` first: moving your own server is always safe, and killing someone else's is not. - */ -export class DevPortInUseError extends UltimateError { - constructor(input: { - readonly port: number; - readonly suggestion: number; - readonly holder?: PortOwner; - }) { - const holder = input.holder ?? {}; - const named = ownerText(holder) ?? 'another process'; - super({ - code: 'X_PORT_IN_USE', - cause: `:${input.port} is already bound by ${named}, so the web role cannot listen — on a machine running several projects this is usually another one's dev server, not a stale copy of this one`, - fix: - holder.pid === undefined - ? `x dev --port ${quoteArg(String(input.suggestion))}` - : `x dev --port ${quoteArg(String(input.suggestion))} # or free it, if that pid is yours: kill ${holder.pid}`, - meta: { port: input.port, ...holder }, - }); - } -} - /** * Is anything listening? A successful bind-then-close is the only answer that does not lie. * diff --git a/packages/cli/src/dev-policy.test.ts b/packages/cli/src/dev-policy.test.ts index 9fd2dbe90..69f20c3b0 100644 --- a/packages/cli/src/dev-policy.test.ts +++ b/packages/cli/src/dev-policy.test.ts @@ -157,6 +157,35 @@ describe('unit · the /_x policy matrix', () => { expect(cell(facts, 'post:publish', 'anonymous')).toBe(false); }); + // The same false deny `x policy explain` used to print: an input-scoped rule (every one + // `x g resource` writes) read "deny" for the admin who succeeds over HTTP. With no request + // there is nothing to decide it on, so the cell says so — and the panel never calls it + // unreachable. + test('a predicate that reads the request input is needs-input, never a deny', () => { + definePermissions(['post:edit'] as const); + defineRoles({ admin: { grants: ['post:edit'] } }); + registerActions({ + editPost: action({ + input: t.object({ authorId: t.string }), + output: t.object({}), + policy: can<{ authorId: string }>('post:edit', ({ input }) => input.authorId === 'me'), + async handle() { + return {}; + }, + }), + }); + const admin = devPolicyMatrix().find( + (fact) => fact.permission === 'post:edit' && fact.actorId === 'admin', + ); + expect(admin?.verdict).toBe('needs-input'); + expect(admin?.trace[0]).toContain('needs input'); + expect(admin?.trace[0]).not.toContain('deny'); + const anonymous = devPolicyMatrix().find( + (fact) => fact.permission === 'post:edit' && fact.actorId === 'anonymous', + ); + expect(anonymous?.verdict).toBe('deny'); + }); + test('an app with no registered primitives answers an empty matrix, not a throw', () => { expect(devPolicyMatrix()).toEqual([]); }); diff --git a/packages/cli/src/dev-policy.ts b/packages/cli/src/dev-policy.ts index 169223fd9..66af314b3 100644 --- a/packages/cli/src/dev-policy.ts +++ b/packages/cli/src/dev-policy.ts @@ -6,8 +6,9 @@ import { listActions } from '@ultimat3/action'; import type { PolicyFact } from '@ultimat3/admin/dev'; import type { NamedActor, Policy } from '@ultimat3/policy'; -import { policyMatrix, roleDefinitions, testActor } from '@ultimat3/policy'; +import { roleDefinitions, testActor } from '@ultimat3/policy'; import { listQueries } from '@ultimat3/query'; +import { rowWithoutInput } from './policy-row'; /** * One capability and the policy that decides it. A primitive's `capability` IS its policy's own @@ -56,21 +57,23 @@ export function devPolicyGates(): readonly PolicyGate[] { /** * The matrix, actor by actor and capability by capability. * - * Evaluated with no row on purpose: `/_x` asks whether an actor may reach a capability at all, and - * there is no row to hand a row-level rule outside a real request. A rule that needs one therefore - * shows its no-row verdict, and the trace says so rather than letting the cell read as a flat deny. + * Evaluated with no row and no input on purpose: `/_x` asks whether an actor may reach a + * capability at all, and outside a real request there is neither. A row-level rule shows its + * no-row verdict and the trace says so; a predicate that reads the input is `needs input` — the + * row `x policy explain` draws (`policy-row.ts`), never the deny `input: {}` used to produce. */ export function devPolicyMatrix(): readonly PolicyFact[] { const actors = devActors(); return devPolicyGates().flatMap((gate) => { - const matrix = policyMatrix(gate.policy, { actors, input: {} }); - return matrix.rows.map( + const rows = actors.map((actor) => rowWithoutInput(gate.policy, actor)); + return rows.map( (row): PolicyFact => ({ permission: gate.permission, actorId: row.actor, - allowed: row.allowed, + allowed: row.allowed === true, + verdict: row.verdict, trace: [ - `${gate.policy.label}: ${row.allowed ? 'allow' : 'deny'}`, + `${gate.policy.label}: ${row.verdict === 'needs-input' ? 'needs input' : row.verdict}`, ...(row.deciding === null ? [] : [`deciding rule: ${row.deciding}`]), ...(row.reason === null ? [] : [`reason: ${row.reason}`]), `enforced in: ${gate.usedBy.join(', ')}`, diff --git a/packages/cli/src/doctor-probe.ts b/packages/cli/src/doctor-probe.ts index 4e33a2c15..9ae617ddb 100644 --- a/packages/cli/src/doctor-probe.ts +++ b/packages/cli/src/doctor-probe.ts @@ -56,7 +56,8 @@ export interface DoctorProbe { /** * The framework's own secrets this machine lacks — `framework-env.ts`'s * `machineSecretFindings`, gated by `namedDeployed`: only an environment NAMED staging or - * production (an unnamed developer shell owes nothing; `x env check` is the fail-closed answer). + * production (an unnamed developer shell owes nothing; `x env check` is the fail-closed answer + * under `CI` only — elsewhere it checks an unnamed shell as development, as `x dev` runs). * The list's own `needed`/`unsafe` decide; doctor reports. */ readonly frameworkFindings: readonly Finding[]; diff --git a/packages/cli/src/framework-env.ts b/packages/cli/src/framework-env.ts index 43fefd21e..8f7b123fd 100644 --- a/packages/cli/src/framework-env.ts +++ b/packages/cli/src/framework-env.ts @@ -32,8 +32,9 @@ export const deployed = (env: EnvTable): boolean => devSecretsRefused({ env }); /** * Does `env` NAME a deployed environment — `ULTIMATE_ENV`, else `NODE_ENV`, resolving to * `staging` or `production`? `x doctor`'s gate, and deliberately not `deployed`: the two commands - * answer different questions. `x env check` asks what a deployed boot does with a table, and the - * boot fails closed, so an unnamed table is a deploy there. `x doctor` asks about THIS machine, + * answer different questions. `x env check` asks what a boot does with a table: an unnamed one is + * checked as `x dev` runs it (development), except under `CI`, where the boot fails closed and it + * is a deploy (`cmd-env.ts`'s `checkedAsDev`). `x doctor` asks about THIS machine, * and a developer shell that names nothing is not a deploy — reporting the shipped keys there would * put two findings in front of every developer on day one. An unknown `ULTIMATE_ENV` names * nothing (`tryResolveEnvironment`): the boot refuses it first, and doctor must not crash on it. @@ -43,7 +44,10 @@ export const namedDeployed = (env: EnvTable): boolean => { return environment === 'staging' || environment === 'production'; }; -/** Does `env` name no environment? The boot then reads it as production, and `x env check` says so. */ +/** + * Does `env` name no environment? The boot then reads it as production; `x env check` checks it so + * under `CI` only, and as development elsewhere — and says which. + */ export const namesNoEnvironment = (env: EnvTable): boolean => // Core's reading, twice: only a table that names nothing answers with whichever fallback it got. tryResolveEnvironment({ env, fallback: 'production' }) !== diff --git a/packages/cli/src/policy-facts.ts b/packages/cli/src/policy-facts.ts index f936e2d0f..b275ffc05 100644 --- a/packages/cli/src/policy-facts.ts +++ b/packages/cli/src/policy-facts.ts @@ -4,18 +4,12 @@ import type { AnyAction } from '@ultimat3/action'; import { describeActions, getAction } from '@ultimat3/action'; -import type { MatrixRow, NamedActor, Policy } from '@ultimat3/policy'; -import { - decideBeforeInput, - knownPermissions, - policyMatrix, - reasonOf, - roleDefinitions, - rolesGranting, -} from '@ultimat3/policy'; +import type { Policy } from '@ultimat3/policy'; +import { knownPermissions, policyMatrix, roleDefinitions, rolesGranting } from '@ultimat3/policy'; import type { AnyQuery } from '@ultimat3/query'; import { describeQueries, getQuery } from '@ultimat3/query'; import { devActors } from './dev-policy'; +import { decided, type ExplainRow, rowWithoutInput } from './policy-row'; const isDefined = (value: T | undefined): value is T => value !== undefined; @@ -88,20 +82,6 @@ export function listPolicy(): PolicyListFacts { export type DeclarationKind = 'action' | 'query'; export type SubjectKind = 'permission' | DeclarationKind; -/** - * `needs-input` is NOT a denial: the actor passes every clause that reads only the actor, and a - * predicate then read the request's input — which this command was not given. Reported as a deny - * it sent the reader to edit a correct policy: every input-scoped rule (all that `x g resource` - * writes) read "predicate returned false" about the admin who had just succeeded over HTTP. - */ -export type ExplainVerdict = 'allow' | 'deny' | 'needs-input'; - -/** A `MatrixRow` that can also say "not decided". `allowed` is `null` exactly when it was not. */ -export interface ExplainRow extends Omit { - readonly verdict: ExplainVerdict; - readonly allowed: boolean | null; -} - /** What `x policy explain --input ''` supplies: the request's input, parsed. */ export interface ExplainOptions { /** Absent: no input was given, and a rule that reads one is `needs-input`. */ @@ -140,66 +120,6 @@ export interface SubjectExplanation { /** The matrix half of a declaration: the rows, and whether they mean anything at all. */ type DeclarationMatrix = Pick; -const decided = (row: MatrixRow): ExplainRow => ({ - ...row, - verdict: row.allowed ? 'allow' : 'deny', -}); - -/** - * A stand-in for the input nobody supplied, which records being READ. Every trap a predicate can - * reach it through answers "nothing there" — what `{}` answered — and sets the flag, so a verdict - * that came out of reading it is known to be a verdict about no request at all. - */ -function absentInput(): { readonly value: object; read(): boolean } { - let touched = false; - const touch = (answer: T): T => { - touched = true; - return answer; - }; - const value = new Proxy( - {}, - { - get: () => touch(undefined), - has: () => touch(false), - ownKeys: () => touch([]), - getOwnPropertyDescriptor: () => touch(undefined), - }, - ); - return { value, read: () => touched }; -} - -/** - * One actor with no input to hand the policy. The before-input gate (`decideBeforeInput`, the one - * the HTTP surface runs before it parses a body) says whether a predicate has to run for this - * actor at all; when one does, the full evaluation runs over `absentInput()`, and a predicate - * that read it — or threw reading it — is `needs-input`, never a deny. A predicate that reads - * only the actor decides as it would on a request. `policyMatrix` stays the only decider. - */ -function rowWithoutInput(policy: Policy, entry: NamedActor): ExplainRow { - const input = absentInput(); - let row: MatrixRow | undefined; - try { - row = policyMatrix(policy, { actors: [entry], input: input.value }).rows[0]; - } catch { - row = undefined; - } - const before = decideBeforeInput(policy, { actor: entry.actor }); - if (row !== undefined && !(before === undefined && input.read())) return decided(row); - // Decided whatever the input is, and a predicate past the deciding clause threw on the stand-in. - if (before !== undefined) { - const { allowed } = before; - return decided({ actor: entry.name, allowed, reason: reasonOf(before), deciding: null }); - } - const clause = row?.deciding ?? policy.label; - return { - actor: entry.name, - verdict: 'needs-input', - allowed: null, - deciding: row?.deciding ?? null, - reason: `not denied — every actor-only clause passes, and ${clause} has a predicate that reads the request input`, - }; -} - /** * One `testActor` per declared role plus the anonymous caller — the same actor set the `/_x` * policy panel asks about (`devActors`, `dev-policy.ts`). Reusing it is the point: a second diff --git a/packages/cli/src/policy-row.ts b/packages/cli/src/policy-row.ts new file mode 100644 index 000000000..d890a4051 --- /dev/null +++ b/packages/cli/src/policy-row.ts @@ -0,0 +1,80 @@ +// One actor's verdict on a policy, with or without the request's input: the row both `x policy +// explain` and the `/_x` policy panel draw. Without input, a predicate that READS input is +// `needs-input` — never the deny a stand-in `{}` produced. `policyMatrix` stays the only decider. + +import type { MatrixRow, NamedActor, Policy } from '@ultimat3/policy'; +import { decideBeforeInput, policyMatrix, reasonOf } from '@ultimat3/policy'; + +/** + * `needs-input` is NOT a denial: the actor passes every clause that reads only the actor, and a + * predicate then read the request's input — which this command was not given. Reported as a deny + * it sent the reader to edit a correct policy: every input-scoped rule (all that `x g resource` + * writes) read "predicate returned false" about the admin who had just succeeded over HTTP. + */ +export type ExplainVerdict = 'allow' | 'deny' | 'needs-input'; + +/** A `MatrixRow` that can also say "not decided". `allowed` is `null` exactly when it was not. */ +export interface ExplainRow extends Omit { + readonly verdict: ExplainVerdict; + readonly allowed: boolean | null; +} + +export const decided = (row: MatrixRow): ExplainRow => ({ + ...row, + verdict: row.allowed ? 'allow' : 'deny', +}); + +/** + * A stand-in for the input nobody supplied, which records being READ. Every trap a predicate can + * reach it through answers "nothing there" — what `{}` answered — and sets the flag, so a verdict + * that came out of reading it is known to be a verdict about no request at all. + */ +function absentInput(): { readonly value: object; read(): boolean } { + let touched = false; + const touch = (answer: T): T => { + touched = true; + return answer; + }; + const value = new Proxy( + {}, + { + get: () => touch(undefined), + has: () => touch(false), + ownKeys: () => touch([]), + getOwnPropertyDescriptor: () => touch(undefined), + }, + ); + return { value, read: () => touched }; +} + +/** + * One actor with no input to hand the policy. The before-input gate (`decideBeforeInput`, the one + * the HTTP surface runs before it parses a body) says whether a predicate has to run for this + * actor at all; when one does, the full evaluation runs over `absentInput()`, and a predicate + * that read it — or threw reading it — is `needs-input`, never a deny. A predicate that reads + * only the actor decides as it would on a request. `policyMatrix` stays the only decider. + */ +export function rowWithoutInput(policy: Policy, entry: NamedActor): ExplainRow { + const input = absentInput(); + let row: MatrixRow | undefined; + try { + row = policyMatrix(policy, { actors: [entry], input: input.value }).rows[0]; + } catch { + row = undefined; + } + const before = decideBeforeInput(policy, { actor: entry.actor }); + if (row !== undefined && !(before === undefined && input.read())) return decided(row); + // Decided whatever the input is, and a predicate past the deciding clause threw on the stand-in. + if (before !== undefined) { + const { allowed } = before; + return decided({ actor: entry.name, allowed, reason: reasonOf(before), deciding: null }); + } + const clause = row?.deciding ?? policy.label; + return { + actor: entry.name, + verdict: 'needs-input', + allowed: null, + deciding: row?.deciding ?? null, + reason: `not denied — every actor-only clause passes, and ${clause} has a predicate that reads the request input`, + }; +} diff --git a/packages/cli/src/templates/guard-released-forms.ts b/packages/cli/src/templates/guard-released-forms.ts index fe9d2d8ee..a8e57ef66 100644 --- a/packages/cli/src/templates/guard-released-forms.ts +++ b/packages/cli/src/templates/guard-released-forms.ts @@ -129,9 +129,14 @@ export const RELEASED_GUARD_FORMS: Readonly< 'undeclared-env': [ ['16pof11n1trhg', 'error'], ['1f8kizielequo', 'error'], + ['1fc7m95vm6k3g', 'error'], + ['20rw6oj7g0bz3', 'error'], ['2jb32jms80mge', 'error'], ['2t3qtexnpfnyq', 'error'], + ['2x7h5rxf4hv0g', 'error'], ['3gsoj050vbe69', 'error'], + ['3mtci6brks9i6', 'error'], + ['3rmwdbc6jgv5q', 'error'], ], 'undefined-style-class': [ ['3food9t4vrzv8', 'error'], diff --git a/packages/core/src/env.test.ts b/packages/core/src/env.test.ts index 486ba72f3..28bb52eba 100644 --- a/packages/core/src/env.test.ts +++ b/packages/core/src/env.test.ts @@ -77,16 +77,19 @@ describe('defineEnv', () => { }); test('a key with a declared fix is never given a generated line', () => { + // A command this build ships: the `errors` step runs every fix line a test cites. + const STRIPE_FIX = + 'x env check --json # STRIPE_KEY: the secret key the Stripe dashboard shows'; let fix = ''; try { defineEnv( - { STRIPE_KEY: { type: 'string', fix: 'x stripe login' } }, + { STRIPE_KEY: { type: 'string', fix: STRIPE_FIX } }, { env: { ROLE: 'web' }, redact: false }, ); } catch (thrown) { fix = (thrown as UltimateError).fix; } - expect(fix).toBe('x stripe login'); + expect(fix).toBe(STRIPE_FIX); }); test("each issue's fix is a command that finds the line, the key never spliced raw", () => { diff --git a/packages/http/src/errors.test.ts b/packages/http/src/errors.test.ts index 278346ca2..702c90546 100644 --- a/packages/http/src/errors.test.ts +++ b/packages/http/src/errors.test.ts @@ -160,7 +160,9 @@ describe('forbidden', () => { // command this error told the reader to run was the one command that could not work. test('names the POLICY, never the pathname, when the route declares one', () => { const error = forbidden('/settings', 'not the owner', 'member:self'); - expect(error.fix).toBe('x policy explain member:self --json # shows which clause denied'); + expect(error.fix).toBe( + "x policy explain member:self --input '' --json # shows which clause denied; --input decides a predicate that reads the request", + ); expect(error.fix).not.toContain('/settings'); }); diff --git a/packages/http/src/errors.ts b/packages/http/src/errors.ts index df5128c46..2a62c9cda 100644 --- a/packages/http/src/errors.ts +++ b/packages/http/src/errors.ts @@ -194,7 +194,7 @@ export const forbidden = (pathname: string, reason: string, policy?: string): Ht cause: `${pathname} denied: ${reason}`, fix: policy !== undefined && POLICY_SUBJECT.test(policy) - ? `x policy explain ${renderFixShellArg(policy, '')} --json # shows which clause denied` + ? `x policy explain ${renderFixShellArg(policy, '')} --input '' --json # shows which clause denied; --input decides a predicate that reads the request` : `x routes --json # find ${pathname}, then read the policy it declares`, callerFix: deniedCallerFix( policy !== undefined && POLICY_SUBJECT.test(policy) ? policy : undefined, diff --git a/packages/http/src/pipeline-authz.test.ts b/packages/http/src/pipeline-authz.test.ts index c437090f9..e2cebd042 100644 --- a/packages/http/src/pipeline-authz.test.ts +++ b/packages/http/src/pipeline-authz.test.ts @@ -68,7 +68,9 @@ describe('authz stage refusals', () => { const problem = await problemOf(response); expect(problem.code).toBe('X_FORBIDDEN'); // `x policy explain /settings` exits `X_DECLARATION_UNKNOWN`: a pathname is not a subject. - expect(problem.fix).toBe('x policy explain member:self --json # shows which clause denied'); + expect(problem.fix).toBe( + "x policy explain member:self --input '' --json # shows which clause denied; --input decides a predicate that reads the request", + ); }); test("outside dev a caller is told what IT can do — the developer's command stays in the log", async () => { @@ -86,7 +88,9 @@ describe('authz stage refusals', () => { const response = await pipelineWith().handle(get('/unwired'), { role: 'web' }); expect(response.status).toBe(403); const problem = await problemOf(response); - expect(problem.fix).toBe('x policy explain post:publish --json # shows which clause denied'); + expect(problem.fix).toBe( + "x policy explain post:publish --input '' --json # shows which clause denied; --input decides a predicate that reads the request", + ); }); test('the cause still carries the pathname, so the log line locates the route', async () => { diff --git a/packages/i18n/src/errors.ts b/packages/i18n/src/errors.ts index c78de69fb..ee2d8c320 100644 --- a/packages/i18n/src/errors.ts +++ b/packages/i18n/src/errors.ts @@ -58,7 +58,7 @@ export function catalogMissingKeys(locale: string, keys: readonly string[]): I18 return new I18nError({ code: 'X_CATALOG_MISSING_KEYS', cause: `packages/i18n/catalogs/${locale}.json is missing ${keys.length} key(s) source names or the reference locale defines: ${shown.join(', ')}${suffix}`, - fix: `x i18n sync ${renderFixShellArg(locale, '')} # writes each key above as ⟦key⟧ — replace every one with the real string`, + fix: `x i18n sync ${renderFixShellArg(locale, '')} # writes each key above as a placeholder to replace with the real string: ⟦key⟧ in the default locale, ⟦the default locale’s string⟧ in any other`, }); } diff --git a/packages/i18n/src/extract.test.ts b/packages/i18n/src/extract.test.ts index fcba23543..622a71c31 100644 --- a/packages/i18n/src/extract.test.ts +++ b/packages/i18n/src/extract.test.ts @@ -141,6 +141,15 @@ describe('auditCatalogs', () => { expect(cause).toContain('es.json'); expect(cause).toContain('admin.nav.jobs'); }); + + // `x i18n sync` writes `⟦key⟧` only in the default locale; any other gets the default locale's + // string inside `⟦…⟧`. `x errors explain X_CATALOG_MISSING_KEYS` quotes this literal. + test('the fix comment says what the sync writes in a non-default locale too', () => { + const { fix } = catalogMissingKeys('es', ['a.b']); + expect(fix).toBe( + 'x i18n sync es # writes each key above as a placeholder to replace with the real string: ⟦key⟧ in the default locale, ⟦the default locale’s string⟧ in any other', + ); + }); }); describe('extractKeys \u00B7 declared properties', () => { diff --git a/packages/jobs/src/limits-rate-scale.test.ts b/packages/jobs/src/limits-rate-scale.test.ts index 778f35343..af94121c3 100644 --- a/packages/jobs/src/limits-rate-scale.test.ts +++ b/packages/jobs/src/limits-rate-scale.test.ts @@ -21,19 +21,32 @@ function fakeClock(startMs: number): Clock & { advance(ms: number): void } { const N = 20_000; describe('a large rate window', () => { + // Linear is judged as a RATIO, never a wall-clock bound: the last quarter of the acquires runs + // over a window holding 3N/4 stamps, the first over a near-empty one. O(1) a claim makes the two + // quarters cost the same (the first pays the JIT warm-up, so it is if anything the slower); an + // O(n) claim makes the last ~7x the first. A loaded machine slows both quarters alike, so the + // ratio holds where `< 250 ms` read 283 ms under three concurrent preflights. test(`${N} acquires in one window are linear, and the next one is refused`, () => { const clock = fakeClock(T0); const limiter = concurrencyLimiter({ ratePerTenant: { limit: N, windowMs: 60_000 } }, clock); - const started = performance.now(); + const quarter = N / 4; + const quarterMs: number[] = []; + let started = performance.now(); for (let index = 0; index < N; index += 1) { const lease = limiter.tryAcquire({ queue: 'q', tenantId: 'org' }); if (lease === undefined) return expect.unreachable(`acquire ${index} was refused`); lease.release(); if (index % 10 === 0) clock.advance(1); + if ((index + 1) % quarter === 0) { + const now = performance.now(); + quarterMs.push(now - started); + started = now; + } } - // Was ~3.9 s. Budgeted at 250 ms, not the 100 ms measured headroom, so a loaded CI runner is - // not a red build; a quadratic window is an order of magnitude past either. - expect(performance.now() - started).toBeLessThan(250); + const [first = 0, , , last = 0] = quarterMs; + // `max(first, 1)`: a quarter faster than a millisecond is linear by any reading, and a ratio + // over a sub-millisecond denominator measures the timer, not the window. + expect(last / Math.max(first, 1)).toBeLessThan(3); expect(limiter.tryAcquire({ queue: 'q', tenantId: 'org' })).toBeUndefined(); expect(limiter.blockedBy({ queue: 'q', tenantId: 'org' })).toBe('rate'); }); diff --git a/packages/policy/src/errors.test.ts b/packages/policy/src/errors.test.ts index 43e70d65f..3a4b33a1b 100644 --- a/packages/policy/src/errors.test.ts +++ b/packages/policy/src/errors.test.ts @@ -26,10 +26,10 @@ describe('policyForbidden()', () => { // `knownPolicySubjects()` (cli's `policy-facts.ts`) holds every declared permission, so this // is the one label shape the command can answer. expect(policyForbidden(can('post:publish').label, 'no').fix).toContain( - 'x policy explain post:publish --json', + "x policy explain post:publish --input '' --json", ); expect(policyForbidden('org_admin:read-all', 'no').fix).toContain( - 'x policy explain org_admin:read-all --json', + "x policy explain org_admin:read-all --input '' --json", ); }); diff --git a/packages/policy/src/errors.ts b/packages/policy/src/errors.ts index d4928844f..a06d59984 100644 --- a/packages/policy/src/errors.ts +++ b/packages/policy/src/errors.ts @@ -108,7 +108,7 @@ export const policyForbidden = (label: string, reason: string): PolicyError => // `x policy list --json` is what `X_DECLARATION_UNKNOWN`'s own fix falls back to, so a reader // who follows either one lands in the same place. fix: BARE_PERMISSION.test(label) - ? `x policy explain ${renderFixShellArg(label, '')} --json # shows which clause decided and why` + ? `x policy explain ${renderFixShellArg(label, '')} --input '' --json # shows which clause decided and why; --input decides a predicate that reads the request` : `x policy list --json # then: x policy explain --json for the clause that decided`, // The remote caller's half: it holds a credential, not the policy file. callerFix: deniedCallerFix(BARE_PERMISSION.test(label) ? label : undefined), diff --git a/packages/query/src/errors.test.ts b/packages/query/src/errors.test.ts index 1598c2498..38f583f71 100644 --- a/packages/query/src/errors.test.ts +++ b/packages/query/src/errors.test.ts @@ -5,7 +5,12 @@ import { describe, expect, test } from 'bun:test'; import { ERROR_DOCS_URL, type UltimateError } from '@ultimat3/core'; -import { QueryDuplicateError, QueryPolicyMissingError, QueryUnregisteredError } from './errors'; +import { + QueryDeniedError, + QueryDuplicateError, + QueryPolicyMissingError, + QueryUnregisteredError, +} from './errors'; const CAN_ARGUMENT = /can\('(?[^']*)'\)/; @@ -54,3 +59,27 @@ describe('unit · every query error documents at the one page core declares', () } }); }); + +// Same rule as the action's: `x policy explain` decides a predicate that reads input only on +// `--input`, so the fix names the flag — as a placeholder, never the request's own value. +describe('unit · X_FORBIDDEN names --input as a placeholder', () => { + test('the fix carries the --input form and no request value', () => { + const error = new QueryDeniedError({ + kind: 'query', + name: 'postList', + surface: 'server', + code: 'X_FORBIDDEN', + reason: 'not a member', + denial: { + surface: 'job', + outcome: 'failed', + retryable: false, + code: 'X_FORBIDDEN', + reason: 'not a member', + }, + }); + expect(error.fix).toStartWith( + "x policy explain postList --input '' --json", + ); + }); +}); diff --git a/packages/query/src/errors.ts b/packages/query/src/errors.ts index 51e6e1a07..50ef44959 100644 --- a/packages/query/src/errors.ts +++ b/packages/query/src/errors.ts @@ -91,7 +91,7 @@ export class QueryDeniedError extends UltimateError { super({ code: refused.code, cause: `${refused.name} denied: ${refused.reason}`, - fix: `x policy explain ${renderFixShellArg(refused.name, '')} --json # shows which clause decided and why`, + fix: `x policy explain ${renderFixShellArg(refused.name, '')} --input '' --json # shows which clause decided and why; --input decides a predicate that reads the request`, callerFix: deniedCallerFix(), }); this.denial = refused.denial; diff --git a/scripts/doc-fix-agreement.ts b/scripts/doc-fix-agreement.ts index 19bb9ed61..3f1008287 100644 --- a/scripts/doc-fix-agreement.ts +++ b/scripts/doc-fix-agreement.ts @@ -28,8 +28,9 @@ const PAGE = 'the wiki/Error-Codes*.md pages'; * `X_CONFIG_INVALID`'s 23), where the page states the class of remedy and each site its instance; * a few are a row ahead of a stale site (`X_RPC_FAILED`'s site is thrown by nothing since 21.0.0). * Agreeing one lowers this by one in the same diff; `X_DOC_FIX_DISAGREES_PIN_STALE` says when. + * lowered 17 → 16, measured 16 (2026-11-19, r9 sweep 3): a row the docs pass brought into agreement. */ -export const DISAGREEMENT_PIN = 17; +export const DISAGREEMENT_PIN = 16; /** One site's registered fix; `undefined` when the site builds it at run time. */ export interface RegisteredFix { diff --git a/scripts/lib/guard-refresh-forms.test.ts b/scripts/lib/guard-refresh-forms.test.ts new file mode 100644 index 000000000..cbc295268 --- /dev/null +++ b/scripts/lib/guard-refresh-forms.test.ts @@ -0,0 +1,38 @@ +// A released guard form, once recorded, is never dropped by a later `--write`. A tag's templates are +// re-read against the WORKING TREE's `@ultimat3/*` (the workspace links), so a rule that embeds a +// framework value (`undeclared-env` writes core's `FRAMEWORK_ENV` into its text) re-hashes every past +// tag under today's value — and the hash an app's unedited copy actually carries was erased. + +import { describe, expect, test } from 'bun:test'; +import { withRecorded } from './guard-refresh-forms'; + +describe('unit · guard-refresh-forms keeps every recorded form', () => { + test('a recorded hash the regeneration no longer produces stays, with its severity', () => { + const forms = { 'undeclared-env': new Map([['new', 'error' as const]]) }; + const tests = { 'undeclared-env': new Set(['t-new']) }; + const merged = withRecorded( + { forms, tests }, + { 'undeclared-env': [['old', 'warning']] }, + { 'undeclared-env': ['t-old'] }, + ); + expect([...(merged.forms['undeclared-env'] ?? [])].sort()).toEqual([ + ['new', 'error'], + ['old', 'warning'], + ]); + expect([...(merged.tests['undeclared-env'] ?? [])].sort()).toEqual(['t-new', 't-old']); + }); + + test('a hash both hold keeps the regenerated severity', () => { + const merged = withRecorded( + { forms: { a: new Map([['h', 'error' as const]]) }, tests: {} }, + { a: [['h', 'warning']] }, + {}, + ); + expect([...(merged.forms['a'] ?? [])]).toEqual([['h', 'error']]); + }); + + test('a guard no longer shipped is not carried: the table is per shipped guard', () => { + const merged = withRecorded({ forms: {}, tests: {} }, { gone: [['h', 'error']] }, {}); + expect(merged.forms).toEqual({}); + }); +}); diff --git a/scripts/lib/guard-refresh-forms.ts b/scripts/lib/guard-refresh-forms.ts index 44e894497..4b5950975 100644 --- a/scripts/lib/guard-refresh-forms.ts +++ b/scripts/lib/guard-refresh-forms.ts @@ -10,6 +10,10 @@ import { mkdirSync, rmSync } from 'node:fs'; // why: Bun exposes no path-join primitive. import { join } from 'node:path'; import { guardFormHash } from '../../packages/cli/src/guards-vendored'; +import { + RELEASED_GUARD_FORMS, + RELEASED_GUARD_TEST_FORMS, +} from '../../packages/cli/src/templates/guard-released-forms'; import { reportOnlyForm, SHIPPED_GUARD_NAMES, @@ -98,6 +102,31 @@ export async function releasedForms( return { forms, tests }; } +/** + * The regenerated table, plus every hash the committed one recorded for a guard still shipped. A + * tag's templates import `@ultimat3/*` from the WORKING TREE, so a rule embedding a framework value + * (`undeclared-env` writes core's `FRAMEWORK_ENV`) re-hashes every past tag under today's value: a + * rewrite from scratch erased the hash an app's unedited copy really carries, and the codemod then + * kept that copy as the app's edit. A recorded form is history; history is only ever added to. + */ +export function withRecorded( + regenerated: { readonly forms: Forms; readonly tests: TestForms }, + recordedForms: Readonly>, + recordedTests: Readonly>, +): { readonly forms: Forms; readonly tests: TestForms } { + const forms: Forms = {}; + const tests: TestForms = {}; + for (const [name, known] of Object.entries(regenerated.forms)) { + const merged = new Map(Object.hasOwn(recordedForms, name) ? recordedForms[name] : []); + for (const [hash, severity] of known) merged.set(hash, severity); + forms[name] = merged; + const recorded = Object.hasOwn(recordedTests, name) ? (recordedTests[name] ?? []) : []; + const testHashes = new Set([...recorded, ...(regenerated.tests[name] ?? [])]); + if (testHashes.size > 0) tests[name] = testHashes; + } + return { forms, tests }; +} + /** * A key's entries in Biome's layout, so the written file is already formatted: on the key's line * when one pair, or flat strings that fit the 100 columns; otherwise one per line. @@ -147,7 +176,9 @@ ${testRows.join('\n')} if (import.meta.main) { const root = repoRoot(); - const rendered = renderForms(await releasedForms(root)); + const rendered = renderForms( + withRecorded(await releasedForms(root), RELEASED_GUARD_FORMS, RELEASED_GUARD_TEST_FORMS), + ); if (process.argv.includes('--write')) await Bun.write(join(root, FORMS_FILE), rendered); const current = await Bun.file(join(root, FORMS_FILE)) .text() diff --git a/scripts/lib/public-api.lock.json b/scripts/lib/public-api.lock.json index 72d10fa2e..556ec60bc 100644 --- a/scripts/lib/public-api.lock.json +++ b/scripts/lib/public-api.lock.json @@ -554,8 +554,8 @@ "ManifestFact": {"hash":"78d78f96bd019ea9","shape":{"kind":"members","head":"21267f46","members":{"committed":"2456a234","diff":"03360437","emitted":"2456a234"}}}, "ManifestPanelData": {"hash":"537de17cf0740243","shape":{"kind":"members","head":"32e451df","members":{"added":"f8639a23","changed":"f8639a23","drifted":"a001763a","fix":"1fb0a448","manifest":"09de8e10","removed":"f8639a23"}}}, "PanelPayload": {"hash":"7efb07a0e89cf464","shape":{"kind":"declaration","keyword":"type","head":"7efb07a0"}}, - "PolicyFact": {"hash":"301ab950a4acfc67","shape":{"kind":"members","head":"7bcfcb13","members":{"actorId":"1fb0a448","allowed":"a001763a","permission":"1fb0a448","trace":"f8639a23"}}}, - "PolicyPanelData": {"hash":"69659ac25519780d","shape":{"kind":"members","head":"8d434c6a","members":{"actors":"f8639a23","facts":"d6d3cd2a","matrix":"e111a1f0","permissions":"f8639a23","trace":"f8639a23","unreachable":"f8639a23"}}}, + "PolicyFact": {"hash":"11dd806b48d9dcb0","shape":{"kind":"members","head":"7bcfcb13","members":{"actorId":"1fb0a448","allowed":"a001763a","permission":"1fb0a448","trace":"f8639a23","verdict":"?c9826bd4"}}}, + "PolicyPanelData": {"hash":"808ad46986452ab8","shape":{"kind":"members","head":"8d434c6a","members":{"actors":"f8639a23","facts":"d6d3cd2a","matrix":"e111a1f0","needsInput":"?f8639a23","permissions":"f8639a23","trace":"f8639a23","unreachable":"f8639a23"}}}, "QueueFact": {"hash":"b757c77b69b1142c","shape":{"kind":"members","head":"f628b3e9","members":{"deadLetter":"4e57c805","depth":"4e57c805","failed":"4e57c805","name":"1fb0a448","paused":"a001763a","running":"4e57c805"}}}, "ReadOnlyVerdict": {"hash":"d7595302425bafeb","shape":{"kind":"declaration","keyword":"type","head":"d7595302"}}, "RequestTrace": {"hash":"cbd91e3de055e9d3","shape":{"kind":"members","head":"18dc6cae","members":{"method":"1fb0a448","path":"1fb0a448","requestId":"1fb0a448","spans":"c86a25ed","startedAt":"1fb0a448","status":"4e57c805","totalMs":"4e57c805"}}}, @@ -701,7 +701,7 @@ "Gateway": {"hash":"7c82a8c5ca0cf712","shape":{"kind":"members","head":"2af43abc","members":{"callLedger":"0867f2c3","defaultModel":"?76be5e96","generate":"68673862","marksPromptCache":"?0bac0076","samplingWires":"?0765ecd2","scope":"cfa7c1b2","spent":"f06dc546","stream":"da5d332c"}}}, "GatewayBreakerOption": {"hash":"d546ab058ee149f5","shape":{"kind":"declaration","keyword":"type","head":"d546ab05"}}, "GatewayCache": {"hash":"6b09b80872176ff5","shape":{"kind":"members","head":"bf6e0e70","members":{"get":"3f12686a","set":"9188827d"}}}, - "GenerateRequest": {"hash":"4c889b94c527ee6d","shape":{"kind":"members","head":"fe8b89d6","members":{"effort":"?2d684a3d","fallbackModels":"?cf2675ce","maxTokens":"4e57c805","messages":"588dae54","model":"?376db075","promptCache":"?2a41412d","providerOptions":"?79b0a527","seed":"?4e57c805","signal":"?2b99db86","stopSequences":"?f8639a23","system":"?9a6541df","temperature":"?4e57c805","thinking":"?e8355593","tools":"?2653e4e9"}}}, + "GenerateRequest": {"hash":"78f38e8931669ba8","shape":{"kind":"members","head":"fe8b89d6","members":{"effort":"?2d684a3d","fallbackModels":"?cf2675ce","maxTokens":"4e57c805","messages":"588dae54","model":"?376db075","promptCache":"?2a41412d","providerOptions":"?79b0a527","seed":"?4e57c805","signal":"?2b99db86","stopSequences":"?f8639a23","system":"?9a6541df","temperature":"?4e57c805","thinking":"?e8355593","toolChoice":"?943ab0df","tools":"?2653e4e9"}}}, "GenerateResult": {"hash":"855043eac7ff14ec","shape":{"kind":"members","head":"f33183ac","members":{"cost":"2dca7dbd","costExact":"?2dca7dbd","fallbacks":"?ec265cbc","model":"376db075","provider":"?1fb0a448","stopDetails":"cc0bbe2b","stopReason":"e3e55cfc","text":"1fb0a448","toolCalls":"e6a80b35","usage":"871a0e75"}}}, "HashEmbedder": {"hash":"85581e295c48015f","shape":{"kind":"class","head":"7109db5c","members":{"dimension":"4e57c805","embed":"3341f28f","name":"6df842b8"},"ctor":["?4fb9a5ff"]}}, "HashEmbedderInput": {"hash":"a9f15a7dbefe67f8","shape":{"kind":"members","head":"493a2ed9","members":{"dimension":"?4e57c805"}}}, @@ -904,7 +904,7 @@ "BudgetLedger": {"hash":"f6a0051a62a52b39","shape":{"kind":"class","head":"024606f4","members":{"derive":"08ab12c9","record":"6b096a55","release":"2d01ea48","report":"bbececd3","reserve":"74784887"},"ctor":["d9f5bffc"]}}, "Embedder": {"hash":"500dcde0d3d6ed87","shape":{"kind":"members","head":"0d96823d","members":{"dimension":"4e57c805","embed":"3341f28f","name":"1fb0a448"}}}, "Gateway": {"hash":"7c82a8c5ca0cf712","shape":{"kind":"members","head":"2af43abc","members":{"callLedger":"0867f2c3","defaultModel":"?76be5e96","generate":"68673862","marksPromptCache":"?0bac0076","samplingWires":"?0765ecd2","scope":"cfa7c1b2","spent":"f06dc546","stream":"da5d332c"}}}, - "GenerateRequest": {"hash":"4c889b94c527ee6d","shape":{"kind":"members","head":"fe8b89d6","members":{"effort":"?2d684a3d","fallbackModels":"?cf2675ce","maxTokens":"4e57c805","messages":"588dae54","model":"?376db075","promptCache":"?2a41412d","providerOptions":"?79b0a527","seed":"?4e57c805","signal":"?2b99db86","stopSequences":"?f8639a23","system":"?9a6541df","temperature":"?4e57c805","thinking":"?e8355593","tools":"?2653e4e9"}}}, + "GenerateRequest": {"hash":"78f38e8931669ba8","shape":{"kind":"members","head":"fe8b89d6","members":{"effort":"?2d684a3d","fallbackModels":"?cf2675ce","maxTokens":"4e57c805","messages":"588dae54","model":"?376db075","promptCache":"?2a41412d","providerOptions":"?79b0a527","seed":"?4e57c805","signal":"?2b99db86","stopSequences":"?f8639a23","system":"?9a6541df","temperature":"?4e57c805","thinking":"?e8355593","toolChoice":"?943ab0df","tools":"?2653e4e9"}}}, "GenerateResult": {"hash":"855043eac7ff14ec","shape":{"kind":"members","head":"f33183ac","members":{"cost":"2dca7dbd","costExact":"?2dca7dbd","fallbacks":"?ec265cbc","model":"376db075","provider":"?1fb0a448","stopDetails":"cc0bbe2b","stopReason":"e3e55cfc","text":"1fb0a448","toolCalls":"e6a80b35","usage":"871a0e75"}}}, "ModelId": {"hash":"ee3819055db4ab4a","shape":{"kind":"declaration","keyword":"type","head":"ee381905"}}, "SamplingWire": {"hash":"bc5592feba46663b","shape":{"kind":"literals","head":"3be6e258","values":["7d3194f7","c70eca6b"]}}, @@ -946,7 +946,7 @@ "AuthRateLimitPolicy": {"hash":"22516311d83a2a03","shape":{"kind":"members","head":"d5a37c24","members":{"lockoutMs":"4e57c805","maxAttempts":"4e57c805","maxKeys":"?5d7469a7","orgMaxAttempts":"?5d7469a7","scope":"3a8ecd59","windowMs":"4e57c805"}}}, "AuthReservation": {"hash":"e61b8a3d8653ac7a","shape":{"kind":"members","head":"8f8e4694","members":{"atMs":"4e57c805","key":"1fb0a448"}}}, "AuthRouteDescriptor": {"hash":"125c0fb252c466e9","shape":{"kind":"members","head":"1b2ee4c7","members":{"auth":"ab689970","handle":"ad90166b","meta":"ed4c660a","method":"303bb57f","name":"1fb0a448","path":"1fb0a448"}}}, - "AuthServerClient": {"hash":"f258fccc48cf8445","shape":{"kind":"members","head":"a1d85d4e","members":{"authMethod":"5a0e441a","clientId":"1fb0a448","createdAt":"085a63b8","grantTypes":"c0691d82","name":"1fb0a448","redirectUris":"f8639a23","resources":"f8639a23","scopes":"f8639a23","secretHash":"c380b02d"}}}, + "AuthServerClient": {"hash":"ed872478bb7dc8b6","shape":{"kind":"members","head":"a1d85d4e","members":{"authMethod":"5a0e441a","clientId":"1fb0a448","createdAt":"085a63b8","grantTypes":"c0691d82","host":"?6c665e22","name":"1fb0a448","redirectUris":"f8639a23","resources":"f8639a23","scopes":"f8639a23","secretHash":"c380b02d"}}}, "AuthServerEvent": {"hash":"139a3c848e840903","shape":{"kind":"members","head":"057a4591","members":{"clientId":"?6c665e22","error":"?6c665e22","grantType":"?6c665e22","kind":"3789b020"}}}, "AuthServerGrant": {"hash":"dc816b7dac6fa5e0","shape":{"kind":"literals","head":"713b15fa","values":["2553a850","2bb82946","36b0bdee","88f0c1fa"]}}, "AuthServerHttpContext": {"hash":"f1a522620112f66c","shape":{"kind":"members","head":"02694ef9","members":{"ip":"c380b02d"}}}, @@ -1301,7 +1301,7 @@ "AuthLimiterFactory": {"hash":"082879dcfae5dbfe","shape":{"kind":"function","head":"18493e2a","params":["afedcca2"],"returns":"3bcf4744"}}, "AuthLimiterScope": {"hash":"c9397eba6f6fa2e8","shape":{"kind":"literals","head":"436df323","values":["b140b547","cb73c0b0"]}}, "AuthRateLimitPolicy": {"hash":"22516311d83a2a03","shape":{"kind":"members","head":"d5a37c24","members":{"lockoutMs":"4e57c805","maxAttempts":"4e57c805","maxKeys":"?5d7469a7","orgMaxAttempts":"?5d7469a7","scope":"3a8ecd59","windowMs":"4e57c805"}}}, - "AuthServerClient": {"hash":"f258fccc48cf8445","shape":{"kind":"members","head":"a1d85d4e","members":{"authMethod":"5a0e441a","clientId":"1fb0a448","createdAt":"085a63b8","grantTypes":"c0691d82","name":"1fb0a448","redirectUris":"f8639a23","resources":"f8639a23","scopes":"f8639a23","secretHash":"c380b02d"}}}, + "AuthServerClient": {"hash":"ed872478bb7dc8b6","shape":{"kind":"members","head":"a1d85d4e","members":{"authMethod":"5a0e441a","clientId":"1fb0a448","createdAt":"085a63b8","grantTypes":"c0691d82","host":"?6c665e22","name":"1fb0a448","redirectUris":"f8639a23","resources":"f8639a23","scopes":"f8639a23","secretHash":"c380b02d"}}}, "AuthServerStore": {"hash":"886cf86c9ed78720","shape":{"kind":"members","head":"6b069b0a","members":{"consumeDevice":"303ab096","decideDevice":"ff1e5b6e","deviceByUserCode":"c74d7e9c","getClient":"0a7d33ec","getCode":"d7da9a3e","getGrant":"7a4ce615","getToken":"95e379eb","pollDevice":"208be11b","purge":"c75867eb","putClient":"585bc4c2","putCode":"7896a1bd","putDevice":"4f8e4c74","putGrant":"3eb122fc","putToken":"575043b6","revokeGrant":"7955e945","revokeGrants":"522bd6ee","rotateRefresh":"b12e71d1","takeCode":"78305e52","touchGrant":"7955e945"}}}, "AuthTokenKind": {"hash":"0c32627929c06825","shape":{"kind":"literals","head":"a4819127","values":["0fd85c57","e9423b39"]}}, "AuthTokenRecord": {"hash":"f1de5613386bcb37","shape":{"kind":"members","head":"f421dcaf","members":{"createdAt":"085a63b8","expiresAt":"085a63b8","grantId":"1fb0a448","kind":"abf9bba5","retiredAt":"6d12c226","tokenHash":"1fb0a448"}}}, @@ -1522,7 +1522,7 @@ "DEFAULT_PORT": {"hash":"027f66bccba07899","shape":{"kind":"declaration","keyword":"const","head":"027f66bc"}}, "DEV_BINDING": {"hash":"b36f952ebe94c69d","shape":{"kind":"declaration","keyword":"const","head":"b36f952e"}}, "DEV_ROLES": {"hash":"07002d90bbf3eb91","shape":{"kind":"declaration","keyword":"const","head":"07002d90"}}, - "DoctorProbe": {"hash":"9605f5ddd3cf2cda","shape":{"kind":"members","head":"f89af633","members":{"appUrl":"6c665e22","authStorage":"1e94bd6a","bunVersion":"1fb0a448","database":"5451f576","drift":"fdc77de0","embeddedDatabase":"367bc00b","envNames":"d863606e","exists":"5b86e268","frameworkFindings":"a4c2a735","mergeDriverUnset":"?2c2a3276","mergeState":"?501e5289","offlineFallback":"82e1ee67","pins":"c98810d0","pooler":"1e7e13de","port":"4e57c805","portFree":"b6d6532d","portOwner":"?5e5be31d","root":"6c665e22","rowSecurity":"?fdc77de0","rowSecurityOff":"4c6cda06","sealedKeys":"9187134c","snapshots":"fdc77de0","typescript":"f667253c","unflooredSteps":"6d71d972"}}}, + "DoctorProbe": {"hash":"3900b55cad5d8895","shape":{"kind":"members","head":"f89af633","members":{"appUrl":"6c665e22","authStorage":"1e94bd6a","bunVersion":"1fb0a448","database":"5451f576","drift":"fdc77de0","embeddedDatabase":"367bc00b","envNames":"d863606e","exists":"5b86e268","frameworkFindings":"a4c2a735","mergeDriverUnset":"?2c2a3276","mergeState":"?501e5289","offlineFallback":"82e1ee67","pins":"c98810d0","pooler":"1e7e13de","port":"4e57c805","portFree":"b6d6532d","portOwner":"?5e5be31d","root":"6c665e22","rowSecurity":"?fdc77de0","rowSecurityOff":"4c6cda06","sealedKeys":"9187134c","snapshots":"fdc77de0","typescript":"f667253c","unflooredSteps":"6d71d972","unlistedPrimitives":"?501e5289"}}}, "ErrorCodePage": {"hash":"aeb3d867808268d7","shape":{"kind":"members","head":"89b36b24","members":{"path":"1fb0a448","text":"1fb0a448"}}}, "ExecOptions": {"hash":"8924e6bef7d6bc02","shape":{"kind":"members","head":"c3190773","members":{"cwd":"1fb0a448","env":"?fa15e968","inheritFds":"?6a01f5ed","onSpawn":"?b0744bb9","stdin":"?1fb0a448"}}}, "ExecResult": {"hash":"c238441be9cbf483","shape":{"kind":"members","head":"1f747144","members":{"code":"4e57c805","command":"f8639a23","durationMs":"4e57c805","ok":"a001763a","stderr":"1fb0a448","stdout":"1fb0a448"}}}, @@ -3087,7 +3087,7 @@ "ReplicatedClientOptions": {"hash":"322fd2f2cc868cb3","shape":{"kind":"members","head":"9b8b14d3","members":{"breakerCooldownMs":"?5d7469a7","breakerFailures":"?5d7469a7","clock":"?ec3d6144","positionCacheMs":"?5d7469a7"}}}, "ReservableClient": {"hash":"1c4d171da7baf5d4","shape":{"kind":"members","head":"47d972a6","members":{"reserve":"691faa8b"}}}, "RetainDescriptionLike": {"hash":"e9b3d2a37b9f8490","shape":{"kind":"members","head":"026185e0","members":{"after":"1fb0a448","on":"1fb0a448"}}}, - "RollbackOptions": {"hash":"6ba29caf1d35569e","shape":{"kind":"members","head":"ecf4ca9c","members":{"client":"?aaed5a91","lock":"?f4af6dab","lockRetries":"?5d7469a7","lockTimeoutMs":"?5d7469a7","lockWaitMs":"?5d7469a7","migrations":"94d28db6","steps":"?5d7469a7"}}}, + "RollbackOptions": {"hash":"f06b101d9ab5cbf4","shape":{"kind":"members","head":"ecf4ca9c","members":{"client":"?aaed5a91","confirm":"?69eae74c","lock":"?f4af6dab","lockRetries":"?5d7469a7","lockTimeoutMs":"?5d7469a7","lockWaitMs":"?5d7469a7","migrations":"94d28db6","steps":"?5d7469a7"}}}, "RollingUnsafeKind": {"hash":"57db317e8eae30d4","shape":{"kind":"literals","head":"39ecea71","values":["3d7a2eee","d4edef58","dfee8169"]}}, "RollingUnsafeStatement": {"hash":"5f849726b0ea8cd4","shape":{"kind":"members","head":"60874685","members":{"column":"c380b02d","kind":"58caa094","statement":"1fb0a448","table":"1fb0a448"}}}, "RowSecurityDifference": {"hash":"95be624a97481c57","shape":{"kind":"members","head":"250d0d9d","members":{"direction":"b77dffa7","table":"1fb0a448"}}}, @@ -3598,6 +3598,7 @@ "memoryRepo": {"hash":"d8a5ae611c449738","shape":{"kind":"function","head":"88b40334","params":["4077f25d","?4545958a","?6dd23698"],"returns":"3820eb67"}}, "memorySearchIndex": {"hash":"3c4aeb8186be626c","shape":{"kind":"function","head":"d2a1fde7","params":[],"returns":"0f6f9ca2"}}, "memoryTransactor": {"hash":"95a2dfa8c1e0ce77","shape":{"kind":"function","head":"d95db665","params":[],"returns":"ab7cecb4"}}, + "memoryTxOpen": {"hash":"cdbee8d7cd9209c8","shape":{"kind":"function","head":"a2eee35f","params":["5b9e8d7c"],"returns":"bf84d3d6"}}, "money": {"hash":"1c54bffaf98437be","shape":{"kind":"function","head":"64a036a3","params":["?117c1122"],"returns":"3e9ac006"}}, "moneyColumns": {"hash":"d55844fb2ca02d49","shape":{"kind":"function","head":"2775f5fa","params":["473287f8","fec6318e"],"returns":"2b524d96"}}, "nPlusOne": {"hash":"5370a1e2cd4cbb56","shape":{"kind":"function","head":"56118f27","params":["3ba6642d"],"returns":"b0ea7bf1"}}, @@ -3942,6 +3943,7 @@ "httpRouter": {"hash":"b0b464dd8e9e51f8","shape":{"kind":"function","head":"a987e877","params":["35d592df"],"returns":"eada0318"}}, "httpServer": {"hash":"e05834d1f56294f3","shape":{"kind":"function","head":"182e2a45","params":["1c7c7e20"],"returns":"bd5e257e"}}, "installedRateLimitStore": {"hash":"25f60175a518c378","shape":{"kind":"function","head":"4ac76508","params":[],"returns":"02e4962b"}}, + "isCallerAbort": {"hash":"bf960b3e09569d3b","shape":{"kind":"function","head":"6d74c2c4","params":["b23a6a84","b3da7007"],"returns":"bf84d3d6"}}, "isCompressibleType": {"hash":"48c7838b8bd98a3c","shape":{"kind":"function","head":"3e7d2626","params":["473287f8|74234e98"],"returns":"bf84d3d6"}}, "joinWebSocketMounts": {"hash":"36ad04ecf1bca11d","shape":{"kind":"function","head":"7ac0e849","params":["938c234c"],"returns":"38c2aba3"}}, "jsonResponse": {"hash":"d9d6e82d31f79609","shape":{"kind":"function","head":"b179a981","params":["e632b709","?ffb23d77"],"returns":"9061383b"}}, @@ -3981,6 +3983,7 @@ "relocate": {"hash":"563160185fec2ecc","shape":{"kind":"function","head":"fbdc7f32","params":["473287f8","?194e9fe6"],"returns":"9061383b"}}, "renderErrorLines": {"hash":"592934630af18131","shape":{"kind":"function","head":"e69d0e98","params":["b23a6a84"],"returns":"473287f8"}}, "renderErrorPage": {"hash":"c5a39eccb19f4350","shape":{"kind":"function","head":"b7ea7cc6","params":["54e4414c"],"returns":"473287f8"}}, + "reportLateFault": {"hash":"fed1e9a654098c61","shape":{"kind":"function","head":"4dd83226","params":["b23a6a84","?10bc96af|eb045d78"],"returns":"bf84d3d6"}}, "requestAddress": {"hash":"42258812e40b4d50","shape":{"kind":"function","head":"dfd73234","params":["c855c9fc"],"returns":"5f0f72b3"}}, "requestContext": {"hash":"a066466f6042b6c4","shape":{"kind":"function","head":"bf2d9405","params":["fb10d285"],"returns":"c855c9fc"}}, "requestFacts": {"hash":"9b09b137a40c5a83","shape":{"kind":"function","head":"4c47bbae","params":["b257ac2c"],"returns":"4b27ce60"}}, @@ -4620,7 +4623,7 @@ }, "@ultimat3/jobs/redis": { "DEFAULT_REDIS_DONE_TTL_MS": {"hash":"08059d54876799ee","shape":{"kind":"declaration","keyword":"const","head":"08059d54"}}, - "RedisJobDriverOptions": {"hash":"230bb3d3f0704d1e","shape":{"kind":"members","head":"d19864b7","members":{"client":"?c127e93c","clock":"?5a6c9eb0","doneTtlMs":"?4e57c805","prefix":"?1fb0a448"}}}, + "RedisJobDriverOptions": {"hash":"4e66bfa45f724a48","shape":{"kind":"members","head":"d19864b7","members":{"client":"?c127e93c","clock":"?5a6c9eb0","deadTtlMs":"?4e57c805","doneTtlMs":"?4e57c805","prefix":"?1fb0a448"}}}, "RedisSender": {"hash":"11ec043d407fc83c","shape":{"kind":"members","head":"2292ca6d","members":{"send":"48dd3c00"}}}, "redisJobDriver": {"hash":"264939c0a6b94024","shape":{"kind":"function","head":"49705f2c","params":["?de8c52cd"],"returns":"686a0cac"}} }, diff --git a/scripts/lib/test-byte-ceilings.test.ts b/scripts/lib/test-byte-ceilings.test.ts new file mode 100644 index 000000000..2bdf5b233 --- /dev/null +++ b/scripts/lib/test-byte-ceilings.test.ts @@ -0,0 +1,84 @@ +// A byte ceiling pinned inside a test file (`client-bundle.test.ts`'s `RPC_MINIFIED_BYTES_MAX`, a +// `toBeLessThan(16_186)` in a bundle test) is a ratchet like any `*-pins.ts` row: a raise names its +// reason in the same diff, or `pin-raises` reports `X_PIN_RAISE_UNSTATED`. + +import { describe, expect, test } from 'bun:test'; +import { checkPinRaises } from '../pin-raises'; +import { testBytePins, testBytePinTable } from './test-byte-ceilings'; + +const PATH = 'packages/demo/src/client-bundle.test.ts'; + +const CONST_PIN = (bytes: string, why: string) => + [ + '/**', + ` * measured: 25,281 B (2026-11-19). ${why}`, + ' */', + `const RPC_BYTES_MAX = ${bytes};`, + "test('rpc', async () => {", + ' expect(code.length).toBeLessThanOrEqual(RPC_BYTES_MAX);', + '});', + ].join('\n'); + +const LITERAL_PIN = (bytes: string, comment: string) => + [ + ` // ${comment}`, + " test('stays under 16 kB minified', async () => {", + ' const { bytes } = await build(true);', + ` expect(bytes).toBeLessThan(${bytes});`, + ' expect(reads).toBeLessThanOrEqual(8);', + ' }, 60_000);', + ].join('\n'); + +describe('unit · test-file byte pins', () => { + test('a named ceiling and a literal one are rows; a small count is not a byte pin', () => { + expect(testBytePins(CONST_PIN('25_303', 'why: a'))).toEqual([ + { key: 'RPC_BYTES_MAX', value: 25_303, line: 4 }, + ]); + expect(testBytePins(LITERAL_PIN('16_186', 'why: b'))).toEqual([ + { key: 'stays under 16 kB minified', value: 16_186, line: 2 }, + ]); + }); + + test('a raise with no new why: is X_PIN_RAISE_UNSTATED; one with its own why: is not', () => { + const base = CONST_PIN('25_000', 'why: the transport'); + const silent = testBytePinTable(PATH, CONST_PIN('25_303', 'why: the transport'), base); + expect(checkPinRaises([silent]).map((raise) => [raise.row, raise.was, raise.now])).toEqual([ + ['bytes.RPC_BYTES_MAX', 25_000, 25_303], + ]); + const stated = testBytePinTable(PATH, CONST_PIN('25_303', 'why: +303 B, the stream'), base); + expect(checkPinRaises([stated])).toEqual([]); + }); + + test("a literal pin's why: may sit above its test or inside it", () => { + const base = LITERAL_PIN('16_174', 'measured 16,170. why: the trim'); + const silent = testBytePinTable( + PATH, + LITERAL_PIN('16_186', 'measured 16,170. why: the trim'), + base, + ); + expect(checkPinRaises([silent])).toHaveLength(1); + const stated = testBytePinTable( + PATH, + LITERAL_PIN('16_186', 'why: +12 B, the write rule'), + base, + ); + expect(checkPinRaises([stated])).toEqual([]); + }); + + test('a lowered pin, or one unchanged, asks nothing', () => { + const base = CONST_PIN('25_303', 'why: a'); + expect(checkPinRaises([testBytePinTable(PATH, CONST_PIN('25_000', 'why: a'), base)])).toEqual( + [], + ); + expect(checkPinRaises([testBytePinTable(PATH, base, base)])).toEqual([]); + }); + + test('a file new since the base is a raise from 0 per row, never licensed by an import why:', () => { + const fresh = [ + '// why: Bun ships no path API.', + "import { join } from 'node:path';", + LITERAL_PIN('8_000', 'measured 7,900 B'), + ].join('\n'); + expect(checkPinRaises([testBytePinTable(PATH, fresh, undefined)])).toHaveLength(1); + }); +}); diff --git a/scripts/lib/test-byte-ceilings.ts b/scripts/lib/test-byte-ceilings.ts new file mode 100644 index 000000000..89d04af4b --- /dev/null +++ b/scripts/lib/test-byte-ceilings.ts @@ -0,0 +1,91 @@ +// The byte ceilings pinned inside TEST files — a bundle test's `const RPC_BYTES_MAX = 25_303` or its +// `toBeLessThan(16_186)` — read as one `pin-raises` table per file, so a raise without its own +// `why:` is `X_PIN_RAISE_UNSTATED` exactly as a `scripts/lib/*-pins.ts` row's is. They carried +// `measured:` / `why:` comments by convention alone, and nothing failed when one rose in silence. + +import type { PinTableVersions } from '../pin-raises'; + +/** Every test that measures bytes: a bundle's, or a `*-bytes` encoder's. */ +export const TEST_BYTE_PIN_GLOB = 'packages/*/src/**/*{bundle,bytes}*.test.ts'; + +/** Below this a literal bound is a count (`reads ≤ 8`), not a byte ceiling. */ +const MIN_BYTES = 256; + +const BOUND = /\.toBeLessThan(?:OrEqual)?\(\s*([A-Z][A-Z0-9_]*|\d[\d_]*)\s*\)/g; +const TEST_CALL = /\btest(?:\.\w+)?\(\s*(['"`])((?:(?!\1)[^\\]|\\.)*)\1/g; + +export interface TestBytePin { + /** The constant's name, or the title of the test the literal sits in. */ + readonly key: string; + readonly value: number; + /** The `const` line, or the enclosing `test(` line — where its `why:` is read from. */ + readonly line: number; +} + +const lineAt = (source: string, index: number): number => source.slice(0, index).split('\n').length; +const numberOf = (text: string): number => Number(text.replaceAll('_', '')); + +/** The last `test(''` opened before `index`, or `undefined` at module scope. */ +function enclosingTest(source: string, index: number): { title: string; at: number } | undefined { + let found: { title: string; at: number } | undefined; + for (const match of source.matchAll(TEST_CALL)) { + const at = match.index ?? 0; + if (at > index) break; + found = { title: match[2] ?? '', at }; + } + return found; +} + +export function testBytePins(source: string): readonly TestBytePin[] { + const pins: TestBytePin[] = []; + const seen = new Map<string, number>(); + for (const match of source.matchAll(BOUND)) { + const bound = match[1] ?? ''; + if (/^[A-Z]/.test(bound)) { + const declared = new RegExp(`\\bconst ${bound}\\s*=\\s*(\\d[\\d_]*)\\s*;`).exec(source); + if (declared === null || pins.some((pin) => pin.key === bound)) continue; + const value = numberOf(declared[1] ?? ''); + if (value >= MIN_BYTES) + pins.push({ key: bound, value, line: lineAt(source, declared.index) }); + continue; + } + const value = numberOf(bound); + if (value < MIN_BYTES) continue; + const at = match.index ?? 0; + const test = enclosingTest(source, at); + const title = test?.title ?? `line ${lineAt(source, at)}`; + const nth = (seen.get(title) ?? 0) + 1; + seen.set(title, nth); + pins.push({ + key: nth === 1 ? title : `${title} #${nth}`, + value, + line: lineAt(source, test?.at ?? at), + }); + } + return pins; +} + +const ROW = 'bytes.'; + +const rowsOf = (source: string): ReadonlyMap<string, number> => + new Map(testBytePins(source).map((pin) => [`${ROW}${pin.key}`, pin.value])); + +/** + * One test file as a `pin-raises` table. A file absent at the base has NO rows there — never an + * `undefined` base, which `pin-raises` reads as a new table licensed by any `why:` above its first + * export: a test file has no export, so its import comments' `why:`s would license every pin. + */ +export function testBytePinTable( + path: string, + source: string, + baseSource: string | undefined, +): PinTableVersions { + return { + path, + source, + now: rowsOf(source), + base: baseSource === undefined ? new Map() : rowsOf(baseSource), + ...(baseSource === undefined ? {} : { baseSource }), + line: (text, row) => testBytePins(text).find((pin) => `${ROW}${pin.key}` === row)?.line ?? 0, + }; +} diff --git a/scripts/pin-raises.ts b/scripts/pin-raises.ts index dcaf6c5c3..5e99f4e36 100644 --- a/scripts/pin-raises.ts +++ b/scripts/pin-raises.ts @@ -1,6 +1,7 @@ #!/usr/bin/env bun // A ratchet pin that goes UP needs its reason in the same diff — `budget-raises`' rule, applied to -// every `scripts/lib/*-pins.ts` table and to the ratchets kept inside scripts (`PIN_FILES`). History +// every `scripts/lib/*-pins.ts` table, to the ratchets kept inside scripts (`PIN_FILES`) and to the +// byte ceilings pinned inside bundle and `*-bytes` tests (`lib/test-byte-ceilings.ts`). History // shows why: `secret-compare` went 53 → 63, `node-import-pins` 3 → 12 and `proto-index-pins` 1 → 9 // with nothing on the row saying why, and a ratchet that only rises in silence is a list of // findings nobody is asked to read. @@ -12,6 +13,8 @@ // no base key already a site, its total not above the base's) is one debt under new names, stated // by a `why:` in its header the base's header did not carry. A checkout without `origin/main` is // refused (`X_PIN_BASE_MISSING`). The `--write-pin` placeholder (`lib/pin-edit.ts`) is no `why:`. +// A test file's row is a `const …_MAX = n` or a literal `toBeLessThan(n)`, n ≥ 256; its `why:` sits +// above the constant, or above or inside the test that holds the literal. // // bun run scripts/pin-raises.ts [--json] @@ -28,6 +31,7 @@ import { importPinSource, pinRows } from './lib/pin-rows'; import type { ScriptPinTable } from './lib/pin-tables'; import { PIN_GLOB, SCRIPT_PIN_TABLES, scriptTableRows, tableDeclaration } from './lib/pin-tables'; import { repoRoot } from './lib/run'; +import { TEST_BYTE_PIN_GLOB, testBytePinTable } from './lib/test-byte-ceilings'; const SCRIPT = 'pin-raises'; @@ -233,6 +237,12 @@ export async function readPinTables(root: string, base: string): Promise<PinTabl ...(spec.line === undefined ? {} : { line: spec.line }), }); } + // The byte ceilings pinned inside test files: read as text at both ends, never imported. + for (const path of [...new Bun.Glob(TEST_BYTE_PIN_GLOB).scanSync({ cwd: root })].sort()) { + const source = await Bun.file(`${root}/${path}`).text(); + const table = testBytePinTable(path, source, await textAt(root, base, path)); + if (table.now.size > 0) tables.push(table); + } } finally { await rm(scratch, { recursive: true, force: true }); } diff --git a/scripts/template-codemods-rows.ts b/scripts/template-codemods-rows.ts index b6771f658..2252bc4c0 100644 --- a/scripts/template-codemods-rows.ts +++ b/scripts/template-codemods-rows.ts @@ -15,6 +15,9 @@ const BRIEF_TYPECHECK_WHY = const WORKER_BRIEF_WHY = "the agent briefs now tell a worker with a file set to skip the gate and stop allowing the raw typecheck and lint scripts; an existing app's .claude files are the app's to edit and keep working, so x upgrade leaves them alone"; +const QUERY_VIEW_WHY = + "x g query and x g resource now answer the slice's View; an existing app's reads are its own code and keep answering the row they always did — narrowing them would drop fields a deployed client may read, so x upgrade leaves them alone"; + export const TEMPLATE_CODEMOD_ROWS: readonly TemplateCodemodRow[] = [ ...TEMPLATE_CODEMOD_HISTORY, ...[ @@ -235,4 +238,46 @@ export const TEMPLATE_CODEMOD_ROWS: readonly TemplateCodemodRow[] = [ since: '31.49.0', none: "the specimen's replicator now ships at replicas: 0, as sync and the chart's replicator do; x new writes no replicator service at all, and an app that runs one turned realtime on and configured Postgres for it, so rewriting its replica count would switch a working change feed off", }, + ...[ + 'packages/cli/src/templates/query.ts', + 'packages/cli/src/templates/query-slice.ts', + 'packages/cli/src/templates/resource-page.ts', + 'apps/web/app/post/live/post-list.ts', + 'apps/web/app/post/live/post-list.test.ts', + 'apps/web/app/post/live/post-list.live.test.ts', + 'apps/web/app/posts/page.tsx', + ].map((template) => ({ template, since: '31.49.0', none: QUERY_VIEW_WHY })), + ...['packages/cli/src/templates/scaffold-repo.ts', 'package.json'].map((template) => ({ + template, + since: '31.49.0', + none: 'new apps declare @ultimat3/realtime at the framework pin; an existing app that imports it adds it once with bun add --exact at its @ultimat3/core pin, and one that does not never needs it, so x upgrade leaves the dependency set alone', + })), + ...[ + 'packages/cli/src/templates/shapes/realtime.ts', + 'packages/cli/src/templates/shapes/offline.ts', + ].map((template) => ({ + template, + since: '31.49.0', + none: "the @ultimat3/realtime dependency these shapes added moved into every scaffold's package.json; x new writes the same package.json for both shapes", + })), + { + template: 'packages/cli/src/templates/scaffold-container-compose.ts', + since: '31.49.0', + none: "new apps pin the compose database image by digest; an existing app's docker-compose.yml runs a live database on the tag it chose, and moving that image is a backup-first operation the app decides, so x upgrade leaves it alone", + }, + { + template: 'packages/cli/src/templates/scaffold-test-services.ts', + since: '31.49.0', + none: "x new now keys the test services' ports and compose project by the checkout root as well as the name; an existing app's docker-compose.test.yml and .env.test keep working as written, and renaming its project would orphan the containers it already runs, so x upgrade leaves them alone", + }, + ...[ + 'packages/cli/src/templates/sign-in-action-tests.ts', + 'packages/cli/src/templates/sign-in-oidc-mfa.ts', + 'packages/cli/src/templates/sign-in-oidc.ts', + 'packages/cli/src/templates/sign-in-password.ts', + ].map((template) => ({ + template, + since: '31.49.0', + none: "x g sign-in --oidc now also writes the second-factor leg and passes mfaPath; a sign-in an app already generated is its own code and keeps signing in as it did, and the password shape's files render byte-identical, so x upgrade leaves them alone", + })), ]; diff --git a/scripts/template-codemods.lock.json b/scripts/template-codemods.lock.json index 4988084e8..f25a8ca77 100644 --- a/scripts/template-codemods.lock.json +++ b/scripts/template-codemods.lock.json @@ -80,9 +80,9 @@ "agent:apps/web/app/post/jobs/reindex-post.job.test.ts": "cc5df6fb25b1a190", "agent:apps/web/app/post/jobs/reindex-post.test.ts": "745068c1c7ff9909", "agent:apps/web/app/post/jobs/reindex-post.ts": "753f18ce0a94506d", - "agent:apps/web/app/post/live/post-list.live.test.ts": "664fd0dc72555724", - "agent:apps/web/app/post/live/post-list.test.ts": "f7cb0e156fd2876a", - "agent:apps/web/app/post/live/post-list.ts": "fb2ad44b21cbf775", + "agent:apps/web/app/post/live/post-list.live.test.ts": "c2469780d8b2aaa9", + "agent:apps/web/app/post/live/post-list.test.ts": "b2c50899d4ac66c3", + "agent:apps/web/app/post/live/post-list.ts": "d6a04385df9175fc", "agent:apps/web/app/post/policy.test.ts": "95e6750645dd6927", "agent:apps/web/app/post/policy.ts": "4fd2fb9971b1d459", "agent:apps/web/app/post/post-form.island.states.ts": "28a07878a6f06356", @@ -100,7 +100,7 @@ "agent:apps/web/app/posts/page.e2e.test.ts": "820309c4ad1c0137", "agent:apps/web/app/posts/page.module.scss": "5c16e9f576e40881", "agent:apps/web/app/posts/page.test.ts": "c60685252f58f54d", - "agent:apps/web/app/posts/page.tsx": "4a97126ad626863d", + "agent:apps/web/app/posts/page.tsx": "e7372d43cf2d7d1c", "agent:apps/web/exercise.test.ts": "59e127aa99f4169a", "agent:apps/web/exercise.ts": "3778f775150b6194", "agent:apps/web/mcp.test.ts": "e77e883b35ccd668", @@ -148,7 +148,7 @@ "agent:docker/Dockerfile.dockerignore": "4c340f4f472b6bd0", "agent:docker/README.md": "dc36b1c9f98f3fed", "agent:docker/docker-compose.dev.yml": "3ec93e58a98444cc", - "agent:docker/docker-compose.prod.yml": "cb007a881d876b2e", + "agent:docker/docker-compose.prod.yml": "d09afc95296c7a74", "agent:docker/docker-compose.test.yml": "fdb49595c1f1f137", "agent:docker/helm/Chart.yaml": "095ddd6ede78a561", "agent:docker/helm/dashboards/ultimate-app.json": "538b25e4cb1ede81", @@ -166,7 +166,7 @@ "agent:docker/helm/values.yaml": "e8b55a79285cd604", "agent:docker/test-services.env": "cf3749be580cb6ad", "agent:guards/shipped.json": "55e6068bdd3bfc6c", - "agent:package.json": "37153521a655fb35", + "agent:package.json": "48f871ee9c7a60fb", "agent:packages/db/.gitattributes": "9739e256c86c62b8", "agent:packages/db/CLAUDE.md": "fc372217e5605c37", "agent:packages/db/README.md": "9dbc43c831a88756", @@ -271,9 +271,9 @@ "api:apps/web/app/post/jobs/reindex-post.job.test.ts": "cc5df6fb25b1a190", "api:apps/web/app/post/jobs/reindex-post.test.ts": "745068c1c7ff9909", "api:apps/web/app/post/jobs/reindex-post.ts": "753f18ce0a94506d", - "api:apps/web/app/post/live/post-list.live.test.ts": "664fd0dc72555724", - "api:apps/web/app/post/live/post-list.test.ts": "f7cb0e156fd2876a", - "api:apps/web/app/post/live/post-list.ts": "fb2ad44b21cbf775", + "api:apps/web/app/post/live/post-list.live.test.ts": "c2469780d8b2aaa9", + "api:apps/web/app/post/live/post-list.test.ts": "b2c50899d4ac66c3", + "api:apps/web/app/post/live/post-list.ts": "d6a04385df9175fc", "api:apps/web/app/post/policy.test.ts": "95e6750645dd6927", "api:apps/web/app/post/policy.ts": "4fd2fb9971b1d459", "api:apps/web/app/post/repo.test.ts": "3151e4135521c414", @@ -315,7 +315,7 @@ "api:docker/Dockerfile.dockerignore": "4c340f4f472b6bd0", "api:docker/README.md": "dc36b1c9f98f3fed", "api:docker/docker-compose.dev.yml": "3ec93e58a98444cc", - "api:docker/docker-compose.prod.yml": "cb007a881d876b2e", + "api:docker/docker-compose.prod.yml": "d09afc95296c7a74", "api:docker/docker-compose.test.yml": "fdb49595c1f1f137", "api:docker/helm/Chart.yaml": "095ddd6ede78a561", "api:docker/helm/dashboards/ultimate-app.json": "538b25e4cb1ede81", @@ -333,7 +333,7 @@ "api:docker/helm/values.yaml": "e8b55a79285cd604", "api:docker/test-services.env": "cf3749be580cb6ad", "api:guards/shipped.json": "55e6068bdd3bfc6c", - "api:package.json": "0404b39490d87cbd", + "api:package.json": "624255477e65bcd9", "api:packages/db/.gitattributes": "9739e256c86c62b8", "api:packages/db/CLAUDE.md": "fc372217e5605c37", "api:packages/db/README.md": "9dbc43c831a88756", @@ -473,7 +473,7 @@ "bare:docker/Dockerfile.dockerignore": "4c340f4f472b6bd0", "bare:docker/README.md": "dc36b1c9f98f3fed", "bare:docker/docker-compose.dev.yml": "3ec93e58a98444cc", - "bare:docker/docker-compose.prod.yml": "cb007a881d876b2e", + "bare:docker/docker-compose.prod.yml": "d09afc95296c7a74", "bare:docker/docker-compose.test.yml": "fdb49595c1f1f137", "bare:docker/helm/Chart.yaml": "095ddd6ede78a561", "bare:docker/helm/dashboards/ultimate-app.json": "538b25e4cb1ede81", @@ -491,7 +491,7 @@ "bare:docker/helm/values.yaml": "e8b55a79285cd604", "bare:docker/test-services.env": "cf3749be580cb6ad", "bare:guards/shipped.json": "55e6068bdd3bfc6c", - "bare:package.json": "0404b39490d87cbd", + "bare:package.json": "624255477e65bcd9", "bare:packages/db/.gitattributes": "9739e256c86c62b8", "bare:packages/db/CLAUDE.md": "fc372217e5605c37", "bare:packages/db/README.md": "9dbc43c831a88756", @@ -633,7 +633,7 @@ "blog:docker/Dockerfile.dockerignore": "4c340f4f472b6bd0", "blog:docker/README.md": "dc36b1c9f98f3fed", "blog:docker/docker-compose.dev.yml": "3ec93e58a98444cc", - "blog:docker/docker-compose.prod.yml": "cb007a881d876b2e", + "blog:docker/docker-compose.prod.yml": "d09afc95296c7a74", "blog:docker/docker-compose.test.yml": "fdb49595c1f1f137", "blog:docker/helm/Chart.yaml": "095ddd6ede78a561", "blog:docker/helm/dashboards/ultimate-app.json": "538b25e4cb1ede81", @@ -651,7 +651,7 @@ "blog:docker/helm/values.yaml": "e8b55a79285cd604", "blog:docker/test-services.env": "cf3749be580cb6ad", "blog:guards/shipped.json": "55e6068bdd3bfc6c", - "blog:package.json": "0404b39490d87cbd", + "blog:package.json": "624255477e65bcd9", "blog:packages/db/.gitattributes": "9739e256c86c62b8", "blog:packages/db/CLAUDE.md": "fc372217e5605c37", "blog:packages/db/README.md": "9dbc43c831a88756", @@ -790,7 +790,7 @@ "content:docker/Dockerfile.dockerignore": "4c340f4f472b6bd0", "content:docker/README.md": "dc36b1c9f98f3fed", "content:docker/docker-compose.dev.yml": "3ec93e58a98444cc", - "content:docker/docker-compose.prod.yml": "cb007a881d876b2e", + "content:docker/docker-compose.prod.yml": "d09afc95296c7a74", "content:docker/docker-compose.test.yml": "fdb49595c1f1f137", "content:docker/helm/Chart.yaml": "095ddd6ede78a561", "content:docker/helm/dashboards/ultimate-app.json": "538b25e4cb1ede81", @@ -808,7 +808,7 @@ "content:docker/helm/values.yaml": "e8b55a79285cd604", "content:docker/test-services.env": "cf3749be580cb6ad", "content:guards/shipped.json": "55e6068bdd3bfc6c", - "content:package.json": "0404b39490d87cbd", + "content:package.json": "624255477e65bcd9", "content:packages/db/.gitattributes": "9739e256c86c62b8", "content:packages/db/CLAUDE.md": "fc372217e5605c37", "content:packages/db/README.md": "9dbc43c831a88756", @@ -914,9 +914,9 @@ "dashboard:apps/web/app/post/jobs/reindex-post.job.test.ts": "cc5df6fb25b1a190", "dashboard:apps/web/app/post/jobs/reindex-post.test.ts": "745068c1c7ff9909", "dashboard:apps/web/app/post/jobs/reindex-post.ts": "753f18ce0a94506d", - "dashboard:apps/web/app/post/live/post-list.live.test.ts": "664fd0dc72555724", - "dashboard:apps/web/app/post/live/post-list.test.ts": "f7cb0e156fd2876a", - "dashboard:apps/web/app/post/live/post-list.ts": "fb2ad44b21cbf775", + "dashboard:apps/web/app/post/live/post-list.live.test.ts": "c2469780d8b2aaa9", + "dashboard:apps/web/app/post/live/post-list.test.ts": "b2c50899d4ac66c3", + "dashboard:apps/web/app/post/live/post-list.ts": "d6a04385df9175fc", "dashboard:apps/web/app/post/policy.test.ts": "95e6750645dd6927", "dashboard:apps/web/app/post/policy.ts": "4fd2fb9971b1d459", "dashboard:apps/web/app/post/post-form.island.states.ts": "28a07878a6f06356", @@ -939,7 +939,7 @@ "dashboard:apps/web/app/posts/page.e2e.test.ts": "820309c4ad1c0137", "dashboard:apps/web/app/posts/page.module.scss": "5c16e9f576e40881", "dashboard:apps/web/app/posts/page.test.ts": "c60685252f58f54d", - "dashboard:apps/web/app/posts/page.tsx": "ad59dfc52c853c55", + "dashboard:apps/web/app/posts/page.tsx": "199de380097e89ea", "dashboard:apps/web/exercise.test.ts": "59e127aa99f4169a", "dashboard:apps/web/exercise.ts": "f0a745d3215fe64c", "dashboard:apps/web/mcp.test.ts": "e77e883b35ccd668", @@ -987,7 +987,7 @@ "dashboard:docker/Dockerfile.dockerignore": "4c340f4f472b6bd0", "dashboard:docker/README.md": "dc36b1c9f98f3fed", "dashboard:docker/docker-compose.dev.yml": "3ec93e58a98444cc", - "dashboard:docker/docker-compose.prod.yml": "cb007a881d876b2e", + "dashboard:docker/docker-compose.prod.yml": "d09afc95296c7a74", "dashboard:docker/docker-compose.test.yml": "fdb49595c1f1f137", "dashboard:docker/helm/Chart.yaml": "095ddd6ede78a561", "dashboard:docker/helm/dashboards/ultimate-app.json": "538b25e4cb1ede81", @@ -1005,7 +1005,7 @@ "dashboard:docker/helm/values.yaml": "e8b55a79285cd604", "dashboard:docker/test-services.env": "cf3749be580cb6ad", "dashboard:guards/shipped.json": "55e6068bdd3bfc6c", - "dashboard:package.json": "0404b39490d87cbd", + "dashboard:package.json": "624255477e65bcd9", "dashboard:packages/db/.gitattributes": "9739e256c86c62b8", "dashboard:packages/db/CLAUDE.md": "fc372217e5605c37", "dashboard:packages/db/README.md": "9dbc43c831a88756", @@ -1110,9 +1110,9 @@ "example:apps/web/app/post/jobs/reindex-post.job.test.ts": "cc5df6fb25b1a190", "example:apps/web/app/post/jobs/reindex-post.test.ts": "745068c1c7ff9909", "example:apps/web/app/post/jobs/reindex-post.ts": "753f18ce0a94506d", - "example:apps/web/app/post/live/post-list.live.test.ts": "664fd0dc72555724", - "example:apps/web/app/post/live/post-list.test.ts": "f7cb0e156fd2876a", - "example:apps/web/app/post/live/post-list.ts": "fb2ad44b21cbf775", + "example:apps/web/app/post/live/post-list.live.test.ts": "c2469780d8b2aaa9", + "example:apps/web/app/post/live/post-list.test.ts": "b2c50899d4ac66c3", + "example:apps/web/app/post/live/post-list.ts": "d6a04385df9175fc", "example:apps/web/app/post/policy.test.ts": "95e6750645dd6927", "example:apps/web/app/post/policy.ts": "4fd2fb9971b1d459", "example:apps/web/app/post/post-form.island.states.ts": "28a07878a6f06356", @@ -1130,7 +1130,7 @@ "example:apps/web/app/posts/page.e2e.test.ts": "820309c4ad1c0137", "example:apps/web/app/posts/page.module.scss": "5c16e9f576e40881", "example:apps/web/app/posts/page.test.ts": "c60685252f58f54d", - "example:apps/web/app/posts/page.tsx": "4a97126ad626863d", + "example:apps/web/app/posts/page.tsx": "e7372d43cf2d7d1c", "example:apps/web/exercise.test.ts": "59e127aa99f4169a", "example:apps/web/exercise.ts": "f0a745d3215fe64c", "example:apps/web/mcp.test.ts": "e77e883b35ccd668", @@ -1178,7 +1178,7 @@ "example:docker/Dockerfile.dockerignore": "4c340f4f472b6bd0", "example:docker/README.md": "dc36b1c9f98f3fed", "example:docker/docker-compose.dev.yml": "3ec93e58a98444cc", - "example:docker/docker-compose.prod.yml": "cb007a881d876b2e", + "example:docker/docker-compose.prod.yml": "d09afc95296c7a74", "example:docker/docker-compose.test.yml": "fdb49595c1f1f137", "example:docker/helm/Chart.yaml": "095ddd6ede78a561", "example:docker/helm/dashboards/ultimate-app.json": "538b25e4cb1ede81", @@ -1196,7 +1196,7 @@ "example:docker/helm/values.yaml": "e8b55a79285cd604", "example:docker/test-services.env": "cf3749be580cb6ad", "example:guards/shipped.json": "55e6068bdd3bfc6c", - "example:package.json": "0404b39490d87cbd", + "example:package.json": "624255477e65bcd9", "example:packages/db/.gitattributes": "9739e256c86c62b8", "example:packages/db/CLAUDE.md": "fc372217e5605c37", "example:packages/db/README.md": "9dbc43c831a88756", @@ -1301,9 +1301,9 @@ "offline:apps/web/app/post/jobs/reindex-post.job.test.ts": "cc5df6fb25b1a190", "offline:apps/web/app/post/jobs/reindex-post.test.ts": "745068c1c7ff9909", "offline:apps/web/app/post/jobs/reindex-post.ts": "753f18ce0a94506d", - "offline:apps/web/app/post/live/post-list.live.test.ts": "664fd0dc72555724", - "offline:apps/web/app/post/live/post-list.test.ts": "f7cb0e156fd2876a", - "offline:apps/web/app/post/live/post-list.ts": "fb2ad44b21cbf775", + "offline:apps/web/app/post/live/post-list.live.test.ts": "c2469780d8b2aaa9", + "offline:apps/web/app/post/live/post-list.test.ts": "b2c50899d4ac66c3", + "offline:apps/web/app/post/live/post-list.ts": "d6a04385df9175fc", "offline:apps/web/app/post/policy.test.ts": "95e6750645dd6927", "offline:apps/web/app/post/policy.ts": "4fd2fb9971b1d459", "offline:apps/web/app/post/post-form.island.states.ts": "86f0400ed33935fc", @@ -1322,7 +1322,7 @@ "offline:apps/web/app/posts/page.e2e.test.ts": "820309c4ad1c0137", "offline:apps/web/app/posts/page.module.scss": "5c16e9f576e40881", "offline:apps/web/app/posts/page.test.ts": "56a39b719f103861", - "offline:apps/web/app/posts/page.tsx": "59e36fd365fc2d7f", + "offline:apps/web/app/posts/page.tsx": "57e1069655e74337", "offline:apps/web/exercise.test.ts": "59e127aa99f4169a", "offline:apps/web/exercise.ts": "f0a745d3215fe64c", "offline:apps/web/mcp.test.ts": "e77e883b35ccd668", @@ -1371,7 +1371,7 @@ "offline:docker/Dockerfile.dockerignore": "4c340f4f472b6bd0", "offline:docker/README.md": "dc36b1c9f98f3fed", "offline:docker/docker-compose.dev.yml": "3ec93e58a98444cc", - "offline:docker/docker-compose.prod.yml": "cb007a881d876b2e", + "offline:docker/docker-compose.prod.yml": "d09afc95296c7a74", "offline:docker/docker-compose.test.yml": "fdb49595c1f1f137", "offline:docker/helm/Chart.yaml": "095ddd6ede78a561", "offline:docker/helm/dashboards/ultimate-app.json": "538b25e4cb1ede81", @@ -1502,9 +1502,9 @@ "realtime:apps/web/app/post/jobs/reindex-post.job.test.ts": "cc5df6fb25b1a190", "realtime:apps/web/app/post/jobs/reindex-post.test.ts": "745068c1c7ff9909", "realtime:apps/web/app/post/jobs/reindex-post.ts": "753f18ce0a94506d", - "realtime:apps/web/app/post/live/post-list.live.test.ts": "664fd0dc72555724", - "realtime:apps/web/app/post/live/post-list.test.ts": "f7cb0e156fd2876a", - "realtime:apps/web/app/post/live/post-list.ts": "fb2ad44b21cbf775", + "realtime:apps/web/app/post/live/post-list.live.test.ts": "c2469780d8b2aaa9", + "realtime:apps/web/app/post/live/post-list.test.ts": "b2c50899d4ac66c3", + "realtime:apps/web/app/post/live/post-list.ts": "d6a04385df9175fc", "realtime:apps/web/app/post/policy.test.ts": "95e6750645dd6927", "realtime:apps/web/app/post/policy.ts": "c3d9cd0550533018", "realtime:apps/web/app/post/post-form.island.states.ts": "28a07878a6f06356", @@ -1524,7 +1524,7 @@ "realtime:apps/web/app/posts/page.e2e.test.ts": "820309c4ad1c0137", "realtime:apps/web/app/posts/page.module.scss": "5c16e9f576e40881", "realtime:apps/web/app/posts/page.test.ts": "c60685252f58f54d", - "realtime:apps/web/app/posts/page.tsx": "4a97126ad626863d", + "realtime:apps/web/app/posts/page.tsx": "e7372d43cf2d7d1c", "realtime:apps/web/exercise.test.ts": "59e127aa99f4169a", "realtime:apps/web/exercise.ts": "0e3f90cf81650ccf", "realtime:apps/web/mcp.test.ts": "e77e883b35ccd668", @@ -1572,7 +1572,7 @@ "realtime:docker/Dockerfile.dockerignore": "4c340f4f472b6bd0", "realtime:docker/README.md": "dc36b1c9f98f3fed", "realtime:docker/docker-compose.dev.yml": "3ec93e58a98444cc", - "realtime:docker/docker-compose.prod.yml": "cb007a881d876b2e", + "realtime:docker/docker-compose.prod.yml": "d09afc95296c7a74", "realtime:docker/docker-compose.test.yml": "fdb49595c1f1f137", "realtime:docker/helm/Chart.yaml": "095ddd6ede78a561", "realtime:docker/helm/dashboards/ultimate-app.json": "538b25e4cb1ede81", @@ -1705,9 +1705,9 @@ "saas:apps/web/app/post/jobs/reindex-post.job.test.ts": "cc5df6fb25b1a190", "saas:apps/web/app/post/jobs/reindex-post.test.ts": "745068c1c7ff9909", "saas:apps/web/app/post/jobs/reindex-post.ts": "753f18ce0a94506d", - "saas:apps/web/app/post/live/post-list.live.test.ts": "664fd0dc72555724", - "saas:apps/web/app/post/live/post-list.test.ts": "f7cb0e156fd2876a", - "saas:apps/web/app/post/live/post-list.ts": "fb2ad44b21cbf775", + "saas:apps/web/app/post/live/post-list.live.test.ts": "c2469780d8b2aaa9", + "saas:apps/web/app/post/live/post-list.test.ts": "b2c50899d4ac66c3", + "saas:apps/web/app/post/live/post-list.ts": "d6a04385df9175fc", "saas:apps/web/app/post/policy.test.ts": "95e6750645dd6927", "saas:apps/web/app/post/policy.ts": "4fd2fb9971b1d459", "saas:apps/web/app/post/post-form.island.states.ts": "28a07878a6f06356", @@ -1725,7 +1725,7 @@ "saas:apps/web/app/posts/page.e2e.test.ts": "820309c4ad1c0137", "saas:apps/web/app/posts/page.module.scss": "5c16e9f576e40881", "saas:apps/web/app/posts/page.test.ts": "c60685252f58f54d", - "saas:apps/web/app/posts/page.tsx": "4a97126ad626863d", + "saas:apps/web/app/posts/page.tsx": "e7372d43cf2d7d1c", "saas:apps/web/exercise.test.ts": "59e127aa99f4169a", "saas:apps/web/exercise.ts": "c5fd1ddf0c0e42d4", "saas:apps/web/mcp.test.ts": "e77e883b35ccd668", @@ -1773,7 +1773,7 @@ "saas:docker/Dockerfile.dockerignore": "4c340f4f472b6bd0", "saas:docker/README.md": "dc36b1c9f98f3fed", "saas:docker/docker-compose.dev.yml": "3ec93e58a98444cc", - "saas:docker/docker-compose.prod.yml": "cb007a881d876b2e", + "saas:docker/docker-compose.prod.yml": "d09afc95296c7a74", "saas:docker/docker-compose.test.yml": "fdb49595c1f1f137", "saas:docker/helm/Chart.yaml": "095ddd6ede78a561", "saas:docker/helm/dashboards/ultimate-app.json": "538b25e4cb1ede81", @@ -1791,7 +1791,7 @@ "saas:docker/helm/values.yaml": "e8b55a79285cd604", "saas:docker/test-services.env": "cf3749be580cb6ad", "saas:guards/shipped.json": "55e6068bdd3bfc6c", - "saas:package.json": "cee2022743d84b5c", + "saas:package.json": "ca45b7eebec8a932", "saas:packages/db/.gitattributes": "9739e256c86c62b8", "saas:packages/db/CLAUDE.md": "fc372217e5605c37", "saas:packages/db/README.md": "9dbc43c831a88756", diff --git a/wiki/CLI-Reference.md b/wiki/CLI-Reference.md index a997c5144..0e9ab6fea 100644 --- a/wiki/CLI-Reference.md +++ b/wiki/CLI-Reference.md @@ -562,6 +562,7 @@ Two more facts about the set, both `As of 2026-08`: | `--allow-destructive` | boolean | `false` | let `gen` emit a DROP whose `down` cannot restore the rows. `X_MIGRATION_IRREVERSIBLE`'s own `fix:` line names it | | `--drop-redundant` | boolean | `false` | `gen`: leave out of the diff each implicit index (a column's own, from `.references()` or `.index()`) that another index, the primary key or a unique invariant already leads with, so the migration drops it `concurrently` in a non-transactional step you review. Never a default; once dropped, a plain `x db gen` does not rebuild it. A table with no migration yet keeps every index. `x doctor` lists what it would drop (`data.redundantIndexes`), `As of 2026-11-14` | | `--merge-fork` | boolean | `false` | `gen`: the fix `X_MIGRATION_FORKED` prints. Rewrites the newest `.snapshot.json` to what the merged chain builds, then continues as any `gen`. Changes no SQL and deletes no migration. `--json`: `data.outcome` is `fork-merged` when no migration was needed, `data.forkRepairs` the objects corrected. Two migrations creating one object are still refused ([Two branches, one chain](Migrations-And-Backfills#two-branches-one-chain--x_migration_forked)) | +| `--steps` | integer ≥ 1 | `1` | `rollback` only: how many applied migrations to reverse, most recently applied first. `0`, a fraction or a word is `X_CLI_BAD_FLAG` before anything opens | | `--list` | boolean | `false` | `backfill`: print the ledger | | `--pending` | boolean | `false` | `backfill`: declared minus completed, judged in this `ULTIMATE_ENV`. Non-zero exit when anything is unswept | | `--all` | boolean | `false` | `backfill`: every pending sweep, isolated per name | diff --git a/wiki/Error-Codes-cli.md b/wiki/Error-Codes-cli.md index 7a08f01ac..3aef98adb 100644 --- a/wiki/Error-Codes-cli.md +++ b/wiki/Error-Codes-cli.md @@ -48,7 +48,7 @@ Part of [Error codes](Error-Codes): every code `@ultimat3/cli` registers. `x err | `X_CLI_BAD_FLAG` | flag or positional rejected | unknown flag, a bad value (`--port abc`, `--workers 4.9` — refused, never coerced), a required positional left out, or a mandatory-subcommand command called bare. A missing positional says so and names it, rather than inventing a flag that does not exist. A **well-formed** argv whose answer is still no is not this code — a `dev`-tier seed refused against production is `X_SEED_ENVIRONMENT`, because a flag code says "you typed it wrong" and sends the reader to `x help`, which is the wrong instruction there | `x help <command>`. **Use that form and not `--help` on `db` and `mcp`** — they declare no default subcommand, and the subcommand is resolved *before* the flag loop, so `x db --help` raises this same error again. Its `fix:` said exactly that until 2026-08 | | `X_CLI_FLAG_UNREAD` | a command declares a flag no code reads | the CLI's own declarations held to each other: a `FlagSpec` the parser accepts and no file under `packages/cli/src` reads is a promise `x help` makes with nothing behind it. `x deploy --critical` said *"forces clients to reload"* and reached no reader outside the plan JSON. The four global flags are excluded — the parser owns them — and any bare `'name'` literal outside a `name:`/`short:` spec field counts as a read, so a flag echoed into `--json` still counts | `bun test packages/cli/src/flag-reads.test.ts` — the finding names the flag and the file to read it in | | `X_CLI_UNEXPECTED` | the CLI itself failed | a bug, or a broken environment | `x doctor --json` and attach it to an issue | -| `X_CLI_UNKNOWN_COMMAND` | not a command | a typo | `x help` — the suggestion is in `fix`: the nearest registered command or subcommand (`x db rollbak` → `x db rollback`), a near-miss generator with the name you typed (`x g acton foo` → `x g action foo`), and for a subcommand near nothing that command's own page, `x help <command>` (`As of 2026-11-19`) | +| `X_CLI_UNKNOWN_COMMAND` | not a command | a typo. The suggestion is computed from what is registered: the nearest command or subcommand, a near-miss generator completed with the name and `--feature` you typed, and for a subcommand near nothing that command's own page (`As of 2026-11-19`) | `x help` — the suggestion is in `fix`; for a subcommand near nothing it is `x help <command>` | | `X_COVERAGE_BELOW_FLOOR` | the unit suite covers less of the app than x.verify.json states | Line or function coverage of the app's own source — every `.ts`/`.tsx` under `apps/` and `packages/`, a file no unit test loads counted at 0% — is under the `coverage` floor in `x.verify.json`. A test was deleted, or source landed without one. The finding names the measured and required numbers and the ten files that lose the most lines | `x verify --only unit --json` — names the ten files losing the most lines; cover the worst with a test beside it | | `X_COVERAGE_FLOOR_STALE` | the app now covers more than the floor in x.verify.json states | A floor under 95 is more than 1.5 points below what the unit suite measures. The floor only rises: left alone it would let the next regression fall back to a number the app left behind | `x verify --only unit --json` — the finding carries the measured numbers; raise "coverage" in x.verify.json to them | | `X_COVERAGE_FLOOR_UNSTATED` | x.verify.json states no coverage floor, or one under 95 with no reason | `x.verify.json` has no `coverage: { lines, funcs }`, so the gate has no floor to hold the unit suite to — an app is never held to a default it did not write. Also raised for a stated floor under 95 on either number that carries no `why` | `x verify --only unit --json` — the finding carries the measured numbers and the exact "coverage" line to add to x.verify.json | diff --git a/wiki/Scheduled-Tasks.md b/wiki/Scheduled-Tasks.md index be6e2e0da..110317b4e 100644 --- a/wiki/Scheduled-Tasks.md +++ b/wiki/Scheduled-Tasks.md @@ -84,6 +84,8 @@ export const digestTask = sendDigest.schedule; Hand the job's module to `defineApi({ jobs })`; the task registers with it — it needs no `tasks` entry. A task that fires several jobs, or a job other code also enqueues, stays a `task()` beside its jobs. +**One job per org, from a schedule**: the schedule belongs to no org (`tenant: 'none'`), the org list is read inside `crossTenant()` as a service actor, and each child job is tenant-scoped and runs as its org — the whole pattern, with a test that runs it, is `x docs 'jobs.README#one-job-per-org-from-a-schedule'`. Fire it now in dev with `x tasks run <name>.schedule`. + ## The fluent surface Every projection is a method on the task — `nightlyDigest.enqueue()`, never `runTask(nightlyDigest)` — and every declared field is lifted onto it. A task has no `.def`. diff --git a/wiki/Upgrading.md b/wiki/Upgrading.md index da97c6d86..98d6ed23c 100644 --- a/wiki/Upgrading.md +++ b/wiki/Upgrading.md @@ -343,6 +343,12 @@ A setter still on a package's `.` barrel is `X_ADAPTER_PORT_INCOMPLETE` on the ` | OAuth (**31.49.0**): `/oauth/register` takes at most 10 `redirect_uris` of 2,048 characters, self-registered clients get `d_` ids that `purge()` reaps once idle and unnamed, limits are per IPv6 /64; `mcpOAuthClient().begin()` refuses a non-loopback `http:` server or issuer, and `refresh()` answers the token it was passed when the server sends none | a hand-written `AuthServerStore`: re-run `authServerStoreConformance` — its `purge` must reap those clients. An internal MCP server on plain `http:` by hostname: serve it over TLS. Consent pages: show `client.host` beside `client.name` | | a push service's 401/403 keeps the subscription (**31.49.0**), refused by code and logged; a served-stale `isr` answer is `public, max-age=0, s-maxage=0` | after a real VAPID key rotation, old rows stay until each browser re-subscribes or the row expires. Behind a CDN: one extra origin request per stale serve, no stale window at the edge | | AI and tests (**31.49.0**): `postgresVectorStore()` lexical search matches any word and reads no websearch syntax; `defineEval` refuses a `NaN`, infinite or negative `tolerance` (`X_INVARIANT`); `ULTIMATE_EVAL_RECORD=0` / `false` / `no` / `off` gates; `toBeWithinBudget` refuses a non-finite limit (`X_TEST_NUMBER_EXPECTED`); `chunkDocument` cuts a little earlier | drop `"…"` / `-word` from vector queries; `grep -rn 'tolerance\|toBeWithinBudget' apps packages` — a number ≥ 0, a finite limit. Re-indexing may change chunk ids: re-run `indexDocument` for every document, not a subset | +| `x env check` with no `ULTIMATE_ENV`, `NODE_ENV` or `CI` set checks as **development** (**31.49.0**), as `x dev` runs there; it checked as production. Under `CI`, or with either name set, nothing changes | a deploy script running a bare `x env check` on a host that sets none of the three: `ULTIMATE_ENV=production x env check` | +| `x test <type>` exits 1 with `X_TEST_FAILED` when every test it selected skipped itself (**31.49.0**), where it exited 0 having checked nothing; `x verify` is unaffected | a script calling `x test live` (or any type) without the services: `docker compose -f docker/docker-compose.test.yml up -d --wait && set -a && . docker/test-services.env && set +a` first, or drop the call | +| `x dev` is `✗ dev ready` while migrations on disk are ahead of its database (`X_APP_MIGRATIONS_UNAPPLIED`) or an applied one was edited (**31.49.0**), and a schema finding no longer restarts it; on the embedded database `x db gen` refuses an edited applied migration (`X_MIGRATION_CONFLICT`, nothing written) | a workflow starting `x dev` before its first migrate: `x db migrate`. A script waiting for a fresh `✓` banner after `x db gen`: read `/_x` (or `x dev --json --once`). An edited applied migration: restore it (`git checkout <rev> -- packages/db/migrations/<id>.sql`), or rebuild the dev database with `x stop --json && x db reset` | +| `x policy explain --json` (**31.49.0**): a row whose predicate reads request input it was not given is `verdict: "needs-input"`, `allowed: null`, counted in `data.pending` — it was `allowed: false` | a script reading `!allowed` as denied: `verdict === "deny"`. To decide such a row: `x policy explain <subject> --input '<json>'` | +| fix text changed, codes unchanged (**31.49.0**): `X_ENV_MISSING` is the line to add to the file the environment loads; `X_CATALOG_MISSING_KEYS`'s comment half; `X_TEST_FAILED` reruns the first failing file; on the embedded development database `X_MIGRATION_CONFLICT` and `X_MIGRATION_ROLLBACK_DESTRUCTIVE` lead with `x stop --json && x db reset` | anything matching those strings exactly: `grep -rn 'x env check\|as ⟦key⟧' <your scripts>` and match the new text | +| new scaffolds (**31.49.0**): `docker/docker-compose.test.yml` is named `<app>-test-<hash of the directory>` with ports picked per directory, and `package.json` declares `@ultimat3/realtime` | nothing; an existing app keeps its `name:` and dependency set. One importing `@ultimat3/realtime` without declaring it: `bun add --exact @ultimat3/realtime@$(bun -p "require('./package.json').dependencies['@ultimat3/core']")`. Sharing a test stack with a same-named app: its own `name:` and ports in the compose file and `docker/test-services.env` | ## 29.x → 30.0.0, entry by entry From 682e721df0766a03c612a54ce97b46e803986253 Mon Sep 17 00:00:00 2001 From: sebi <gore.sebyx@yahoo.com> Date: Thu, 19 Nov 2026 13:35:16 -0500 Subject: [PATCH 6/9] wip: r9 verification fixes --- packages/action/README.md | 16 +- packages/action/src/adapter.ts | 1 + packages/action/src/audit-batch.test.ts | 27 ++++ packages/action/src/audit-postgres.test.ts | 29 ++++ packages/action/src/audit-postgres.ts | 14 +- packages/action/src/http-dates.test.ts | 117 +++++++++++++- packages/action/src/http-stream.test.ts | 23 ++- packages/action/src/http-stream.ts | 55 ++----- packages/action/src/http.ts | 4 +- packages/action/src/record-wire.ts | 10 +- packages/action/src/tx-scope.ts | 12 +- packages/ai/CLAUDE.md | 2 +- packages/ai/README.md | 4 +- packages/ai/src/agent-compact-head.test.ts | 30 ++++ packages/ai/src/agent-compact.ts | 74 ++++++--- packages/ai/src/anthropic-provider.ts | 106 +------------ packages/ai/src/anthropic-strict.test.ts | 2 +- packages/ai/src/anthropic-strict.ts | 104 ++++++++++++ packages/auth/CLAUDE.md | 3 +- packages/auth/README.md | 33 ++++ packages/auth/src/index.test.ts | 14 ++ packages/auth/src/index.ts | 8 +- packages/cache/CLAUDE.md | 9 +- packages/cache/README.md | 11 +- packages/cache/src/broadcast.test.ts | 70 +++++++- packages/cache/src/index.ts | 1 + packages/cache/src/invalidate.ts | 42 +++-- packages/cache/src/redis-buckets.ts | 4 +- packages/cache/src/redis-fake-fixture.ts | 6 +- packages/cache/src/redis-ordering.test.ts | 31 ++++ packages/cache/src/redis.live.test.ts | 20 ++- packages/cache/src/redis.ts | 3 + packages/cache/src/shared-scopes.ts | 32 ++++ packages/cache/src/tiers.ts | 7 + packages/cli/README.md | 8 +- packages/cli/src/cmd-db-rollback.ts | 12 +- packages/cli/src/cmd-errors-app.test.ts | 44 +++++- packages/cli/src/cmd-errors-app.ts | 49 ++---- packages/cli/src/cmd-errors.ts | 18 ++- packages/cli/src/cmd-tasks-run.test.ts | 20 +++ packages/cli/src/cmd-tasks-run.ts | 14 +- packages/cli/src/db-applied-edits.ts | 6 +- packages/cli/src/db-dev-wire.test.ts | 53 +++++++ packages/cli/src/db-dev-wire.ts | 18 +++ packages/cli/src/db-migrate-through-dev.ts | 6 +- packages/cli/src/db-rollback-consent.test.ts | 54 +++++++ packages/cli/src/db-rollback-consent.ts | 60 +++++-- packages/cli/src/db-rollback-pass.ts | 6 +- packages/cli/src/dev-db-migrate.ts | 20 +-- packages/cli/src/dev-db-rollback.ts | 9 +- packages/cli/src/dev-lock.ts | 5 +- packages/cli/src/dev-rebuild-schema.ts | 3 +- packages/cli/src/role-select.test.ts | 70 ++++++++ packages/cli/src/role-select.ts | 33 +++- packages/cli/src/role-start.ts | 16 +- packages/cli/src/runtime-cache-frame.test.ts | 40 +++++ packages/cli/src/runtime-cache-frame.ts | 46 ++++++ packages/cli/src/runtime-cache-scopes.test.ts | 110 +++++++++++++ packages/cli/src/runtime-cache.ts | 25 ++- packages/cli/src/runtime-database-ssl.test.ts | 19 +++ packages/cli/src/runtime-database-ssl.ts | 13 +- packages/cli/src/runtime-jobs-retry.test.ts | 21 ++- packages/cli/src/runtime-jobs.ts | 2 +- packages/cli/src/runtime-queue.ts | 6 + packages/cli/src/runtime-services.ts | 5 +- packages/cli/src/serve-env.ts | 11 +- .../cli/src/serve-graph-ceilings-fixture.ts | 12 +- .../serve-graph-serving-ceiling-fixture.ts | 6 +- .../src/serve-graph-web-ceiling-fixture.ts | 4 +- packages/cli/src/stop-run-start.test.ts | 37 +++++ packages/cli/src/stop-run-start.ts | 12 ++ .../cli/src/templates/sign-in-action-tests.ts | 53 ++----- .../cli/src/templates/sign-in-challenge.ts | 62 ++++++++ .../cli/src/templates/sign-in-oidc-mfa.ts | 57 +------ .../cli/src/templates/sign-in-oidc.test.ts | 4 + .../src/templates/sign-in-password.test.ts | 19 +++ .../cli/src/templates/sign-in-password.ts | 58 +------ .../src/error-reporter-sentry-dsn.test.ts | 33 ++++ packages/core/src/error-reporter-sentry.ts | 5 +- packages/core/src/lifecycle-deadline.test.ts | 35 ++++ packages/core/src/lifecycle-types.ts | 8 + packages/core/src/lifecycle.ts | 13 +- packages/db/README.md | 2 +- packages/db/src/column-drop.ts | 6 +- packages/db/src/generate-rolling.test.ts | 47 ++++++ packages/db/src/index-plan.ts | 8 + packages/db/src/migrate-dev-fix.ts | 30 ++++ packages/db/src/migrate-rollback.ts | 2 +- packages/db/src/migrate.ts | 9 +- packages/db/src/migration-errors-dev.test.ts | 2 +- packages/db/src/migration-errors.ts | 30 +--- packages/db/src/migration-ledger.ts | 3 +- packages/db/src/retype-dependents.ts | 17 ++ packages/entity/package.json | 1 + packages/entity/src/batch-read.test.ts | 73 +++++++++ packages/entity/src/batch-read.ts | 13 +- packages/entity/src/index.ts | 2 +- packages/entity/src/memory-journal.test.ts | 16 +- packages/entity/src/memory-journal.ts | 2 +- packages/entity/src/memory-tx-entry.ts | 5 + packages/entity/src/predicate-operand.test.ts | 11 ++ packages/entity/src/predicate-operand.ts | 12 ++ packages/http/README.md | 11 +- packages/http/src/context.ts | 23 ++- packages/http/src/fault-report.test.ts | 34 ++++ packages/http/src/fault-report.ts | 7 +- packages/http/src/index.ts | 4 +- packages/http/src/peer-identity.test.ts | 149 +++++++++++++++++- packages/http/src/peer-identity.ts | 82 ++++++++-- packages/http/src/wire-dates-cap.test.ts | 121 ++++++++++++++ packages/http/src/wire-dates-cap.ts | 55 +++++++ packages/i18n/src/subset.test.ts | 15 ++ packages/i18n/src/subset.ts | 31 +++- packages/jobs/CLAUDE.md | 3 +- packages/jobs/README.md | 14 +- packages/jobs/src/backfill.ts | 7 +- packages/jobs/src/consumer.ts | 11 +- packages/jobs/src/errors-declaration.ts | 11 +- packages/jobs/src/export.ts | 7 +- packages/jobs/src/import.ts | 7 +- packages/jobs/src/job-types.ts | 10 ++ packages/jobs/src/job.ts | 29 +++- packages/jobs/src/ledger.ts | 7 +- packages/jobs/src/limits-abandon.test.ts | 14 +- packages/jobs/src/partitions.ts | 7 +- packages/jobs/src/purge.ts | 7 +- packages/jobs/src/refresh-view.ts | 8 +- packages/jobs/src/retry-default.test.ts | 35 +++- packages/jobs/src/retry-default.ts | 22 +-- packages/jobs/src/rollup.ts | 8 +- packages/jobs/src/scheduler-dispatch.ts | 30 +++- packages/jobs/src/scheduler-tenant.test.ts | 62 +++++++- packages/jobs/src/subject-jobs.ts | 9 +- packages/jobs/src/webhook-receiver.ts | 7 +- packages/jobs/src/webhook.ts | 7 +- packages/jobs/src/worker-admit.test.ts | 72 ++++++++- packages/jobs/src/worker-admit.ts | 48 +++++- packages/jobs/src/worker-drain-cutoff.test.ts | 26 +++ packages/jobs/src/worker-drain-cutoff.ts | 47 ++++-- packages/jobs/src/worker-drain-finish.test.ts | 50 ++++++ packages/jobs/src/worker-drain-signal.test.ts | 7 +- packages/jobs/src/worker.ts | 5 +- .../src/readonly-sql-forbidden-calls.test.ts | 4 + packages/mcp/src/readonly-sql.ts | 20 +++ packages/query/src/record-answer.test.ts | 73 ++++++++- packages/query/src/record-answer.ts | 8 +- packages/realtime/src/channel-logs.ts | 7 +- packages/realtime/src/channel-tenant.ts | 10 -- packages/realtime/src/fanout.ts | 12 +- packages/realtime/src/presence.test.ts | 6 +- packages/realtime/src/socket.ts | 23 +-- packages/ui/src/hotkeys-view.test.ts | 5 +- packages/ui/src/hotkeys-view.ts | 5 +- packages/ui/src/use-hotkeys.ts | 1 + scripts/lib/public-api-compat.test.ts | 22 +++ scripts/lib/public-api-compat.ts | 24 ++- scripts/lib/public-api-shape-kinds.ts | 29 +++- 157 files changed, 3058 insertions(+), 755 deletions(-) create mode 100644 packages/ai/src/anthropic-strict.ts create mode 100644 packages/cache/src/shared-scopes.ts create mode 100644 packages/cli/src/db-dev-wire.test.ts create mode 100644 packages/cli/src/db-dev-wire.ts create mode 100644 packages/cli/src/db-rollback-consent.test.ts create mode 100644 packages/cli/src/role-select.test.ts create mode 100644 packages/cli/src/runtime-cache-frame.test.ts create mode 100644 packages/cli/src/runtime-cache-frame.ts create mode 100644 packages/cli/src/runtime-cache-scopes.test.ts create mode 100644 packages/cli/src/stop-run-start.test.ts create mode 100644 packages/cli/src/stop-run-start.ts create mode 100644 packages/cli/src/templates/sign-in-challenge.ts create mode 100644 packages/core/src/error-reporter-sentry-dsn.test.ts create mode 100644 packages/db/src/migrate-dev-fix.ts create mode 100644 packages/entity/src/batch-read.test.ts create mode 100644 packages/entity/src/memory-tx-entry.ts create mode 100644 packages/http/src/wire-dates-cap.test.ts create mode 100644 packages/http/src/wire-dates-cap.ts create mode 100644 packages/jobs/src/worker-drain-cutoff.test.ts diff --git a/packages/action/README.md b/packages/action/README.md index d9f80476b..42a9aaac0 100644 --- a/packages/action/README.md +++ b/packages/action/README.md @@ -175,7 +175,11 @@ An output holding a `Date` (`t.date`, an entity `timestamp()` row) names each on typed client hands back the `Date` the output type promises (`As of 2026-11`). The body and the OpenAPI document are unchanged: a client that ignores the header reads the ISO string it always read. Each streamed `chunk` and the `done` frame carry their instants on a `dates:` field, which an -SSE reader that does not know it ignores. +SSE reader that does not know it ignores. The header is capped at 4,096 bytes +(`WIRE_DATES_MAX_BYTES`): an answer whose instants need one path each — a `string | Date` column, a +`[label, instant]` tuple — past that is sent with no `x-ultimate-dates` (and no `dates:` line), the +client reads those instants as ISO strings, and the operation is logged once at `warn` as +`http.wire_dates_dropped`. `As of 2026-11-19`. ### Flight control — `clientFlight`, opt-in @@ -994,9 +998,13 @@ a time, and the batch may have committed before its reply was lost. Each accepte record object, the same one handed to `writeMany` and to its retry, carrying the row id minted when it was accepted. Both inserts skip a row whose id is already stored with the same facts. A DIFFERENT row under that id still raises the driver's `unique_violation`, so a collision is never -silently dropped. `memoryAuditSink` keeps an accepted record once, too. Two attempts with identical -facts are still two records: one object written twice is two acceptances. A sink of your own keys -an idempotent write on the record object it is handed. +silently dropped. A retry that meets its own batch still committing draws `unique_violation` once +(it waited on the key); `postgresAuditSink` sends that record once more, and the second statement +sees the committed row and skips it. `memoryAuditSink` keeps an accepted record once, too. Two attempts with identical +facts are still two records: one object written twice is two acceptances. A sink of your own reads +the same id with `acceptedIdOf(record)` from `@ultimat3/action/adapter` (a string for every record +`batchedAuditSink` handed it, `undefined` for one written unbatched) and keys its idempotent insert +on it. `x_audit` carries the framework's own facts as columns — the action, the surface, the outcome, the actor, the correlation ids, the idempotency key — and the parsed `input` as `jsonb`, redacted diff --git a/packages/action/src/adapter.ts b/packages/action/src/adapter.ts index f625f3b25..43cb873ef 100644 --- a/packages/action/src/adapter.ts +++ b/packages/action/src/adapter.ts @@ -3,6 +3,7 @@ // and group commit for a sink author's own `writeMany`. Never the `.` barrel: an app swaps a store // in `apps/<app>/runtime.ts`, so the callers here are the cli boot, `@ultimat3/testing` and authors. +export { acceptedIdOf } from './audit-accepted'; export type { BatchAuditSink, BatchedAuditSink, BatchedAuditSinkOptions } from './audit-batch'; export { batchedAuditSink, diff --git a/packages/action/src/audit-batch.test.ts b/packages/action/src/audit-batch.test.ts index 6737eb5ab..4a3258c60 100644 --- a/packages/action/src/audit-batch.test.ts +++ b/packages/action/src/audit-batch.test.ts @@ -3,6 +3,7 @@ // a dead store still fails every one — and a drain leaves nothing queued behind. import { afterEach, describe, expect, jest, test } from 'bun:test'; +import { acceptedIdOf } from '@ultimat3/action/adapter'; import { configureLifecycle, ctxOf, @@ -161,6 +162,32 @@ describe('batchedAuditSink groups concurrent writes into one writeMany', () => { expect(singles.toSorted()).toEqual(['a', 'c', 'poisoned']); }); + test("a sink of one's own reads the accepted id off the adapter: one per write, the same on the retry", async () => { + const seen: (string | undefined)[][] = []; + const lostReply = new RangeError('connection reset after commit'); + let first = true; + const sink: BatchAuditSink = { + write: async (record) => { + seen.push([acceptedIdOf(record)]); + }, + async writeMany(records) { + seen.push(records.map(acceptedIdOf)); + if (first) { + first = false; + throw lostReply; + } + }, + }; + const batched = open(sink, { maxDelayMs: 0 }); + await Promise.all(['a', 'b'].map((name) => batched.write(recordNamed(name)))); + const [batch = [], ...singles] = seen; + expect(batch).toHaveLength(2); + expect(batch.every((id) => typeof id === 'string')).toBe(true); + expect(new Set(batch).size).toBe(2); + expect(singles.flat().toSorted()).toEqual(batch.toSorted()); + expect(acceptedIdOf(recordNamed('never accepted'))).toBeUndefined(); + }); + test('a batch that stored its rows and then rejected settles every waiter as stored, and stores each record once', async () => { const ring = memoryAuditSink(); const lostReply = new RangeError('connection reset after commit'); diff --git a/packages/action/src/audit-postgres.test.ts b/packages/action/src/audit-postgres.test.ts index 331c51ae7..d64f98311 100644 --- a/packages/action/src/audit-postgres.test.ts +++ b/packages/action/src/audit-postgres.test.ts @@ -347,6 +347,35 @@ describe('the postgres audit sink writes many records in one statement', () => { expect(new Set(batchIds).size).toBe(2); }); + test('groupCommit: a retry that meets its own batch mid-commit (23505) re-sends once and settles', async () => { + // The batch committed after its reply was lost: the retry's `not exists` ran before that + // commit, waited on the key, and the server answered unique_violation. Sent again, it sees the + // committed identical row and skips it; a second 23505 is a DIFFERENT row and still fails. + const uniqueViolation = { severity: 'ERROR', code: '23505', message: 'duplicate key' }; + const singles: string[] = []; + const exec: PgExecutor = { + query<R>(sql: string, params: readonly unknown[]): Promise<readonly R[]> { + if (sql === SQL_AUDIT_INSERT_MANY) return Promise.reject(new RangeError('reply lost')); + const name = String(params[2]); + singles.push(name); + const seen = singles.filter((one) => one === name).length; + if (name === 'clash' || seen === 1) return Promise.reject(uniqueViolation); + return Promise.resolve([] as unknown as readonly R[]); + }, + }; + const sink = postgresAuditSink({ executor: exec, groupCommit: { maxDelayMs: 0 } }); + let settled: PromiseSettledResult<void>[]; + try { + settled = await Promise.allSettled( + ['a', 'clash'].map((name) => sink.write(recordFor({ name }))), + ); + } finally { + await sink.close(); + } + expect(settled.map((one) => one.status)).toEqual(['fulfilled', 'rejected']); + expect(singles.toSorted()).toEqual(['a', 'a', 'clash', 'clash']); + }); + test('two records with identical facts are two ids: an attempt is never collapsed', async () => { const { exec, calls } = executor(); const sink = postgresAuditSink({ executor: exec }); diff --git a/packages/action/src/audit-postgres.ts b/packages/action/src/audit-postgres.ts index a40f2b689..264e738af 100644 --- a/packages/action/src/audit-postgres.ts +++ b/packages/action/src/audit-postgres.ts @@ -6,10 +6,11 @@ import type { PgExecutor } from '@ultimat3/core'; import type { AuditRecord } from './audit'; +import { acceptedIdOf } from './audit-accepted'; import type { BatchAuditSink, BatchedAuditSink, BatchedAuditSinkOptions } from './audit-batch'; import { batchedAuditSink } from './audit-batch'; import { rowOf } from './audit-postgres-row'; -import { outsideTransactions } from './tx-scope'; +import { isUniqueViolation, outsideTransactions } from './tx-scope'; /** * Applied by the boot, never by an app migration — the rule `SQL_IDEMPOTENCY_TABLE` follows, and @@ -205,7 +206,16 @@ export function postgresAuditSink( const exec = grouped ? outsideTransactions(options.executor) : options.executor; const sink: PostgresAuditSink = { async write(record: AuditRecord): Promise<void> { - await exec.query(SQL_AUDIT_INSERT, Object.values(rowOf(record))); + const row = Object.values(rowOf(record)); + try { + await exec.query(SQL_AUDIT_INSERT, row); + } catch (error) { + // Group commit's single retry can meet its own batch still committing: its `not exists` + // ran first, it then waited on the key and drew 23505. Sent once more it sees the + // committed row and skips it if identical; a different row raises again, as it should. + if (acceptedIdOf(record) === undefined || !isUniqueViolation(error)) throw error; + await exec.query(SQL_AUDIT_INSERT, row); + } }, async writeMany(records: readonly AuditRecord[]): Promise<void> { if (records.length === 0) return; diff --git a/packages/action/src/http-dates.test.ts b/packages/action/src/http-dates.test.ts index 81fbefaae..a166ddf5d 100644 --- a/packages/action/src/http-dates.test.ts +++ b/packages/action/src/http-dates.test.ts @@ -3,9 +3,16 @@ // so the typed client hands back the `Date` the output type promises. The body stays the ISO text. import { afterAll, describe, expect, test } from 'bun:test'; -import { DATES_HEADER, RECORDS_HEADER, reviveWireDates, userActor } from '@ultimat3/core'; +import { + DATES_HEADER, + installLogSink, + RECORDS_HEADER, + reviveWireDates, + userActor, + wireDatePaths, +} from '@ultimat3/core'; import { clearRegistry, entity, timestamp, uuid } from '@ultimat3/entity'; -import { defineHttpConfig, httpServer } from '@ultimat3/http'; +import { defineHttpConfig, httpServer, WIRE_DATES_MAX_BYTES } from '@ultimat3/http'; import { allow } from '@ultimat3/policy'; import { t } from '@ultimat3/schema'; import type { AnyAction } from './action'; @@ -134,3 +141,109 @@ describe('an action whose output holds a Date', () => { ); }); }); + +// A `string | Date` column shares one pattern between text and an instant, so no path folds — as +// a chart's `[label, instant]` tuples do: 20,000 instants were a 648 KB response header, which a +// default nginx answers 502. +describe('an output whose instants cannot fold stays under the header cap', () => { + /** `count` instants, each beside a row whose same column is text. */ + const points = (count: number) => + Array.from({ length: count * 2 }, (_, index) => ({ + value: index % 2 === 0 ? `label-${index}` : AT, + })); + const Points = t.array(t.object({ value: t.union(t.string, t.date) })); + const Series = t.object({ points: Points }); + const logged = async (run: () => Promise<void>): Promise<readonly string[]> => { + const lines: string[] = []; + const release = installLogSink((line) => void lines.push(line)); + try { + await run(); + } finally { + release(); + } + return lines.filter((line) => line.includes('http.wire_dates_dropped')); + }; + + test('past the cap the plain 200 carries no header, the body unchanged, one warn per action', async () => { + const chart = action({ + input: t.object({}), + output: Series, + policy: allow(), + handle: () => ({ points: points(20_000) }), + }).named('chartSeries'); + expect(wireDatePaths({ points: points(20_000) })?.length).toBeGreaterThan(500_000); + const lines = await logged(async () => { + for (let call = 0; call < 2; call += 1) { + const response = await post(chart); + expect(response.status).toBe(200); + expect(response.headers.get(DATES_HEADER)).toBeNull(); + const body = (await response.json()) as { points: { value: string }[] }; + expect(body.points).toHaveLength(40_000); + expect(body.points[1]).toEqual({ value: AT.toISOString() }); + } + // The typed client reads the ISO strings it read before the header existed. + const call = chart.client({ baseUrl: 'http://dev.test', fetch: fetchOf(chart) }); + expect((await call({})).points[1]?.value).toBe(AT.toISOString()); + }); + expect(lines).toHaveLength(1); + expect(JSON.parse(lines[0] ?? '{}')).toMatchObject({ operation: 'chartSeries', paths: 20_000 }); + }); + + test('under the cap the same shape still names every instant', async () => { + const small = action({ + input: t.object({}), + output: Series, + policy: allow(), + handle: () => ({ points: points(20) }), + }).named('chartSeriesSmall'); + const header = (await post(small)).headers.get(DATES_HEADER); + expect(header).toBe(wireDatePaths({ points: points(20) }) ?? null); + expect(header?.length).toBeLessThanOrEqual(WIRE_DATES_MAX_BYTES); + }); + + test('the enveloped 200 follows the same cap and keeps x-ultimate-records', async () => { + const wide = action({ + input: t.object({}), + output: t.object({ event: events.$schema, points: Points }), + policy: allow(), + handle: () => ({ event: { id: ID, at: AT }, points: points(2_000) }), + }).named('chartWithRecord'); + const response = await post(wide); + expect(response.headers.get(RECORDS_HEADER)).toBe('1'); + expect(response.headers.get(DATES_HEADER)).toBeNull(); + }); + + test('a streamed chunk and the done frame past the cap carry no dates line, one warn', async () => { + const live = action({ + input: t.object({}), + output: Series, + stream: Series, + policy: allow(), + async *handle() { + yield { points: points(2_000) }; + yield { points: points(2_000) }; + yield { points: points(2) }; + return { points: points(2_000) }; + }, + }).named('chartStream'); + let text = ''; + const lines = await logged(async () => { + text = await (await post(live, 'text/event-stream')).text(); + }); + const frames = text.split('\n\n').filter((frame) => frame !== ''); + expect(frames.map((frame) => frame.split('\n')[0])).toEqual([ + 'event: chunk', + 'event: chunk', + 'event: chunk', + 'event: done', + ]); + expect(frames.map((frame) => frame.includes('\ndates: '))).toEqual([false, false, true, false]); + for (const frame of frames) { + for (const line of frame.split('\n')) { + if (!line.startsWith('data: ')) expect(line.length).toBeLessThan(WIRE_DATES_MAX_BYTES + 8); + } + } + expect(lines).toHaveLength(1); + expect(JSON.parse(lines[0] ?? '{}')).toMatchObject({ operation: 'chartStream', paths: 2_000 }); + }); +}); diff --git a/packages/action/src/http-stream.test.ts b/packages/action/src/http-stream.test.ts index f1719c278..0200e520d 100644 --- a/packages/action/src/http-stream.test.ts +++ b/packages/action/src/http-stream.test.ts @@ -21,7 +21,7 @@ import type { AnyAction } from './action'; import { action } from './action'; import { InputInvalidError } from './errors'; import { toOpenApiOperation, toRoute } from './http'; -import { wantsEventStream } from './http-stream'; +import { streamAnswer, wantsEventStream } from './http-stream'; const Chunk = t.object({ text: t.string }); const Out = t.object({ total: t.number }); @@ -233,6 +233,27 @@ describe('a stream-declaring action over HTTP', () => { expect(seen).toEqual([]); }); + // `reportLateFault` is the ONE report site, and it is the pipeline request's. Every route reaches + // this stream through the pipeline; one driven with no request behind it is a harness, which + // reads the error frame it was sent — this file no longer assembles a second monitor scope. + test('a stream driven outside the pipeline answers the error frame and reports nowhere', async () => { + const reporter = memoryErrorReporter(); + installErrorReporter(reporter); + const response = await direct(() => + streamAnswer({}, async (sink) => { + sink.start(); + // The 200 has left by the time this throws: the fault is a late one. + await new Promise((resolve) => setImmediate(resolve)); + throw new InternalError({ cause: 'the store went away', fix: 'bun run x -- doctor' }); + }), + ); + expect(response.status).toBe(200); + const text = await response.text(); + expect(text).toStartWith('event: error\n'); + expect(text).toContain('X_INTERNAL'); + expect(reporter.events).toEqual([]); + }); + test("a 4xx thrown after the first chunk is the caller's and is not reported", async () => { const reporter = memoryErrorReporter(); installErrorReporter(reporter); diff --git a/packages/action/src/http-stream.ts b/packages/action/src/http-stream.ts index 184f0f7e9..6db8d8fb3 100644 --- a/packages/action/src/http-stream.ts +++ b/packages/action/src/http-stream.ts @@ -6,14 +6,8 @@ */ import type { Ctx } from '@ultimat3/core'; -import { - isAnonymous, - reportError, - useContext, - wireDatePaths, - withChildContext, -} from '@ultimat3/core'; -import { factsOf, isCallerAbort, reportLateFault, toProblem } from '@ultimat3/http'; +import { useContext, withChildContext } from '@ultimat3/core'; +import { cappedWireDates, reportLateFault, toProblem } from '@ultimat3/http'; import type { ChunkSink } from './action-stream'; export const EVENT_STREAM = 'text/event-stream'; @@ -36,7 +30,8 @@ const STARTED: unique symbol = Symbol('started'); * One SSE frame. JSON never holds a raw newline, so `data:` is always one line. `dates` is the * `x-ultimate-dates` value for THIS frame's data (core's `wire-dates.ts`, URI-encoded, so one line * too): a field the SSE format tells every reader that does not know it to ignore, so a client from - * before it reads the frame it always read. + * before it reads the frame it always read. Under the header's cap (`cappedWireDates`): a frame + * whose value is past it carries no `dates:` line, and its instants are read as ISO strings. */ export function sseFrame( event: 'chunk' | 'done' | 'error', @@ -47,27 +42,6 @@ export function sseFrame( return encoder.encode(`event: ${event}\n${named}data: ${JSON.stringify(data ?? null)}\n\n`); } -/** - * A fault after the first byte never reaches the pipeline's `error-map` stage — the 200 has gone — - * so it is handed to the request's late-fault report (`reportLateFault`: the monitor, the app's - * `onError`, the log line, once). With no pipeline request behind `ctx` the monitor is still told: - * a 5xx only, the route PATTERN as operation. - */ -function reportStreamFault(error: unknown, operation: string, ctx: Ctx): void { - if (reportLateFault(error, ctx)) return; - if (factsOf(error).status < 500) return; - reportError(error, { - source: 'http', - scope: { - requestId: ctx.requestId, - traceId: ctx.traceId, - role: ctx.role, - operation, - actorId: isAnonymous(ctx.actor) ? undefined : ctx.actor.id, - }, - }); -} - /** Runs the invocation with `sink` receiving its chunks; resolves the output. */ export type StreamRun = (sink: ChunkSink) => Promise<unknown>; @@ -78,7 +52,6 @@ export type StreamRun = (sink: ChunkSink) => Promise<unknown>; export async function streamAnswer( owner: object, run: StreamRun, - operation: string, heartbeatMs: number = HEARTBEAT_MS, ): Promise<Response> { // Read here, in the request's frame: the settle below runs on a later turn. @@ -98,9 +71,14 @@ export async function streamAnswer( const sink: ChunkSink = { owner, start: () => begin(), - push: (chunk) => send(sseFrame('chunk', chunk, wireDatePaths(chunk))), + push: (chunk) => send(sseFrame('chunk', chunk, cappedWireDates(chunk, ctx))), }; - const settled = withChildContext({ signal: left.signal }, () => run(sink)); + // The handler's own scope: its signal is the request's and `left`'s, composed. + let scope: Ctx = ctx; + const settled = withChildContext({ signal: left.signal }, () => { + scope = useContext(); + return run(sink); + }); // Settled without starting is a refusal — thrown here, before any byte — or a replayed answer, // which streams as a lone `done`. await Promise.race([started, settled]); @@ -118,12 +96,13 @@ export async function streamAnswer( } }; settled.then( - (output) => finish(sseFrame('done', output, wireDatePaths(output))), + (output) => finish(sseFrame('done', output, cappedWireDates(output, ctx))), (error: unknown) => { - // The reader cancelled (or the caller hung up) and the handler unwound on the abort: - // nobody is there to answer and nothing failed, so it is not anybody's incident. - const gone = isCallerAbort(error, left.signal) || isCallerAbort(error, ctx.signal); - if (!gone) reportStreamFault(error, operation, ctx); + // A fault after the first byte never reaches the pipeline's `error-map` stage — the 200 + // has gone — so the request's late-fault report records it (the monitor, the app's + // `onError`, the log line, once). It tells the reader cancelling, or the caller hanging + // up, from a failure by `scope`'s signal, and records nothing for those. + reportLateFault(error, scope); finish(sseFrame('error', toProblem(error, { requestId }))); }, ); diff --git a/packages/action/src/http.ts b/packages/action/src/http.ts index 504012260..08c237396 100644 --- a/packages/action/src/http.ts +++ b/packages/action/src/http.ts @@ -153,9 +153,7 @@ function projectRoute( ); // The same invocation, its chunks sent as they are yielded: one route, chosen by `accept`. if (streams && wantsEventStream(req.header('accept'))) { - // The route PATTERN, as the `error-map` stage names a fault this stream reports itself. - const operation = `${req.ctx.method} ${req.ctx.route?.path ?? path}`; - return streamAnswer(def, (sink) => withChunkSink(sink, call), operation); + return streamAnswer(def, (sink) => withChunkSink(sink, call)); } // A browser's own form, to an action that declared where it lands: a 303 and a flash, the // refusal included. Everything above — the policy, the idempotency, the write — is the same. diff --git a/packages/action/src/record-wire.ts b/packages/action/src/record-wire.ts index 9dd284b6f..4414d3061 100644 --- a/packages/action/src/record-wire.ts +++ b/packages/action/src/record-wire.ts @@ -4,9 +4,9 @@ * action's body is byte-identical to what it always was. Either names its instants by path. */ -import { DATES_HEADER, encodeRecordEnvelope, RECORDS_HEADER, wireDatePaths } from '@ultimat3/core'; +import { DATES_HEADER, encodeRecordEnvelope, RECORDS_HEADER } from '@ultimat3/core'; import { hasEntityRows, rowsOf } from '@ultimat3/entity'; -import { jsonResponse } from '@ultimat3/http'; +import { cappedWireDates, jsonResponse } from '@ultimat3/http'; import type { StandardSchemaV1 } from '@ultimat3/schema'; /** The header value that says "this body is an envelope". Presence alone is not enough. */ @@ -27,10 +27,12 @@ export function carriesRecords(output: StandardSchemaV1): boolean { /** * The output's instants — `@ultimat3/core`'s `wire-dates.ts`, the rule `@ultimat3/query`'s * `record-answer.ts` follows — so the typed client hands back the `Date` the output type promises. - * A header, never the body: an old client reads the ISO string it always read. + * A header, never the body: an old client reads the ISO string it always read. Capped + * (`cappedWireDates`, 4 KB): an output needing one path per instant past that sends NO header — + * a proxy refuses a response whose headers outgrow its buffer — and is logged once per action. */ function datesOf(result: unknown): { readonly headers: Record<string, string> } { - const dates = wireDatePaths(result); + const dates = cappedWireDates(result); return { headers: dates === undefined ? {} : { [DATES_HEADER]: dates } }; } diff --git a/packages/action/src/tx-scope.ts b/packages/action/src/tx-scope.ts index ed0d66c09..9a1c5d62c 100644 --- a/packages/action/src/tx-scope.ts +++ b/packages/action/src/tx-scope.ts @@ -1,7 +1,8 @@ /** * The open database transaction, as this package needs it — **the only** file here that imports * `@ultimat3/db` (`tx-scope.test.ts`): when a write is durable, whether a transaction is OPEN and on - * which client, a scope whose writes are never kept, and an executor that never joins one. + * which client, a scope whose writes are never kept, an executor that never joins one, and the + * one SQLSTATE an insert outside a transaction asks about. */ // Type-only: `idempotency-postgres.ts` imports this module, and a runtime edge would be a cycle. @@ -13,9 +14,12 @@ import { dbClientInstalled, liveTxConnection, outsideTransaction, + SQLSTATE, + sqlState, withTransaction, } from '@ultimat3/db'; -import { memoryJournal, memoryTransactor, memoryTxOpen } from '@ultimat3/entity'; +import { memoryJournal, memoryTransactor } from '@ultimat3/entity'; +import { memoryTxOpen } from '@ultimat3/entity/internal/memory-tx'; /** The mark a keyed run puts on the open root: its COMMIT carries the settle, abort or no abort. */ export const carrySettleOnCommit = (): void => completeTransaction(); @@ -29,6 +33,10 @@ export const outsideTransactions = (executor: PgExecutor): PgExecutor => ({ query: (text, values) => outsideTransaction(() => executor.query(text, values)), }); +/** Whether `error` is Postgres' `unique_violation`, read through db's one SQLSTATE reader. */ +export const isUniqueViolation = (error: unknown): boolean => + sqlState(error) === SQLSTATE.uniqueViolation; + /** The half of a transaction a deferred effect needs. `@ultimat3/db`'s `DbTx` satisfies it. */ export interface CommitScope { /** Fired once the ROOT transaction has committed; dropped on rollback or a lost COMMIT. */ diff --git a/packages/ai/CLAUDE.md b/packages/ai/CLAUDE.md index 4f2fbdf67..4b01882d3 100644 --- a/packages/ai/CLAUDE.md +++ b/packages/ai/CLAUDE.md @@ -21,7 +21,7 @@ Keep `policy` dev-only: tests and `*-fixture.ts` harnesses import `allow`. The | `model-resolve.ts` | `resolveModel` / `modelForCall` — declaration → prompt → gateway `defaultModel`, none is `X_AI_MODEL_UNRESOLVED` naming all three; `describedModel` for a published fact | | `model-fixture.ts` | the rows this package's own suites register (`useFixtureModels()`). Not shipped | | `provider.ts` | `Provider` interface, the request half; re-exports the Anthropic names | -| `anthropic-provider.ts` | `anthropicProvider()`, stream-only rule (`requiresStreaming`), message parse; `strict` per tool | +| `anthropic-provider.ts` / `-strict.ts` | `anthropicProvider()`, `requiresStreaming`, message parse; which tools keep `strict` | | `echo-provider.ts` | `echoProvider()`, the deterministic double. A fixture that needs a tool call uses `scriptedProvider`, never a hand-rolled `Provider` | | `scripted-provider.ts` | `scriptedProvider()`, the scripted double that calls tools, and `X_AI_SCRIPT_EXHAUSTED`: one call past the script is refused, never answered with the last turn again | | `content-blocks.ts` | the `image` / `document` block shapes, the screen every request runs them through, their token estimate | diff --git a/packages/ai/README.md b/packages/ai/README.md index 4dc4b979a..ffd44bd83 100644 --- a/packages/ai/README.md +++ b/packages/ai/README.md @@ -600,7 +600,9 @@ reported for the last one — is compared with the model row's `contextWindow` l the last `keepTurns`; the summary joins the first user message (after the prompt, verbatim, marked `[compacted: …]`), the kept turns follow byte for byte, and the turn is sent. What the **user** said in the summarised turns — a `.continue()` instruction — is carried into that first message -verbatim, newest first up to `KEPT_USER_CHARS` (8,000 characters), never left to the summary alone. +verbatim, newest first up to `KEPT_USER_CHARS` (8,000 characters) **in total** — what earlier +compactions carried is charged against the same allowance, so a long chat's head stays bounded — +and beyond it left to the summary. | Rule | Why | |---|---| diff --git a/packages/ai/src/agent-compact-head.test.ts b/packages/ai/src/agent-compact-head.test.ts index d0b4332d3..4c6068f32 100644 --- a/packages/ai/src/agent-compact-head.test.ts +++ b/packages/ai/src/agent-compact-head.test.ts @@ -61,6 +61,36 @@ describe('compactedHead()', () => { expect(JSON.stringify(twice)).not.toContain('FIRST'); }); + test('repeated compactions never carry more than KEPT_USER_CHARS of user text in total', () => { + let head = HEAD; + for (const round of [0, 1, 2, 3, 4]) { + head = compactedHead(head, turn(`t${round}`, `U${round}:${'x'.repeat(3_000)}`), 1, 'S'); + } + const carried = texts(head).slice(1, -1); + expect(texts(head)[0]).toBe('Write about tides.'); + // Newest first: the two latest fit the one budget, the older three are the summary's. + expect(carried.map((text) => text.slice(0, 3))).toEqual(['U3:', 'U4:']); + expect(carried.join('').length).toBeLessThanOrEqual(KEPT_USER_CHARS); + }); + + test('a prompt of several blocks stays whole across compactions; only carried text is charged', () => { + const prompt: AiMessage = { + role: 'user', + content: [ + { type: 'text', text: 'Write about tides.' }, + { type: 'text', text: 'y'.repeat(KEPT_USER_CHARS) }, + ], + }; + const once = compactedHead(prompt, turn('a', 'In French.'), 1, 'FIRST'); + const twice = compactedHead(once, turn('b', 'And shorter.'), 1, 'SECOND'); + expect(texts(twice).slice(0, -1)).toEqual([ + 'Write about tides.', + 'y'.repeat(KEPT_USER_CHARS), + 'In French.', + 'And shorter.', + ]); + }); + test('a prompt that merely STARTS with the marker is not mistaken for an old summary', () => { const head: AiMessage = { role: 'user', content: '[compacted: notes] Write about tides.' }; expect(texts(compactedHead(head, turn('a'), 1, 'S'))[0]).toBe( diff --git a/packages/ai/src/agent-compact.ts b/packages/ai/src/agent-compact.ts index 1ca44ed42..6aea48976 100644 --- a/packages/ai/src/agent-compact.ts +++ b/packages/ai/src/agent-compact.ts @@ -280,9 +280,10 @@ function splitTurns(messages: readonly AiMessage[], keepTurns: number): Split | } /** - * The most user text one compaction carries out of the summarised turns, in characters (~2,000 - * tokens). Newest first: past it the older text is the summary's to cover, as all of it was — a - * pasted document must not make a transcript no compaction can shorten. + * The most user text a compacted head carries out of summarised turns, in characters (~2,000 + * tokens), IN TOTAL: what earlier compactions carried is charged too, newest kept first. Past it the + * older text is the summary's to cover, as all of it was — a pasted document, or a long + * `.continue()` chat, must not make a transcript no compaction can shorten. */ export const KEPT_USER_CHARS = 8_000; @@ -293,13 +294,28 @@ export const KEPT_USER_CHARS = 8_000; */ const SUMMARY_NOTE = /^\[compacted: \d+ earlier turns? of this run were summarised to fit /; +/** The clause naming how many blocks before the note are carried user text, not the prompt. */ +const CARRIED_NOTE = + /^\[compacted: \d+ earlier turns? of this run were summarised to fit the context window, the last (\d+) text blocks? above kept as the user wrote them\./; + const isSummary = (block: AiContentBlock): boolean => block.type === 'text' && SUMMARY_NOTE.test(block.text); +/** How many blocks an earlier compaction carried, read off its note; 0 for a note without the count. */ +function carriedCount(blocks: readonly AiContentBlock[]): number { + for (const block of blocks) { + if (block.type !== 'text' || !isSummary(block)) continue; + const count = CARRIED_NOTE.exec(block.text)?.[1]; + return count === undefined ? 0 : Number.parseInt(count, 10); + } + return 0; +} + /** - * `head` rebuilt for `turns` summarised turns (`older`): its own blocks less an earlier summary — - * the new one covers it — then the user's text out of `older`, then the summary. The model reads - * the summary as its own notes, said to be so. + * `head` rebuilt for `turns` summarised turns (`older`): its prompt less an earlier summary — the + * new one covers it — then the user's text out of what earlier compactions carried and `older`, + * within one `KEPT_USER_CHARS`, then the summary. The model reads the summary as its own notes, + * said to be so; the note counts the carried blocks so the next compaction can charge them. */ export function compactedHead( head: AiMessage, @@ -307,37 +323,47 @@ export function compactedHead( turns: number, summary: string, ): AiMessage { - const prompt = blocksOf(head).filter((block) => !isSummary(block)); - const note = `${COMPACTED_MARK} ${turns} earlier turn${turns === 1 ? '' : 's'} of this run were summarised to fit the context window. Your summary of everything after the task above:]\n\n${summary}`; + const blocks = blocksOf(head); + const own = blocks.filter((block) => !isSummary(block)); + const from = Math.max(0, own.length - carriedCount(blocks)); + const kept = userTexts([...textsOf(own.slice(from)), ...older.flatMap(saidIn)]); + const carried = + kept.length === 0 + ? '' + : `, the last ${kept.length} text block${kept.length === 1 ? '' : 's'} above kept as the user wrote them`; + const note = `${COMPACTED_MARK} ${turns} earlier turn${turns === 1 ? '' : 's'} of this run were summarised to fit the context window${carried}. Your summary of everything after the task above:]\n\n${summary}`; return { role: 'user', - content: [...prompt, ...userTexts(older), { type: 'text', text: note }], + content: [ + ...own.slice(0, from), + ...kept.map((text): AiContentBlock => ({ type: 'text', text })), + { type: 'text', text: note }, + ], }; } +const textsOf = (blocks: readonly AiContentBlock[]): readonly string[] => + blocks.flatMap((block) => (block.type === 'text' ? [block.text] : [])); + /** - * What the user wrote in `older`, oldest first, within `KEPT_USER_CHARS`. A user message there - * holds tool results and framework text too: results are never text blocks, and the loop's own - * correction is recognised by `isRepairText`. + * What the user wrote in one message. A user message holds tool results and framework text too: + * results are never text blocks, and the loop's own correction is recognised by `isRepairText`. */ -function userTexts(older: readonly AiMessage[]): readonly AiContentBlock[] { - const said: string[] = []; - for (const message of older) { - if (message.role !== 'user') continue; - for (const block of blocksOf(message)) { - if (block.type === 'text' && block.text.trim() !== '' && !isRepairText(block.text)) { - said.push(block.text); - } - } - } +const saidIn = (message: AiMessage): readonly string[] => + message.role !== 'user' + ? [] + : textsOf(blocksOf(message)).filter((text) => text.trim() !== '' && !isRepairText(text)); + +/** `said`, oldest first, cut to the newest that fit `KEPT_USER_CHARS` together. */ +function userTexts(said: readonly string[]): readonly string[] { const kept: string[] = []; let room = KEPT_USER_CHARS; - for (const text of said.reverse()) { + for (const text of [...said].reverse()) { if (text.length > room) break; room -= text.length; kept.unshift(text); } - return kept.map((text) => ({ type: 'text', text })); + return kept; } /** The event's facts about the summary call's input: its form, and how far text was shortened. */ diff --git a/packages/ai/src/anthropic-provider.ts b/packages/ai/src/anthropic-provider.ts index c2a4de67a..bc64a6a89 100644 --- a/packages/ai/src/anthropic-provider.ts +++ b/packages/ai/src/anthropic-provider.ts @@ -3,6 +3,7 @@ // ./provider's; ./models owns the per-model rules and ./wire the streamed response half. import { readAnswerBody } from './answer-body'; +import { anthropicTools } from './anthropic-strict'; import { billedCall } from './billed'; import { assertMediaContent } from './content-blocks'; import { providerFailure } from './context-overflow'; @@ -23,7 +24,7 @@ import { samplingBody } from './sampling'; import { readSse } from './sse'; import { trackSent, trackStreamBill } from './stream-bill'; import { assertToolArguments } from './tool-arguments'; -import type { JsonSchema, LlmTool, LlmToolCall } from './tools'; +import type { LlmToolCall } from './tools'; import { asToolInput, MessageStream, @@ -314,106 +315,3 @@ export function parseMessage(model: ModelId, input: unknown): GenerateResult { costExact: exactCostOf(model, usage), }; } - -// Which tools of one request may carry `strict: true`. On this wire the flag is a promise the server -// checks — a schema outside the documented strict subset, or a request past one of three caps, is a -// 400 — so it is derived per request, never forwarded. Source (read 2026-11-19): -// platform.claude.com/docs/en/build-with-claude/structured-outputs. - -/** "Strict tools per request: 20". A tool sent without the flag does not count. */ -export const MAX_STRICT_TOOLS = 20; -/** "Optional parameters: 24" — keys not in `required`, summed over every strict schema. */ -export const MAX_STRICT_OPTIONAL = 24; -/** "Parameters with union types: 16" — `anyOf`, summed over every strict schema. */ -export const MAX_STRICT_UNIONS = 16; - -/** - * The keywords the strict subset accepts as this package emits them. An ALLOW-list: a keyword the - * projection grows later is outside it until someone reads the provider's page again. `pattern` is - * left out on purpose — only "simple" patterns compile, and which those are is not ours to guess. - */ -const ACCEPTED: ReadonlySet<string> = new Set([ - 'type', - 'title', - 'description', - 'properties', - 'required', - 'additionalProperties', - 'items', - 'minItems', - 'enum', - 'const', - 'default', - 'anyOf', -]); - -/** What one schema costs against the request's caps. */ -export interface StrictWeight { - readonly optional: number; - readonly unions: number; -} - -/** - * `schema`'s weight when it is inside the strict subset, `undefined` when it is not: a length, - * numeric or array bound (`minItems` 0 and 1 excepted), an object not closed with - * `additionalProperties: false`, or `anyOf` beside `type` / `properties`. - */ -export function strictSubset(schema: JsonSchema): StrictWeight | undefined { - for (const key of Object.keys(schema)) if (!ACCEPTED.has(key)) return undefined; - if (schema.minItems !== undefined && schema.minItems !== 0 && schema.minItems !== 1) { - return undefined; - } - let optional = 0; - let unions = 0; - const children: JsonSchema[] = []; - if (schema.anyOf !== undefined) { - if (schema.type !== undefined || schema.properties !== undefined) return undefined; - unions += 1; - children.push(...schema.anyOf); - } - if (schema.items !== undefined) children.push(schema.items); - if (schema.type === 'object' || schema.properties !== undefined) { - if (schema.additionalProperties !== false) return undefined; - const required = new Set(schema.required ?? []); - for (const [key, child] of Object.entries(schema.properties ?? {})) { - if (!required.has(key)) optional += 1; - children.push(child); - } - } - for (const child of children) { - const weight = strictSubset(child); - if (weight === undefined) return undefined; - optional += weight.optional; - unions += weight.unions; - } - return { optional, unions }; -} - -/** - * The request's tools as this wire takes them: `strict` kept where the tool asked for it, its - * schema is inside the subset, and the request stays under all three caps — granted in request - * order, so the same tools always get the same flags (the tools are a cached prefix). A tool - * without the flag is sent whole and validated by its own schema on the way back, as every tool - * call already is. - */ -export function anthropicTools(tools: readonly LlmTool[]): readonly LlmTool[] { - let strict = 0; - let optional = 0; - let unions = 0; - return tools.map((tool) => { - const { strict: asked, ...rest } = tool; - const weight = asked === true ? strictSubset(tool.input_schema) : undefined; - if ( - weight === undefined || - strict + 1 > MAX_STRICT_TOOLS || - optional + weight.optional > MAX_STRICT_OPTIONAL || - unions + weight.unions > MAX_STRICT_UNIONS - ) { - return rest; - } - strict += 1; - optional += weight.optional; - unions += weight.unions; - return tool; - }); -} diff --git a/packages/ai/src/anthropic-strict.test.ts b/packages/ai/src/anthropic-strict.test.ts index b5b994af8..53ba4e333 100644 --- a/packages/ai/src/anthropic-strict.test.ts +++ b/packages/ai/src/anthropic-strict.test.ts @@ -7,7 +7,7 @@ import { MAX_STRICT_TOOLS, MAX_STRICT_UNIONS, strictSubset, -} from './anthropic-provider'; +} from './anthropic-strict'; import type { JsonSchema, LlmTool } from './tools'; const object = ( diff --git a/packages/ai/src/anthropic-strict.ts b/packages/ai/src/anthropic-strict.ts new file mode 100644 index 000000000..dcc970e83 --- /dev/null +++ b/packages/ai/src/anthropic-strict.ts @@ -0,0 +1,104 @@ +// Which tools of one Anthropic request may carry `strict: true`. On this wire the flag is a promise +// the server checks — a schema outside the documented strict subset, or a request past one of three +// caps, is a 400 — so it is derived per request, never forwarded. Source (read 2026-11-19): +// platform.claude.com/docs/en/build-with-claude/structured-outputs. + +import type { JsonSchema, LlmTool } from './tools'; + +/** "Strict tools per request: 20". A tool sent without the flag does not count. */ +export const MAX_STRICT_TOOLS = 20; +/** "Optional parameters: 24" — keys not in `required`, summed over every strict schema. */ +export const MAX_STRICT_OPTIONAL = 24; +/** "Parameters with union types: 16" — `anyOf`, summed over every strict schema. */ +export const MAX_STRICT_UNIONS = 16; + +/** + * The keywords the strict subset accepts as this package emits them. An ALLOW-list: a keyword the + * projection grows later is outside it until someone reads the provider's page again. `pattern` is + * left out on purpose — only "simple" patterns compile, and which those are is not ours to guess. + */ +const ACCEPTED: ReadonlySet<string> = new Set([ + 'type', + 'title', + 'description', + 'properties', + 'required', + 'additionalProperties', + 'items', + 'minItems', + 'enum', + 'const', + 'default', + 'anyOf', +]); + +/** What one schema costs against the request's caps. */ +export interface StrictWeight { + readonly optional: number; + readonly unions: number; +} + +/** + * `schema`'s weight when it is inside the strict subset, `undefined` when it is not: a length, + * numeric or array bound (`minItems` 0 and 1 excepted), an object not closed with + * `additionalProperties: false`, or `anyOf` beside `type` / `properties`. + */ +export function strictSubset(schema: JsonSchema): StrictWeight | undefined { + for (const key of Object.keys(schema)) if (!ACCEPTED.has(key)) return undefined; + if (schema.minItems !== undefined && schema.minItems !== 0 && schema.minItems !== 1) { + return undefined; + } + let optional = 0; + let unions = 0; + const children: JsonSchema[] = []; + if (schema.anyOf !== undefined) { + if (schema.type !== undefined || schema.properties !== undefined) return undefined; + unions += 1; + children.push(...schema.anyOf); + } + if (schema.items !== undefined) children.push(schema.items); + if (schema.type === 'object' || schema.properties !== undefined) { + if (schema.additionalProperties !== false) return undefined; + const required = new Set(schema.required ?? []); + for (const [key, child] of Object.entries(schema.properties ?? {})) { + if (!required.has(key)) optional += 1; + children.push(child); + } + } + for (const child of children) { + const weight = strictSubset(child); + if (weight === undefined) return undefined; + optional += weight.optional; + unions += weight.unions; + } + return { optional, unions }; +} + +/** + * The request's tools as this wire takes them: `strict` kept where the tool asked for it, its + * schema is inside the subset, and the request stays under all three caps — granted in request + * order, so the same tools always get the same flags (the tools are a cached prefix). A tool + * without the flag is sent whole and validated by its own schema on the way back, as every tool + * call already is. + */ +export function anthropicTools(tools: readonly LlmTool[]): readonly LlmTool[] { + let strict = 0; + let optional = 0; + let unions = 0; + return tools.map((tool) => { + const { strict: asked, ...rest } = tool; + const weight = asked === true ? strictSubset(tool.input_schema) : undefined; + if ( + weight === undefined || + strict + 1 > MAX_STRICT_TOOLS || + optional + weight.optional > MAX_STRICT_OPTIONAL || + unions + weight.unions > MAX_STRICT_UNIONS + ) { + return rest; + } + strict += 1; + optional += weight.optional; + unions += weight.unions; + return tool; + }); +} diff --git a/packages/auth/CLAUDE.md b/packages/auth/CLAUDE.md index 8d523c01c..b284b8d0b 100644 --- a/packages/auth/CLAUDE.md +++ b/packages/auth/CLAUDE.md @@ -100,7 +100,8 @@ A rule marked `†` has its full text in [`docs/history/auth-rules.md`](../../do - **One sign-in route implementation** (`identity-provider-route-core.ts`) at `/auth/sso/:provider[/callback]` (the callback movable only by `callbackPath`); failure is coded JSON, success a 303 to `successPath`. † - **A built-in callback hands `X_MFA_REQUIRED` on by `mfaPath` only**: 303 + the challenge in - `__Host-x_mfa` (`mfa-handoff.ts`), read by `readMfaChallenge(request)`. Never a URL, body or log + `__Host-x_mfa` (`mfa-handoff.ts`, the ONE challenge cookie: `mfaChallengeOf`, `mfaChallengeCookie`, + `readMfaChallenge`, `clearMfaChallengeCookie`, `MFA_CHALLENGE_COOKIE` — all public). Never a URL, body or log line. No `mfaPath` → 401 with the `mfaPath` fix; a non-local path is `X_CONFIG_INVALID`. - Refresh is **not implemented**, so the framework **stores no provider token**: `accountFor` (`oauth-login.ts`) writes `accessToken: null, refreshToken: null`. The columns and `AuthAccount` diff --git a/packages/auth/README.md b/packages/auth/README.md index 342c14e64..b50c6827b 100644 --- a/packages/auth/README.md +++ b/packages/auth/README.md @@ -603,6 +603,39 @@ The challenge travels in that cookie and nowhere else: never the redirect URL, a log line. An absent or stale cookie is `readMfaChallenge(request) === null`, and `completeMfa` refuses it like any other bad challenge. +**One challenge cookie, both halves public, `As of 2026-11-19`.** A sign-in handler of your own +(a password form over `login()`) carries its challenge in the same cookie the built-in callbacks +write, so one second-factor page serves every first leg: + +| Export | What it is | +|---|---| +| `mfaChallengeOf(error)` | the sealed challenge of an `X_MFA_REQUIRED`, `null` for every other throw | +| `mfaChallengeCookie(challenge)` | the `Set-Cookie` line that holds it: `__Host-x_mfa`, `HttpOnly; Secure; Path=/; SameSite=Lax`, `Max-Age` the challenge's own five minutes | +| `readMfaChallenge(request)` | the held challenge, or `null` | +| `clearMfaChallengeCookie()` | the `Set-Cookie` line that drops it, sent with the response that finishes the second leg | +| `MFA_CHALLENGE_COOKIE` | the cookie's name, for a test that builds a `cookie:` header or asserts a `Set-Cookie` | + +```ts +import { type Auth, login, mfaChallengeCookie, mfaChallengeOf } from '@ultimat3/auth'; + +declare const auth: Auth; + +/** The first leg: a session, or the challenge held for `/sign-in/mfa`. */ +export async function signIn(email: string, password: string, ip: string): Promise<Response> { + const headers = new Headers(); + try { + headers.append('set-cookie', (await login(auth, { email, password, ip })).cookie); + headers.set('location', '/app'); + } catch (error) { + const challenge = mfaChallengeOf(error); + if (challenge === null) throw error; + headers.append('set-cookie', mfaChallengeCookie(challenge)); + headers.set('location', '/sign-in/mfa'); + } + return new Response(null, { status: 303, headers }); +} +``` + | `completeMfa` is given | Answer | |---|---| | a live challenge and the current code, or an unused recovery code | `{ actor, session, token, cookie }`, `mfaSatisfied: true` | diff --git a/packages/auth/src/index.test.ts b/packages/auth/src/index.test.ts index ae06449d6..a6a7d6a6b 100644 --- a/packages/auth/src/index.test.ts +++ b/packages/auth/src/index.test.ts @@ -3,6 +3,7 @@ import { describe, expect, test } from 'bun:test'; import * as auth from './index'; +import * as handoff from './mfa-handoff'; import { BUILTIN_OAUTH_PROVIDER_IDS as declared } from './oauth-builtins'; describe('@ultimat3/auth public surface', () => { @@ -10,6 +11,19 @@ describe('@ultimat3/auth public surface', () => { expect(auth.BUILTIN_OAUTH_PROVIDER_IDS).toBe(declared); }); + // One MFA challenge cookie: an app's own first leg (a password form) writes the cookie the + // built-in callbacks write, so the write half is public beside the read half. + test('re-exports the whole MFA challenge cookie set: name, of, write, read, clear', () => { + expect(auth.MFA_CHALLENGE_COOKIE).toBe(handoff.MFA_CHALLENGE_COOKIE); + expect(auth.mfaChallengeOf).toBe(handoff.mfaChallengeOf); + expect(auth.mfaChallengeCookie).toBe(handoff.mfaChallengeCookie); + expect(auth.readMfaChallenge).toBe(handoff.readMfaChallenge); + expect(auth.clearMfaChallengeCookie).toBe(handoff.clearMfaChallengeCookie); + const cookie = auth.mfaChallengeCookie('sealed').split(';')[0] ?? ''; + const request = new Request('https://app.test/', { headers: { cookie } }); + expect(auth.readMfaChallenge(request)).toBe('sealed'); + }); + // Apple left the built-ins in 26.0.0 (#709): it POSTs its callback, and both callback routes are // GET, so it could never complete a sign-in. An app that wants it registers its own. test('it is the two shipped ids, frozen — apple is not one of them', () => { diff --git a/packages/auth/src/index.ts b/packages/auth/src/index.ts index a5d3b9ab0..0f02c920f 100644 --- a/packages/auth/src/index.ts +++ b/packages/auth/src/index.ts @@ -217,7 +217,13 @@ export { MFA_CHALLENGE_TTL_MS, mfaChallengeRequired, } from './mfa-challenge'; -export { clearMfaChallengeCookie, readMfaChallenge } from './mfa-handoff'; +export { + clearMfaChallengeCookie, + MFA_CHALLENGE_COOKIE, + mfaChallengeCookie, + mfaChallengeOf, + readMfaChallenge, +} from './mfa-handoff'; export type { PostgresTotpReplayGuard, PostgresTotpReplayGuardOptions, diff --git a/packages/cache/CLAUDE.md b/packages/cache/CLAUDE.md index 4f92074ad..848fd1788 100644 --- a/packages/cache/CLAUDE.md +++ b/packages/cache/CLAUDE.md @@ -131,7 +131,7 @@ Tier 1. Tagged caching + THE invalidation graph. an offset past live keys. `ZSCAN` returns every member present for the whole scan (the fake's `ZSCAN` keeps exactly that guarantee and nothing stronger). **Sweep BEFORE delete** (`As of 2026-11-19`): `sweepBuckets` `ZREM`s what was read (8 in flight, settled), then `unlinkAll` - `UNLINK`s one key per command, then `rejoinBuckets` `ZADD`s back, at its read score, every member + `UNLINK`s one key per command, then `rejoinBuckets` `ZADD … GT`s back (never lowering a fill's later score; Redis ≥ 6.2), at its read score, every member whose `UNLINK` was refused — into a READ bucket only if it held it. Delete-then-sweep orphaned a fill landing between the two (`redis-ordering.test.ts`). 10k members ≤ 100 sequential round trips (`roundTrips` in the fixture counts them). @@ -160,8 +160,10 @@ Tier 1. Tagged caching + THE invalidation graph. `receiveInvalidationBroadcast`; `cli` CHOOSES the bus (`runtime-cache-bus.ts`). The subscriber is its own connection, and every connect unsubscribes before it subscribes (Bun keeps the old listener: a bare re-subscribe delivers twice) — `redis-pubsub.test.ts`. The inbound half cannot - re-emit (only it passes `emit: false`), and **skips a shared read tier** — one with a `fence`: - the sender's bust cleared it for the fleet (`broadcast.test.ts`). The edge is still purged. An undeclared inbound tag goes to `report.errors`, never a + re-emit (only it passes `emit: false`), and **skips a shared read tier only for the sender's own + scope** (`shared-scopes.ts`): a fenced tier whose `CacheTier.scope` (redis: its namespace, per + build) equals what the frame's `SharedTierScopes` names. No scope on either side, or another + build's, is a bust — a rolling deploy's two namespaces each need theirs (`broadcast.test.ts`). The edge is still purged. An undeclared inbound tag goes to `report.errors`, never a throw. - **A `cdn` tier holding `noopPurgeDriver()` reports `skipped`, never keys** (`isNoopPurgeDriver`, in `cdn.ts`). **`report.cdn` is what depends; `report.tiers` is what cleared** — `busted` is built @@ -227,6 +229,7 @@ Tier 1. Tagged caching + THE invalidation graph. | `purge-cloudflare.ts` | `cloudflarePurgeDriver`: cache-tag purge, `purge_everything` | | `purge-env.ts` | `selectPurgeDriver`: which edge an environment purges, and nothing else | | `invalidate.ts` | the single entry point, `InvalidationReport`, and the `cache.invalidate` event | +| `shared-scopes.ts` | which shared tiers a broadcast names as cleared (`SharedTierScopes`), and which a receiver may skip | | `cache-events-fixture.ts` | tests only: `recordCacheEvents()`, the `cache.*` events a test caused | | `semantic.ts` | embedding cache for LLM calls | diff --git a/packages/cache/README.md b/packages/cache/README.md index 8c070c5fe..a8d7979a7 100644 --- a/packages/cache/README.md +++ b/packages/cache/README.md @@ -294,7 +294,7 @@ pod whose clock runs ahead from pruning a member whose value key still lives. | read | `ZSCAN … COUNT 1000` (`BUST_PAGE_SIZE`), buckets concurrently | a page per round trip; returns every member present for the whole scan, so a concurrent prune or re-score skips nothing — a score/offset cursor did | | sweep | `ZREM` of what was read, 1,000 members per command, 8 in flight | — | | delete | `UNLINK` per value key, 1,024 per burst | `UNLINK` frees off the server's main thread | -| re-join | `ZADD` back, at its read score, each member whose `UNLINK` was refused | only on a refusal | +| re-join | `ZADD … GT` back, at its read score unless a fill since scored it later, each member whose `UNLINK` was refused (Redis ≥ 6.2) | only on a refusal | 10k members clear in 25 sequential round trips (≤ 100 is the test). Every command names **one key**, so a bust is slot-local on Redis Cluster and Dragonfly whatever tags it carries; @@ -435,8 +435,13 @@ bus.subscribe('cache.invalidate', (wireTags) => receiveInvalidationBroadcast(wir The inbound half **cannot** re-emit, and that is structural rather than a flag: `emit` lives on the private fan-out options and `receiveInvalidationBroadcast` is the only caller that passes `false`. A receiver that re-broadcast would be a storm bounded by nothing. Inbound, a **shared** read tier -(one with a `fence`, as `redisTier` has) is skipped, `As of 2026-11-19`: the sender's own bust -cleared it for every replica, and a second bust per replica deleted what readers had refilled since. +(one with a `fence`, as `redisTier` has) is skipped, `As of 2026-11-19`, **only when the sender +cleared the same keys**: `fn`'s second argument (`SharedTierScopes`, tier name → `CacheTier.scope`, +the Redis namespace — per build) names what its bust cleared, the frame carries it, and +`receiveInvalidationBroadcast(wireTags, sender)` skips a fenced tier whose `scope` equals the +sender's. Another build's frame on a rolling deploy (`x:v1` vs `x:v2`), a frame naming no scope (an +older pod), or a fenced tier with no `scope` is busted — a skipped bust is a stale row for the TTL. +Within one build, a second bust per replica deleted what readers had refilled since. The in-process tiers and the edge are still cleared. A failed send lands in `report.errors` under `tier: "broadcast"` and the write that triggered the bust still succeeds. What happens to that bust is the sender's (`@ultimat3/cli` keeps the refused tags, bounded, and diff --git a/packages/cache/src/broadcast.test.ts b/packages/cache/src/broadcast.test.ts index 5d2698083..40bf340de 100644 --- a/packages/cache/src/broadcast.test.ts +++ b/packages/cache/src/broadcast.test.ts @@ -84,7 +84,8 @@ describe('cross-instance invalidation', () => { await shared.set('feed', ['fresh'], { tags: [tag('post', '1')] }); server.sent.length = 0; - const report = await receiveInvalidationBroadcast(['post:1']); + // `tierFor` opts out of the build id: its namespace is the bare prefix, `x`. + const report = await receiveInvalidationBroadcast(['post:1'], { redis: 'x' }); expect(await lru.get('feed')).toBeUndefined(); expect(server.sent).toEqual([]); @@ -92,6 +93,73 @@ describe('cross-instance invalidation', () => { expect(report.tiers.map((entry) => entry.tier)).toEqual(['lru']); }); + // A rolling deploy: old pods read `x:v1:*`, new ones `x:v2:*`, on ONE server. A write on a new + // pod busts `x:v2` only; skipping the shared tier here left the old pod serving `x:v1`'s + // pre-write row, re-promoted into its LRU, for the whole TTL. + test("an inbound broadcast from another build still clears this build's shared tier", async () => { + const server = fakeRedis(); + const shared = tierFor(server, { buildId: 'v1' }); + registerTier(shared); + await shared.set('feed', ['pre-write'], { tags: [tag('post', '1')] }); + + const report = await receiveInvalidationBroadcast(['post:1'], { redis: 'x:v2' }); + + expect(await shared.get('feed')).toBeUndefined(); + expect(report.tiers.map((entry) => entry.tier)).toEqual(['redis']); + }); + + // An older pod's frame names no scope: it cannot say which keys its bust cleared, so every tier + // is cleared, as before the skip existed. + test('an inbound broadcast that names no sender scope clears the shared tier', async () => { + const server = fakeRedis(); + const shared = tierFor(server, { buildId: 'v1' }); + registerTier(shared); + await shared.set('feed', ['pre-write'], { tags: [tag('post', '1')] }); + + await receiveInvalidationBroadcast(['post:1']); + + expect(await shared.get('feed')).toBeUndefined(); + }); + + test('the outbound broadcast names the shared scope its bust cleared', async () => { + registerTier(lruTier({ maxBytes: 10_000, defaultTtlMs: 3_600_000 })); + registerTier(tierFor(fakeRedis(), { buildId: 'v7' })); + const scopes: unknown[] = []; + registerInvalidationBroadcast((_wire, sender) => { + scopes.push(sender); + }); + + await invalidateTags([tag('post', '1')]); + + expect(scopes).toEqual([{ redis: 'x:v7' }]); + }); + + // The peers skip what the sender names, so it names only what its bust actually cleared. + test('a shared tier whose bust was refused here is not named to the peers', async () => { + const shared = tierFor(fakeRedis(), { buildId: 'v7' }); + registerTier({ ...shared, invalidateTags: () => Promise.reject(new TypeError('timeout')) }); + const scopes: unknown[] = []; + registerInvalidationBroadcast((_wire, sender) => { + scopes.push(sender); + }); + + await invalidateTags([tag('post', '1')]); + + expect(scopes).toEqual([{}]); + }); + + // A fenced tier that names no scope cannot be proven the sender's: it is cleared. + test('a fenced tier with no scope of its own is cleared inbound whatever the sender names', async () => { + const server = fakeRedis(); + const { scope: _omitted, ...unscoped } = tierFor(server); + registerTier(unscoped); + await unscoped.set('feed', ['pre-write'], { tags: [tag('post', '1')] }); + + await receiveInvalidationBroadcast(['post:1'], { redis: 'x' }); + + expect(await unscoped.get('feed')).toBeUndefined(); + }); + test('a LOCAL bust still clears the shared tier', async () => { const server = fakeRedis(); const shared = tierFor(server); diff --git a/packages/cache/src/index.ts b/packages/cache/src/index.ts index 4f0ac0bce..494c7b993 100644 --- a/packages/cache/src/index.ts +++ b/packages/cache/src/index.ts @@ -86,6 +86,7 @@ export type { SemanticRememberOptions, } from './semantic'; export { memorySemanticCache } from './semantic'; +export type { SharedTierScopes } from './shared-scopes'; export type { CacheTag, CacheTagRegistry, TagFactory } from './tags'; export { assertKnownTags, diff --git a/packages/cache/src/invalidate.ts b/packages/cache/src/invalidate.ts index e2745d8a9..c3f3ba298 100644 --- a/packages/cache/src/invalidate.ts +++ b/packages/cache/src/invalidate.ts @@ -17,6 +17,8 @@ import { import { markAllInvalidated, markInvalidated } from './fence'; import { dependentsOfKind, graphSnapshot } from './graph'; import { logPartial, resetPartialLog } from './partial-log'; +import type { SharedTierScopes } from './shared-scopes'; +import { clearedBySender, sharedScopes } from './shared-scopes'; import type { CacheTag } from './tags'; import { assertKnownTags, knownTags, parseTag, serializeTags } from './tags'; import type { CacheTier, TierInvalidation } from './tiers'; @@ -46,7 +48,14 @@ export const EVERY_TAG = 'every-tag'; * on pod 3, their next request lands on pod 7, and pod 7's in-process copy serves the pre-edit * value for up to `defaultTtlMs`. The user watches their edit vanish and re-submits. */ -export type InvalidationBroadcast = (wireTags: readonly string[]) => Promise<void> | void; +export type InvalidationBroadcast = ( + wireTags: readonly string[], + /** + * What this process's own bust cleared in each shared tier: carry it to the peers. The fan-out + * always passes it; optional in the type so the 31.48 shape stays compatible. + */ + sender?: SharedTierScopes, +) => Promise<void> | void; export interface InvalidationReport { readonly tags: readonly string[]; @@ -159,7 +168,11 @@ export function invalidateTags(tags: readonly CacheTag[]): Promise<InvalidationR * pods know an entity the old ones do not, and a throw here kills the subscriber loop that * delivered it — which would silently end cross-instance invalidation for the whole process. */ -export function receiveInvalidationBroadcast(wire: readonly string[]): Promise<InvalidationReport> { +export function receiveInvalidationBroadcast( + wire: readonly string[], + /** The sender's `SharedTierScopes`; omitted (an older pod's frame), every tier is cleared. */ + sender?: SharedTierScopes, +): Promise<InvalidationReport> { const declared = new Set(knownTags()); const errors: { tier: string; message: string }[] = []; const accepted: CacheTag[] = []; @@ -169,7 +182,13 @@ export function receiveInvalidationBroadcast(wire: readonly string[]): Promise<I if (declared.size === 0 || declared.has(parsed.entity)) accepted.push(parsed); else errors.push({ tier: 'broadcast', message: `ignored undeclared tag "${value}"` }); } - return fanOut(accepted, { source: 'cache.broadcast', emit: false, validate: false, errors }); + return fanOut(accepted, { + source: 'cache.broadcast', + emit: false, + validate: false, + errors, + ...(sender === undefined ? {} : { sender }), + }); } interface FanOutOptions { @@ -180,6 +199,8 @@ interface FanOutOptions { /** The local path throws on a typo; the inbound one has already filtered instead. */ readonly validate: boolean; readonly errors: { tier: string; message: string }[]; + /** Inbound only: the shared scopes the sender's own bust already cleared. */ + readonly sender?: SharedTierScopes; } function fanOut(tags: readonly CacheTag[], options: FanOutOptions): Promise<InvalidationReport> { @@ -206,13 +227,10 @@ function fanOut(tags: readonly CacheTag[], options: FanOutOptions): Promise<Inva // report says every tier cleared, and the LRU is stale again before the call returns. // The EDGE is not one of them here: it is purged last, below (`purgeEdge`). const farthestFirst = [...sortTiers(registry)].reverse(); - // Inbound, a SHARED read tier is skipped: the sender's own bust cleared it for the fleet, and - // a second one per replica deletes what readers refilled since and re-fences their fills. A - // tier is shared when it keeps a fleet fence (`CacheTier.fence`, omitted in-process) — the - // positive declaration, so an app tier that says nothing is still cleared. The edge is not - // skipped: a peer's purge after its own drop is the one that holds (`purgeEdgeAgain`). + // Inbound, a shared tier the sender's own bust already cleared is skipped (`clearedBySender`). + // The edge is not: a peer's purge after its own drop is the one that holds (`purgeEdgeAgain`). const readTiers = farthestFirst.filter( - (one) => !isEdgeTier(one) && (emit || one.fence === undefined), + (one) => !isEdgeTier(one) && (emit || !clearedBySender(one, options.sender)), ); for (const tier of readTiers) { try { @@ -259,7 +277,11 @@ function fanOut(tags: readonly CacheTag[], options: FanOutOptions): Promise<Inva // to "the other pods clear on TTL" rather than failing the write that triggered the bust. if (emit && wire.length > 0 && broadcast !== undefined) { try { - await broadcast(wire); + // Only what ANSWERED: a shared tier whose bust was refused here is the peers' to clear. + await broadcast( + wire, + sharedScopes(farthestFirst.filter((one) => cleared.includes(one.name))), + ); cleared.push('broadcast'); } catch (error) { errors.push({ tier: 'broadcast', message: renderThrowable(error) }); diff --git a/packages/cache/src/redis-buckets.ts b/packages/cache/src/redis-buckets.ts index 505d83e39..6dca67322 100644 --- a/packages/cache/src/redis-buckets.ts +++ b/packages/cache/src/redis-buckets.ts @@ -249,7 +249,9 @@ export async function rejoinBuckets( for (const [bucket, members] of removed) { for (const member of members) { const score = survivors.get(member); - if (score !== undefined) sends.push(client.send('ZADD', [bucket, score, member])); + // `GT` (Redis 6.2+): a fill that re-joined since, at a LATER score, keeps it. The read score + // written over it made the membership prunable while the fill's value still lived. + if (score !== undefined) sends.push(client.send('ZADD', [bucket, 'GT', score, member])); } } const settled = await Promise.allSettled(sends); diff --git a/packages/cache/src/redis-fake-fixture.ts b/packages/cache/src/redis-fake-fixture.ts index c8e258f60..3e49ba7cc 100644 --- a/packages/cache/src/redis-fake-fixture.ts +++ b/packages/cache/src/redis-fake-fixture.ts @@ -118,9 +118,13 @@ export function fakeRedis(): FakeRedis { return remove(key); case 'ZADD': { const zset = zsetOf(key); - for (let i = 1; i + 1 < args.length; i += 2) { + // `GT` (Redis 6.2): a held member only ever moves UP; a missing one is still added. + const gt = args[1] === 'GT'; + for (let i = gt ? 2 : 1; i + 1 < args.length; i += 2) { const score = Number(args[i]); const member = String(args[i + 1]); + const held = zset.get(member); + if (gt && held !== undefined && held >= score) continue; // A re-scored member may have been the floor; recompute rather than guess. if (zset.has(member)) floors.delete(key); const seen = logged.get(key) ?? new Set<string>(); diff --git a/packages/cache/src/redis-ordering.test.ts b/packages/cache/src/redis-ordering.test.ts index 0c659c824..686bf059d 100644 --- a/packages/cache/src/redis-ordering.test.ts +++ b/packages/cache/src/redis-ordering.test.ts @@ -88,6 +88,37 @@ describe('a bust racing a write, on the wire', () => { expect(client.members('x:e2:{post}')).toEqual(['x:c:stuck']); }); + // A fill lands between the sweep and the refused UNLINK, re-joining at a LATER score. Re-joined + // at the scanned score, the membership became prunable at the old expiry while the fill's value + // lived on — a live value no tag reaches until it expires. + test("a refused delete re-joined after a fill keeps the fill's later score", async () => { + const server = fakeRedis(); + const clock = frozenClock(1_000_000); + let busy: (() => Promise<void>) | undefined; + const busting: RedisLike = { + get: (key) => server.get(key), + set: (key, value) => server.set(key, value), + async send(command, args) { + const fill = busy; + if (command === 'UNLINK' && fill !== undefined) { + busy = undefined; + await fill(); + } + return await server.send(command, args); + }, + }; + const tier = tierFor(busting, { clock }); + await tier.set('k', 'v1', { ttlMs: 300_000, tags: [tag('post', '1')] }); + clock.advance(100_000); + server.refuseDel('x:c:k'); + busy = () => tier.set('k', 'v2', { ttlMs: 300_000, tags: [tag('post', '1')] }); + + await expect(tier.invalidateTags([tag('post', '1')])).rejects.toThrow('redis refused UNLINK'); + + const fillScore = String(1_100_000 + 300_000 + TAG_GRACE_MS); + expect(await server.send('ZSCORE', ['x:t2:{post}:1', 'x:c:k'])).toBe(Number(fillScore)); + }); + test("a fill that lands between a bust's delete and its sweep is still reached by the next bust of the same tag", async () => { // Another replica's fill (its fence sampled after the bump, so a valid fresh value) lands // right after this bust's UNLINK. A sweep that ran AFTER the delete removed the member the diff --git a/packages/cache/src/redis.live.test.ts b/packages/cache/src/redis.live.test.ts index 63f469d0d..5a3712f94 100644 --- a/packages/cache/src/redis.live.test.ts +++ b/packages/cache/src/redis.live.test.ts @@ -15,7 +15,7 @@ import { redisClient } from '@ultimat3/core/redis'; import { lruTier } from './lru'; import type { RedisLike } from './redis'; import { redisTier } from './redis'; -import { BUST_PAGE_SIZE, TAG_GRACE_MS } from './redis-buckets'; +import { BUST_PAGE_SIZE, rejoinBuckets, TAG_GRACE_MS } from './redis-buckets'; import { tag } from './tags'; import type { CacheTier } from './tiers'; import { cacheStack, nowMs } from './tiers'; @@ -213,6 +213,24 @@ describe.skipIf(!hasRedis)( expect(await tier.get('raced')).toBeUndefined(); }); + // `ZADD … GT` is Redis 6.2: the fake models it, this proves the server takes it — a later + // score is kept, and a member the bucket lost is still added back. + test("a refused delete's re-join never lowers a score, and still re-adds a missing member", async () => { + const client = raw(); + const bucket = `${PREFIX}:t2:{post}:rejoin`; + await reply(client, 'ZADD', [bucket, '2000', 'refilled']); + const removed = new Map([[bucket, new Set(['refilled', 'gone'])]]); + const survivors = new Map([ + ['refilled', '1000'], + ['gone', '1000'], + ]); + + expect(await rejoinBuckets(client, removed, survivors)).toEqual([]); + + expect(Number(await reply(client, 'ZSCORE', [bucket, 'refilled']))).toBe(2000); + expect(Number(await reply(client, 'ZSCORE', [bucket, 'gone']))).toBe(1000); + }); + test('a fresh bucket comes out of the join with a lease, never immortal', async () => { const client = raw(); const tier = tierOn(client); diff --git a/packages/cache/src/redis.ts b/packages/cache/src/redis.ts index 03ddf849c..f65ae1337 100644 --- a/packages/cache/src/redis.ts +++ b/packages/cache/src/redis.ts @@ -289,6 +289,9 @@ export function redisTier(options: RedisTierOptions = {}): CacheTier { /** The fleet-wide half of the fill fence: generations other replicas' busts move. */ fence: (scope: FenceScope) => sampleGenerations(conn(), ns, clock, scope), + /** The namespace a bust sweeps — per build by default, so two builds are two scopes. */ + scope: ns, + /** * Read every bucket the tags match, a page per round trip and the buckets concurrently; `ZREM` * what they held; THEN `UNLINK` it, one key per command; and re-join any member whose value diff --git a/packages/cache/src/shared-scopes.ts b/packages/cache/src/shared-scopes.ts new file mode 100644 index 000000000..4eac1527a --- /dev/null +++ b/packages/cache/src/shared-scopes.ts @@ -0,0 +1,32 @@ +// Which shared tiers a cross-instance broadcast names as already cleared, and which of them a +// receiver may therefore skip. Kept apart from the fan-out so the skip rule has one home. + +import type { CacheTier } from './tiers'; + +/** + * Shared tier name → the `CacheTier.scope` a bust cleared there. A broadcast carries the sender's, + * so a receiver skips only the shared tiers whose keys the sender's own bust already reached: on a + * rolling deploy the two builds' Redis namespaces differ, and each must still be busted. + */ +export type SharedTierScopes = Readonly<Record<string, string>>; + +/** What this process's bust clears in each shared tier — the `sender` its broadcast carries. */ +export function sharedScopes(tiers: readonly CacheTier[]): SharedTierScopes { + const scopes: Record<string, string> = {}; + for (const tier of tiers) { + if (tier.fence !== undefined && tier.scope !== undefined) scopes[tier.name] = tier.scope; + } + return scopes; +} + +/** + * Inbound, a SHARED read tier is skipped only when the sender's bust reached the very keys this + * one holds: same tier, same `scope`. A second bust per replica deleted what readers refilled + * since and re-fenced their fills. Any doubt clears it — a frame naming no scope (an older pod), + * another build's namespace on a rolling deploy, a fenced tier with no `scope` — because a skipped + * bust is a pre-write row for the whole TTL, and a needless one is one more load. + */ +export function clearedBySender(tier: CacheTier, sender: SharedTierScopes | undefined): boolean { + if (tier.fence === undefined || tier.scope === undefined || sender === undefined) return false; + return Object.hasOwn(sender, tier.name) && sender[tier.name] === tier.scope; +} diff --git a/packages/cache/src/tiers.ts b/packages/cache/src/tiers.ts index 03583e57b..6a4baab15 100644 --- a/packages/cache/src/tiers.ts +++ b/packages/cache/src/tiers.ts @@ -213,6 +213,13 @@ export interface CacheTier { * may never be told about — still stops the fill (`tier-fence.ts`). Omitted by in-process tiers. */ fence?(scope: FenceScope): Promise<TierFence>; + /** + * Which entries this tier's bust clears, as a string a peer can compare: two tiers of one name + * and one `scope` hold the same keys (`redisTier`: its namespace, so per build). Only read beside + * `fence`: an inbound broadcast skips a fenced tier ONLY when the sender named this same scope — + * omitted, the tier is cleared on every inbound broadcast. + */ + readonly scope?: string; /** * Drop every entry — implemented ONLY by a tier whose store is this process's own heap (`lru`). * `flushProcessTiers()` calls it when the process cannot know which busts it missed. A shared diff --git a/packages/cli/README.md b/packages/cli/README.md index ef1394842..d1daa80d7 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -41,7 +41,7 @@ Commands and the `x verify` step count, `As of 2026-08`: | `x secrets show\|init\|edit\|set\|rotate` | the committed encrypted secrets | decrypted into the `envSchema` variables of the same names | | `x policy list\|explain <subject>` | which clause decided a permission, and why | five packages print `x policy explain` as a denial's `fix:` | | `x i18n check\|add\|sync` | catalogs: gaps, a new locale, key sync | all three of i18n's own error fixes name it | -| `x errors explain <CODE>` / `list` | the error table, programmatically | refuses an unregistered code instead of inventing one | +| `x errors explain <CODE>` / `list` | the error table, programmatically | refuses an unregistered code instead of inventing one. An app's own `defineError()` code answers inside the app from the registry alone: title, HTTP status (`null`: off-socket) and the declaring `file:line` — no `cause`/`fix`, which only a throw has (`As of 2026-11-19`) | | `x repro <id> [--write] [--verify]` / `--list` / `--from` | a dead job or a captured 5xx as a red test in `repro/` | `--verify` answers `{ reproduced, code, fingerprint }`; a mismatch is `X_REPRO_NOT_REPRODUCED`, never a crash | | `x repro <id> --bundle` | the failure as one redacted `repro/bundle-<id>.json` for an issue | secrets masked, env values / hostnames / paths replaced; `bunx create-ultimate repro <file>` opens it | | `x docs "<question>"` | the framework docs and the wiki, offline | answered from the installed packages and the `wiki/` this tarball ships (`prepack`: `scripts/pack-cli-wiki.ts`), never the network; `x docs Upgrading#<anchor>` prints one whole section | @@ -203,6 +203,8 @@ its name like any guard. | `parse.ts` | flags, subcommands, `--json`, `--help`, suggestions | | `flag-number.ts` | the one integer-flag reader — `--port`, `--workers`, `--shard` | | `shell-quote.ts` | the one POSIX quoter for a value pasted into a `fix:` or a reproduce line | +| `stop-run-start.ts` | the one `x stop --json && x <command> && x dev` fix line (`stopRunStartFix`); `stop-run-start.test.ts` refuses a hand-built one | +| `db-dev-wire.ts` | the `/_x/db` paths and the `--steps` rule, import-free, read by the dev routes and the `x db` clients; `db-dev-wire.test.ts` refuses a restated literal | | `output.ts` | one data shape, two renderers, the 3-line error format | | `registry.ts` | the one command list | | `generate-kinds.ts` | which generators exist, and how a command line names one | @@ -287,6 +289,10 @@ lints and runs what both shapes leave; `e2e/sign-in.e2e.test.ts` signs in to a p Both shapes ship the second leg, `As of 2026-11`: `--oidc` hands `oauthLogin` `mfaPath: '/auth/sign-in/second-factor'` and writes that page, `actions/confirm-session.ts` and a `sign-in-challenge.ts` that reads auth's `__Host-x_mfa` cookie through `readMfaChallenge`. +One challenge cookie for both shapes, `As of 2026-11-19`: `--password` holds its challenge in the +same cookie through auth's `mfaChallengeOf` / `mfaChallengeCookie` (`templates/sign-in-challenge.ts` +writes both shapes' module); no generated file names a cookie. An app generated before keeps its own +`x_mfa_challenge` code — that file is the app's, and nothing in the framework reads it. ## Beside a running `x dev` (embedded database) diff --git a/packages/cli/src/cmd-db-rollback.ts b/packages/cli/src/cmd-db-rollback.ts index 098e10d24..aeb0ae51f 100644 --- a/packages/cli/src/cmd-db-rollback.ts +++ b/packages/cli/src/cmd-db-rollback.ts @@ -4,6 +4,7 @@ import { isNonTransactional } from '@ultimat3/db'; import type { CommandContext } from './command'; +import { ROLLBACK_STEPS } from './db-dev-wire'; import { stepFinding } from './db-finding'; import { rollbackPass } from './db-rollback-pass'; import { intFlagOr } from './flag-number'; @@ -11,19 +12,12 @@ import { msg } from './messages'; import { MIGRATIONS_DIR, readMigrations } from './migrations'; import type { CommandResult } from './output'; -/** Read before anything is opened: `--steps 0` and `--steps all` never reach the ledger. */ -const STEPS = { - name: 'steps', - command: 'db rollback', - min: 1, - example: 'x db rollback --steps 1', -} as const; - export async function runRollbackCommand( ctx: CommandContext, root: string, ): Promise<CommandResult> { - const steps = intFlagOr(ctx.args, STEPS, 1); + // Read before anything is opened: `--steps 0` and `--steps all` never reach the ledger. + const steps = intFlagOr(ctx.args, ROLLBACK_STEPS, 1); let reverted: readonly string[]; try { reverted = await rollbackPass(root, ctx.env, steps); diff --git a/packages/cli/src/cmd-errors-app.test.ts b/packages/cli/src/cmd-errors-app.test.ts index 6637bbc14..b45061dcd 100644 --- a/packages/cli/src/cmd-errors-app.test.ts +++ b/packages/cli/src/cmd-errors-app.test.ts @@ -63,18 +63,52 @@ const rejected = async (call: Promise<unknown>): Promise<{ code: string; fix: st )) as { code: string; fix: string }; describe('unit · x errors explain answers the app’s own codes', () => { - test('inside the app: title, cause, fix, status and where it is declared', async () => { + test('inside the app: title, status and where it is declared, from the registry', async () => { const result = await run(['errors', 'explain', 'X_TICKET_NOT_FOUND', '--json'], await app()); expect(result.ok).toBe(true); - expect(result.data).toMatchObject({ + expect(result.data).toEqual({ code: 'X_TICKET_NOT_FOUND', title: 'no such ticket', status: 404, - fix: 'x queries list --json, then pass an id the ticket read returns', + docs: expect.any(String), site: { at: ERRORS, line: 4 }, }); - expect(String((result.data as { cause: string }).cause)).toContain('no ticket with id'); - expect(result.lines?.join('\n')).toContain('x queries list --json'); + expect(result.lines?.join('\n')).toContain(`${ERRORS}:4`); + expect(result.lines?.join('\n')).toContain('404'); + }, 30_000); + + // The registry holds a title and a status, never a cause or a fix: those are functions of params + // only a throw has. A declaration no source reader could parse answers exactly as a plain one. + test('a declaration whose cause and fix are not literals answers the same fields', async () => { + const dir = await app(); + await Bun.write( + join(dir, 'apps/web/app/refund/errors.ts'), + `import { defineError } from ${JSON.stringify(import.meta.resolve('@ultimat3/core/page'))}; + +const FIX = 'x queries list --json'; +const why = (id: string): string => \`refund \${id} holds a \\\` and a }); in its text\`; + +export const RefundRefusedError = defineError<{ readonly id: string }>({ + code: 'X_REFUND_REFUSED', + title: 'refund refused', + offSocket: true, + cause: (input) => why(input.id), + fix: FIX, +}); +`, + ); + const result = await run(['errors', 'explain', 'X_REFUND_REFUSED', '--json'], dir); + expect(result.data).toEqual({ + code: 'X_REFUND_REFUSED', + title: 'refund refused', + status: null, + docs: expect.any(String), + site: { at: 'apps/web/app/refund/errors.ts', line: 7 }, + }); + const printed = result.lines?.join('\n') ?? ''; + expect(printed).not.toContain('cause:'); + expect(printed).not.toContain('fix:'); + expect(printed).not.toContain('grep'); }, 30_000); test('a code the app does not declare is still unknown, and the fix says where codes live', async () => { diff --git a/packages/cli/src/cmd-errors-app.ts b/packages/cli/src/cmd-errors-app.ts index 0b004c2eb..44b91ea56 100644 --- a/packages/cli/src/cmd-errors-app.ts +++ b/packages/cli/src/cmd-errors-app.ts @@ -1,54 +1,29 @@ // `x errors explain` for a code the APP declares with `defineError()` (`x g resource` writes one per -// slice). Loading the app registers it; its cause and fix are read off the declaration's own text, -// never by constructing the error — a cause is a function of params nobody has here. +// slice). Loading the app registers it, and the answer is the registry's alone: title and status. +// A cause and a fix are functions of params only a throw has, so the declaring line is named instead. import { describeErrorCode, ERROR_DOCS_URL, hasErrorCode, UltimateError } from '@ultimat3/core'; import { definedErrorStatus } from '@ultimat3/core/internal/error-status'; import { loadApp } from './app-load'; import { findAppRoot } from './app-root'; +import { collectDeclaredCodes } from './error-contract'; import { quoteArg } from './shell-quote'; -/** What an app code answers: the explanation's fields, plus the HTTP status and the declaring line. */ +/** What an app code answers: what the registry holds for it, and the line that declares it. */ export interface AppCodeExplanation { readonly code: string; readonly title: string; - readonly cause: string; - readonly fix: string; readonly docs: string; /** `null` for an `offSocket` declaration. */ readonly status: number | null; readonly site: { readonly at: string; readonly line: number } | null; } -/** A quoted literal — the three quotes a declaration may use — captured without its quotes. */ -const LITERAL = String.raw`(['"\x60])((?:\\.|(?!\1)[^\\])*)\1`; - -/** `key: '…'`, or `key: (params) => \`…\``, inside the declaration's text. */ -const fieldOf = (block: string, key: string): string | undefined => - new RegExp(String.raw`\b${key}:\s*(?:\([^)]*\)\s*=>\s*)?${LITERAL}`).exec(block)?.[2]; - -/** The declaration holding `code: '<code>'` among the app's loaded modules: file, line, its text. */ -async function declarationOf( - root: string, - files: readonly string[], - code: string, -): Promise<{ readonly at: string; readonly line: number; readonly block: string } | undefined> { - const literal = new RegExp(String.raw`\bcode:\s*['"\x60]${code}['"\x60]`); - for (const at of files) { - const text = await Bun.file(`${root}/${at}`).text(); - const found = literal.exec(text); - if (found === null) continue; - const start = text.lastIndexOf('defineError', found.index); - const end = text.indexOf('});', found.index); - const block = text.slice(start < 0 ? found.index : start, end < 0 ? undefined : end); - return { at, line: text.slice(0, found.index).split('\n').length, block }; - } - return undefined; -} - /** * The app's declaration of `code`, or `undefined`: not inside an app, the load failed, or the app - * declares no such code. The caller then refuses with `AppCodeUnknownError`. + * declares no such code. The caller then refuses with `AppCodeUnknownError`. The site is the + * `errors` step's own answer to "where is this code declared" (`collectDeclaredCodes`), never a + * second reading of the declaration. */ export async function explainAppCode( code: string, @@ -56,20 +31,16 @@ export async function explainAppCode( ): Promise<AppCodeExplanation | undefined> { const root = findAppRoot(cwd)?.dir; if (root === undefined) return undefined; - const app = await loadApp(root); + await loadApp(root); if (!hasErrorCode(code)) return undefined; const described = describeErrorCode(code); - const declared = await declarationOf(root, app.files, code); - const site = declared === undefined ? null : { at: declared.at, line: declared.line }; - const where = site === null ? 'this app' : `${site.at}:${site.line}`; + const declared = (await collectDeclaredCodes(root)).find((site) => site.code === code); return { code, title: described.title, - cause: `${described.title} — declared by ${where}: ${fieldOf(declared?.block ?? '', 'cause') ?? described.title}`, - fix: fieldOf(declared?.block ?? '', 'fix') ?? `grep -rn ${quoteArg(code)} apps packages`, docs: described.docs ?? ERROR_DOCS_URL, status: definedErrorStatus(code)?.status ?? null, - site, + site: declared === undefined ? null : { at: declared.at, line: declared.line }, }; } diff --git a/packages/cli/src/cmd-errors.ts b/packages/cli/src/cmd-errors.ts index 7e1e37d99..be92703ee 100644 --- a/packages/cli/src/cmd-errors.ts +++ b/packages/cli/src/cmd-errors.ts @@ -64,7 +64,7 @@ async function explainOne( explainEveryErrorCode().map((entry) => entry.code), ); const declared = await explainAppCode(code, cwd); - if (declared !== undefined) return appCodeResult(declared, reader); + if (declared !== undefined) return appCodeResult(declared); if (suggestion !== undefined) throw new ErrorCodeUnknownError({ code, suggestion }); throw new AppCodeUnknownError({ code, inApp: findAppRoot(cwd) !== undefined }); } @@ -77,13 +77,21 @@ async function explainOne( }; } -/** An app's own code: the same three lines, and its title, status and declaring line as data. */ -const appCodeResult = (declared: AppCodeExplanation, reader?: ReaderOptions): CommandResult => ({ +/** + * An app's own code: what the registry holds (title, status) and the declaring line. No `cause:` or + * `fix:` line — the registry keeps neither for a `defineError` code, and the declaration is one open + * file away. + */ +const appCodeResult = (declared: AppCodeExplanation): CommandResult => ({ ok: true, command: 'errors', summary: msg('cli.errors.explained', { code: declared.code, title: declared.title }), - lines: detailLines(declared, reader), - data: { ...declared, fix: fixForReader(declared.fix, reader) }, + lines: [ + ` status: ${declared.status ?? 'off-socket'}`, + ...(declared.site === null ? [] : [` declared: ${declared.site.at}:${declared.site.line}`]), + ` docs: ${singleLine(declared.docs)}`, + ], + data: { ...declared }, }); /** diff --git a/packages/cli/src/cmd-tasks-run.test.ts b/packages/cli/src/cmd-tasks-run.test.ts index 9bd0bf072..a88d72bbe 100644 --- a/packages/cli/src/cmd-tasks-run.test.ts +++ b/packages/cli/src/cmd-tasks-run.test.ts @@ -9,6 +9,8 @@ import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'; import { tmpdir } from 'node:os'; // why: Bun exposes no path-join primitive. import { join } from 'node:path'; +import { resolveEnvironment } from '@ultimat3/core'; +import { seedTiersFor } from '@ultimat3/entity'; import { type JobDriver, job, @@ -21,6 +23,7 @@ import { import { installJobDriver, resetJobDriver } from '@ultimat3/jobs/adapter'; import { REQUIRED_BUN } from './app-root'; import { tasksCommand } from './cmd-tasks'; +import { tasksRunNeedsFlag } from './cmd-tasks-run'; import type { CommandContext } from './command'; import { msg } from './messages'; import type { ThrownShape } from './thrown-by-fixture'; @@ -166,4 +169,21 @@ describe('unit · x tasks run', () => { expect(asked.ok).toBe(true); expect(await driver.introspect?.list({})).toHaveLength(2); }); + + test("asks exactly where x db seed's production gate asks: one predicate, no second answer", () => { + for (const env of [ + {}, + { ULTIMATE_ENV: 'development' }, + { ULTIMATE_ENV: 'test' }, + { ULTIMATE_ENV: 'staging' }, + { ULTIMATE_ENV: 'production' }, + { NODE_ENV: 'production' }, + ]) { + // `x db seed` leaves `dev` fixtures out exactly where it wants the tier named. + const seedAsks = !seedTiersFor(resolveEnvironment({ env })).includes('dev'); + expect({ env, asks: tasksRunNeedsFlag(env) }).toEqual({ env, asks: seedAsks }); + } + // An `ULTIMATE_ENV` that is no environment is refused by both, never read as "not production". + expect(() => tasksRunNeedsFlag({ ULTIMATE_ENV: 'prod' })).toThrow(/X_ENVIRONMENT_INVALID/); + }); }); diff --git a/packages/cli/src/cmd-tasks-run.ts b/packages/cli/src/cmd-tasks-run.ts index 4c40b5a9c..e5a5645e8 100644 --- a/packages/cli/src/cmd-tasks-run.ts +++ b/packages/cli/src/cmd-tasks-run.ts @@ -2,7 +2,7 @@ // app's queue — so a cron job is exercised in dev without waiting for its cron or editing it. // Through the task's own manual-run path (`TaskHandle.enqueue`), the one the admin's run-now uses. -import { resolveEnvironment } from '@ultimat3/core'; +import { isProduction } from '@ultimat3/core'; import type { TaskHandle } from '@ultimat3/jobs'; import type { CommandContext } from './command'; import { refuseEmbeddedWriteBesideDev } from './dev-lock-live'; @@ -13,14 +13,22 @@ import type { CommandResult, Finding, JsonValue } from './output'; import { flagBool } from './parse'; import { quoteArg } from './shell-quote'; +/** + * Does this environment fire only when asked by name? `x db seed`'s production gate, mirrored: the + * same predicate (`ULTIMATE_ENV` resolved `production`; staging runs unasked, as a `dev` seed does; + * an `ULTIMATE_ENV` that is no environment refuses with `X_ENVIRONMENT_INVALID`), and consent is a + * flag naming what is asked for. Pinned against `seedTiersFor` by `cmd-tasks-run.test.ts`. + */ +export const tasksRunNeedsFlag = (env: Readonly<Record<string, string | undefined>>): boolean => + isProduction({ env }); + /** * Production fires only by flag. Not a scheduled occurrence: the scheduler's watermark is never * moved, so the next real tick still fires — a manual run in production is real work twice. */ function refuseUnaskedProduction(ctx: CommandContext, name: string): void { if (flagBool(ctx.args, 'production')) return; - const environment = resolveEnvironment({ env: ctx.env }); - if (environment !== 'production') return; + if (!tasksRunNeedsFlag(ctx.env)) return; throw new BadFlagError({ flag: 'production', command: 'tasks run', diff --git a/packages/cli/src/db-applied-edits.ts b/packages/cli/src/db-applied-edits.ts index f2e8d5836..2ca036273 100644 --- a/packages/cli/src/db-applied-edits.ts +++ b/packages/cli/src/db-applied-edits.ts @@ -9,6 +9,7 @@ import type { Migration } from '@ultimat3/db'; import { auditLedger, isLedgerMissing, pgliteDataDir, readLedger } from '@ultimat3/db'; import { t } from '@ultimat3/schema'; import { withOpenedDb } from './db-client-displace'; +import { DEV_LEDGER_PATH } from './db-dev-wire'; import { askDev, type PostJson, unreadable } from './db-migrate-through-dev'; import { liveDevLockChecked } from './dev-lock-live'; import { readMigrations } from './migrations'; @@ -23,9 +24,6 @@ export interface AppliedRow { readonly checksum: string; } -/** `dev-db-migrate.ts`'s path, restated: importing that module would load the route's graph. */ -const LEDGER_PATH = '/_x/db/ledger'; - const LEDGER = t.object({ ledger: t.array(t.object({ id: t.string, checksum: t.string })), }); @@ -73,7 +71,7 @@ export async function readApplied(root: string, env: Env, post?: PostJson): Prom holder, services.stateDir, { - path: LEDGER_PATH, + path: DEV_LEDGER_PATH, resume: ['db', 'gen'], read: (data) => { const parsed = LEDGER.safeParse(data); diff --git a/packages/cli/src/db-dev-wire.test.ts b/packages/cli/src/db-dev-wire.test.ts new file mode 100644 index 000000000..fb098245a --- /dev/null +++ b/packages/cli/src/db-dev-wire.test.ts @@ -0,0 +1,53 @@ +// The `/_x/db` wire has ONE spelling: the leaf both ends read. A path or the `--steps` rule +// restated in a client or a route is the drift this file refuses. + +import { describe, expect, test } from 'bun:test'; +// why: Bun ships no path API; `join` reaches each module from this directory. +import { join } from 'node:path'; +import { + DEV_LEDGER_PATH, + DEV_MIGRATE_PATH, + DEV_ROLLBACK_PATH, + ROLLBACK_STEPS, +} from './db-dev-wire'; +import { stepsOf } from './dev-db-rollback'; + +const DIR = import.meta.dir; +const LEAF = 'db-dev-wire.ts'; + +async function sources(): Promise<ReadonlyMap<string, string>> { + const found = new Map<string, string>(); + for await (const file of new Bun.Glob('*.{ts,tsx}').scan({ cwd: DIR })) { + if (file.includes('.test.') || file === LEAF) continue; + found.set(file, await Bun.file(join(DIR, file)).text()); + } + return found; +} + +describe('unit · the /_x/db wire is stated once', () => { + test('the leaf imports nothing, so a client reads it without the route’s graph', async () => { + const text = await Bun.file(join(DIR, LEAF)).text(); + expect(new Bun.Transpiler({ loader: 'ts' }).scanImports(text)).toEqual([]); + expect([DEV_MIGRATE_PATH, DEV_ROLLBACK_PATH, DEV_LEDGER_PATH]).toEqual([ + '/_x/db/migrate', + '/_x/db/rollback', + '/_x/db/ledger', + ]); + }); + + test('no other module spells a /_x/db path or the --steps rule', async () => { + const restated: string[] = []; + for (const [file, text] of await sources()) { + if (/['"`]\/_x\/db\/(?:migrate|rollback|ledger)/.test(text)) restated.push(`${file}: path`); + if (/command:\s*'db rollback'/.test(text)) restated.push(`${file}: --steps rule`); + } + expect(restated).toEqual([]); + }); + + test('the door refuses the steps the flag refuses, by the one rule', () => { + expect(ROLLBACK_STEPS.min).toBe(1); + expect(stepsOf('2')).toBe(2); + expect(() => stepsOf('0')).toThrow(); + expect(() => stepsOf(null)).toThrow(); + }); +}); diff --git a/packages/cli/src/db-dev-wire.ts b/packages/cli/src/db-dev-wire.ts new file mode 100644 index 000000000..681b33e16 --- /dev/null +++ b/packages/cli/src/db-dev-wire.ts @@ -0,0 +1,18 @@ +// The `/_x/db` wire between `x db …` and a live `x dev` holding the embedded database: the three +// paths and the `--steps` rule, stated once. Import-free on purpose — the CLI clients read it +// without loading the route's graph, and the dev routes without loading a command's. + +/** `x db migrate`, asked of the holder (`db-migrate-through-dev.ts` → `dev-db-migrate.ts`). */ +export const DEV_MIGRATE_PATH = '/_x/db/migrate'; + +/** `x db rollback` (`db-rollback-pass.ts`) and `x db gen`'s ledger read (`db-applied-edits.ts`). */ +export const DEV_ROLLBACK_PATH = '/_x/db/rollback'; +export const DEV_LEDGER_PATH = '/_x/db/ledger'; + +/** `--steps` and the door's `?steps=`: one rule, so the holder refuses what the flag refuses. */ +export const ROLLBACK_STEPS = { + name: 'steps', + command: 'db rollback', + min: 1, + example: 'x db rollback --steps 1', +} as const; diff --git a/packages/cli/src/db-migrate-through-dev.ts b/packages/cli/src/db-migrate-through-dev.ts index b5160f74b..03473d6c3 100644 --- a/packages/cli/src/db-migrate-through-dev.ts +++ b/packages/cli/src/db-migrate-through-dev.ts @@ -4,13 +4,11 @@ import { renderThrowable, stringField, UltimateError } from '@ultimat3/core'; import { t } from '@ultimat3/schema'; +import { DEV_MIGRATE_PATH } from './db-dev-wire'; import type { DevMigrateData } from './dev-db-migrate'; import { DevAlreadyRunningError, type DevLock } from './dev-lock'; import { liveDevLockChecked } from './dev-lock-live'; -/** `dev-db-migrate.ts`'s path, restated: importing that module would load the route's graph. */ -const MIGRATE_PATH = '/_x/db/migrate'; - const DIFFERENCE = t.object({ kind: t.string, table: t.string.min(0), @@ -188,7 +186,7 @@ export function migrateThroughDev( lock, stateDir, { - path: MIGRATE_PATH, + path: DEV_MIGRATE_PATH, resume: ['db', 'migrate'], read: (data) => { const parsed = DATA.safeParse(data); diff --git a/packages/cli/src/db-rollback-consent.test.ts b/packages/cli/src/db-rollback-consent.test.ts new file mode 100644 index 000000000..01b93a980 --- /dev/null +++ b/packages/cli/src/db-rollback-consent.test.ts @@ -0,0 +1,54 @@ +// When `x db rollback` needs `ROLLBACK_ALLOW_DESTRUCTIVE` to name what it reverses: a NAMED deploy +// (`namedDeployed`, staging or production), an `ULTIMATE_ENV` that names no environment, and — what +// no environment variable can talk it out of — a database on another machine. + +import { describe, expect, test } from 'bun:test'; +import { rollbackNeedsConsent } from './db-rollback-consent'; + +const embedded = { mode: 'embedded', url: 'pglite:///app/.x/pgdata' } as const; +const external = (url: string) => ({ mode: 'external', url }) as const; + +describe('rollbackNeedsConsent', () => { + test('a named deploy needs the names; development and test do not', () => { + expect(rollbackNeedsConsent({ ULTIMATE_ENV: 'production' }, embedded)).toBe(true); + expect(rollbackNeedsConsent({ ULTIMATE_ENV: 'staging' }, embedded)).toBe(true); + expect(rollbackNeedsConsent({ NODE_ENV: 'production' }, embedded)).toBe(true); + expect(rollbackNeedsConsent({ ULTIMATE_ENV: 'development' }, embedded)).toBe(false); + expect(rollbackNeedsConsent({ ULTIMATE_ENV: 'test' }, embedded)).toBe(false); + expect(rollbackNeedsConsent({}, embedded)).toBe(false); + }); + + test('an ULTIMATE_ENV that is no environment never reads as "not production"', () => { + expect(rollbackNeedsConsent({ ULTIMATE_ENV: 'prod' }, embedded)).toBe(true); + }); + + test('an external non-loopback database needs the names even with no environment set', () => { + // `DATABASE_URL=<prod> x db rollback` from a shell that names nothing resolved development. + const remote = external('postgres://app:secret@db.prod.example.com:5432/app'); + expect(rollbackNeedsConsent({}, remote)).toBe(true); + expect(rollbackNeedsConsent({ ULTIMATE_ENV: 'development' }, remote)).toBe(true); + expect(rollbackNeedsConsent({}, external('postgres://app@10.0.0.7/app'))).toBe(true); + expect(rollbackNeedsConsent({}, external('postgres://app@db/app'))).toBe(true); + }); + + test("this machine's database is the developer's own: loopback and a local socket", () => { + for (const url of [ + 'postgres://app@localhost:5432/app', + 'postgres://app@127.0.0.1/app', + 'postgres://app@[::1]/app', + 'postgresql:///app?host=/var/run/postgresql', + ]) { + expect({ url, consent: rollbackNeedsConsent({}, external(url)) }).toEqual({ + url, + consent: false, + }); + } + }); + + test('a URL that does not parse, or a host query naming another machine, needs the names', () => { + expect(rollbackNeedsConsent({}, external('not a url'))).toBe(true); + expect(rollbackNeedsConsent({}, external('postgres:///app?host=db.prod.example.com'))).toBe( + true, + ); + }); +}); diff --git a/packages/cli/src/db-rollback-consent.ts b/packages/cli/src/db-rollback-consent.ts index 29948d851..6ba1ca406 100644 --- a/packages/cli/src/db-rollback-consent.ts +++ b/packages/cli/src/db-rollback-consent.ts @@ -1,6 +1,6 @@ // What `x db rollback` asks before the first `down` runs, under the migrate lock, of the exact rows -// about to be reversed: every one has a `-- down` half on disk, and outside development the operator -// named each id in `ROLLBACK_ALLOW_DESTRUCTIVE` — the migrate role's own written override. +// about to be reversed: every one has a `-- down` half on disk, and on a deploy — or a database on +// another machine — the operator named each id in `ROLLBACK_ALLOW_DESTRUCTIVE`. // why: Bun exposes no path-join primitive. import { join } from 'node:path'; @@ -8,18 +8,43 @@ import { join } from 'node:path'; import { renderFixShellArg, tryResolveEnvironment } from '@ultimat3/core'; import type { LedgerRow, Migration } from '@ultimat3/db'; import { DbError, migrationIrreversible, ROLLBACK_ALLOW_DESTRUCTIVE_ENV } from '@ultimat3/db'; +import { namedDeployed } from './framework-env'; +import { isLoopbackHostname } from './loopback-host'; import { MIGRATIONS_DIR, parseMigrationSql } from './migrations'; +import type { ServiceBinding } from './runtime-bindings'; type Env = Readonly<Record<string, string | undefined>>; +/** The database the rollback runs against: `resolveServices(root, env).db`. */ +export type RollbackDatabase = Pick<ServiceBinding, 'mode' | 'url'>; + +/** + * Is `url` a Postgres on another machine? A local socket (no host, or a `host=` that is a path) and + * a loopback name are this machine's; a URL that does not parse is another's — fail closed. + */ +function remoteDatabase(url: string): boolean { + let parsed: URL; + try { + parsed = new URL(url); + } catch { + return true; + } + const host = parsed.hostname || (parsed.searchParams.get('host') ?? ''); + if (host === '' || host.startsWith('/')) return false; + return !isLoopbackHostname(host); +} + /** - * Development and test reverse freely: the database is the developer's own. Everything else needs - * the names — staging included, which exists to fail the way production fails — and so does an - * `ULTIMATE_ENV` that is not an environment: a typo must not read as "not production". + * Who needs the names. A NAMED deploy — `namedDeployed`, framework-env's own predicate: staging + * included, which exists to fail the way production fails — and an `ULTIMATE_ENV` that is no + * environment: a typo must not read as "not production". And, whatever the environment resolves + * to, an external database on another machine: `DATABASE_URL=<prod> x db rollback` from a shell + * that names nothing resolves development, and reversed production unasked. A developer's own + * database (embedded, loopback, a local socket) reverses freely. */ -export function rollbackNeedsConsent(env: Env): boolean { - const environment = tryResolveEnvironment({ env }); - return environment !== 'development' && environment !== 'test'; +export function rollbackNeedsConsent(env: Env, database?: RollbackDatabase): boolean { + if (namedDeployed(env) || tryResolveEnvironment({ env }) === undefined) return true; + return database?.mode === 'external' && remoteDatabase(database.url); } const namedIn = (allow: string | undefined): ReadonlySet<string> => @@ -36,15 +61,20 @@ const namedIn = (allow: string | undefined): ReadonlySet<string> => * not only those whose `up` was destructive: the consent `ledgerAheadOfBuild` takes for an older * image over a newer schema, asked here of the schema change itself. */ -function assertNamed(targets: readonly LedgerRow[], env: Env, steps: number): void { - if (!rollbackNeedsConsent(env)) return; +function assertNamed( + targets: readonly LedgerRow[], + env: Env, + steps: number, + database: RollbackDatabase | undefined, +): void { + if (!rollbackNeedsConsent(env, database)) return; const named = namedIn(env[ROLLBACK_ALLOW_DESTRUCTIVE_ENV]); const unnamed = targets.filter((row) => !named.has(row.id)).map((row) => row.id); if (unnamed.length === 0) return; const all = targets.map((row) => row.id).join(','); throw new DbError({ code: 'X_MIGRATION_ROLLBACK_DESTRUCTIVE', - cause: `x db rollback would reverse ${String(targets.length)} applied migration(s) outside development, and ${ROLLBACK_ALLOW_DESTRUCTIVE_ENV} does not name ${unnamed.join(', ')} — a down drops what its up added, rows included, under a build that still reads it`, + cause: `x db rollback would reverse ${String(targets.length)} applied migration(s) on a deployed or remote database, and ${ROLLBACK_ALLOW_DESTRUCTIVE_ENV} does not name ${unnamed.join(', ')} — a down drops what its up added, rows included, under a build that still reads it`, fix: `${ROLLBACK_ALLOW_DESTRUCTIVE_ENV}=${renderFixShellArg(all, '<migration id>')} x db rollback --steps ${String(steps)} --json # names each migration it reverses; first deploy a build that no longer reads what they added`, meta: { refused: unnamed, steps }, }); @@ -81,14 +111,18 @@ function assertReversible(targets: readonly LedgerRow[], unmarked: ReadonlySet<s } } -/** `rollback()`'s `confirm`: reversibility first (it is true in every environment), then consent. */ +/** + * `rollback()`'s `confirm`: reversibility first (it is true in every environment), then consent. + * `database` is the binding the pass runs against; absent, only the environment is asked. + */ export function rollbackConfirm( unmarked: ReadonlySet<string>, env: Env, steps: number, + database?: RollbackDatabase, ): (targets: readonly LedgerRow[]) => void { return (targets) => { assertReversible(targets, unmarked); - assertNamed(targets, env, steps); + assertNamed(targets, env, steps, database); }; } diff --git a/packages/cli/src/db-rollback-pass.ts b/packages/cli/src/db-rollback-pass.ts index 58432fdcb..25761af8c 100644 --- a/packages/cli/src/db-rollback-pass.ts +++ b/packages/cli/src/db-rollback-pass.ts @@ -4,6 +4,7 @@ import { rollback } from '@ultimat3/db'; import { t } from '@ultimat3/schema'; +import { DEV_ROLLBACK_PATH } from './db-dev-wire'; import { askDev, type PostJson, unreadable } from './db-migrate-through-dev'; import { rollbackConfirm, withoutDown } from './db-rollback-consent'; import { liveDevLockChecked } from './dev-lock-live'; @@ -13,9 +14,6 @@ import { startQueue } from './runtime-queue'; type Env = Readonly<Record<string, string | undefined>>; -/** `dev-db-migrate.ts`'s path, restated: importing that module would load the route's graph. */ -const ROLLBACK_PATH = '/_x/db/rollback'; - const REVERTED = t.object({ reverted: t.array(t.string) }); /** @@ -47,7 +45,7 @@ export async function rollbackPass( holder, services.stateDir, { - path: `${ROLLBACK_PATH}?steps=${String(steps)}`, + path: `${DEV_ROLLBACK_PATH}?steps=${String(steps)}`, resume: ['db', 'rollback', '--steps', String(steps)], read: (data) => { const parsed = REVERTED.safeParse(data); diff --git a/packages/cli/src/dev-db-migrate.ts b/packages/cli/src/dev-db-migrate.ts index da5d21eb8..6f8dc8717 100644 --- a/packages/cli/src/dev-db-migrate.ts +++ b/packages/cli/src/dev-db-migrate.ts @@ -3,12 +3,7 @@ // so the command asks the holder instead of opening `.x/pgdata` a second time. Loopback Host and // peer, same-origin: the `/_x/db` doors. -import { - NotImplementedError, - renderFixShellArg, - renderThrowable, - UltimateError, -} from '@ultimat3/core'; +import { NotImplementedError, renderThrowable, UltimateError } from '@ultimat3/core'; import type { DriftDifference } from '@ultimat3/db'; import { checkDrift, db, migrate } from '@ultimat3/db'; import type { CatalogDescription } from '@ultimat3/db/schema-dump'; @@ -17,22 +12,17 @@ import type { Route, UltimateRequest } from '@ultimat3/http'; import { jsonResponse } from '@ultimat3/http'; import { loadAppConfig } from './app-config-load'; import { acceptCreatedTables } from './db-accept-created'; +import { DEV_LEDGER_PATH, DEV_MIGRATE_PATH, DEV_ROLLBACK_PATH } from './db-dev-wire'; import { frameworkStorageDrift } from './db-object-drift'; import { assertSameOrigin, hostRefusal } from './dev-dashboard-guard'; import { ledgerInDev, rollbackInDev, stepsOf } from './dev-db-rollback'; import { ledgerMoved } from './dev-db-settled'; import { readMigrations } from './migrations'; import { rowSecurityDeclared } from './row-security-boot'; - -/** The path `db-migrate-through-dev.ts` posts to, under the dashboard's own `/_x/db`. */ -export const DEV_MIGRATE_PATH = '/_x/db/migrate'; - -/** The paths `db-rollback-pass.ts` and `db-applied-edits.ts` post to, beside it. */ -export const DEV_ROLLBACK_PATH = '/_x/db/rollback'; -export const DEV_LEDGER_PATH = '/_x/db/ledger'; +import { stopRunStartFix } from './stop-run-start'; /** The command that works when this process cannot apply: the embedded database to itself. */ -export const MIGRATE_ALONE_FIX = 'x stop --json && x db migrate && x dev'; +export const MIGRATE_ALONE_FIX = stopRunStartFix(['db', 'migrate']); /** One applied pass as it crosses the wire: `runMigrations`' report, and the live catalog. */ export interface DevMigrateData { @@ -155,7 +145,7 @@ export function devMigrateRoutes(input: DevMigrateRouteInput): readonly Route[] const steps = stepsOf(request.url.searchParams.get('steps')); await assertDevCanMigrate( root, - `x stop --json && x db rollback --steps ${renderFixShellArg(String(steps), '<n>')} && x dev`, + stopRunStartFix(['db', 'rollback', '--steps', String(steps)]), ); return rollbackInDev(root, env, steps).finally(ledgerMoved); }), diff --git a/packages/cli/src/dev-db-rollback.ts b/packages/cli/src/dev-db-rollback.ts index ea4f085cc..f745f70f6 100644 --- a/packages/cli/src/dev-db-rollback.ts +++ b/packages/cli/src/dev-db-rollback.ts @@ -3,19 +3,14 @@ // (`x db gen`'s edited-migration check). Bodies only — `dev-db-migrate.ts` mounts and guards them. import { db, isLedgerMissing, readLedger } from '@ultimat3/db'; +import { ROLLBACK_STEPS } from './db-dev-wire'; import { reverseApplied } from './db-rollback-pass'; import { parseIntFlag } from './flag-number'; type Env = Readonly<Record<string, string | undefined>>; /** `?steps=n`, through the command's own reader: the door refuses what the flag refuses. */ -export const stepsOf = (raw: string | null): number => - parseIntFlag(raw ?? '', { - name: 'steps', - command: 'db rollback', - min: 1, - example: 'x db rollback --steps 1', - }); +export const stepsOf = (raw: string | null): number => parseIntFlag(raw ?? '', ROLLBACK_STEPS); /** `rollback()` over the client this process already holds, with the command's own two refusals. */ export async function rollbackInDev( diff --git a/packages/cli/src/dev-lock.ts b/packages/cli/src/dev-lock.ts index efbae977a..d03ef7bb8 100644 --- a/packages/cli/src/dev-lock.ts +++ b/packages/cli/src/dev-lock.ts @@ -30,7 +30,7 @@ import { reusedPid, startedOf } from './dev-lock-identity'; import type { PortHolder } from './dev-lock-port-holder'; import { stealStale } from './dev-lock-steal'; import { freeDevPortPair } from './port-pair-free'; -import { quoteArg } from './shell-quote'; +import { stopRunStartFix } from './stop-run-start'; /** Where the running dev server records itself, inside the state directory it already owns. */ export const DEV_LOCK_FILE = 'dev.lock'; @@ -143,11 +143,10 @@ export class DevAlreadyRunningError extends UltimateError { code: 'X_DEV_ALREADY_RUNNING', cause: `pid ${input.lock.pid} is already running x dev on ${input.lock.url} and holds ${input.stateDir}${single}${input.unanswered === undefined ? '' : `; asked to do it instead, ${input.unanswered}`}`, // `x stop`, not `kill <pid>`: a kill returns before the drain ends and the next boot refuses. - // The resumed command is assembled word by word from screened words, never spliced. fix: input.resume === undefined ? `x stop --json # or use the one already running at ${input.lock.url}` - : `${['x', 'stop', '--json', '&&', 'x', ...input.resume.map(quoteArg), '&&', 'x', 'dev'].join(' ')} # the embedded database takes one process at a time; pass the flags you passed`, + : `${stopRunStartFix(input.resume)} # the embedded database takes one process at a time; pass the flags you passed`, meta: { pid: input.lock.pid, port: input.lock.port, stateDir: input.stateDir }, }); } diff --git a/packages/cli/src/dev-rebuild-schema.ts b/packages/cli/src/dev-rebuild-schema.ts index 4d5757de8..97a573504 100644 --- a/packages/cli/src/dev-rebuild-schema.ts +++ b/packages/cli/src/dev-rebuild-schema.ts @@ -20,8 +20,7 @@ import { resolveServices } from './runtime-bindings'; export const SCHEMA_AHEAD_FIX = 'x db gen "describe the change" && x db migrate'; /** Where this process cannot apply the pass itself: the embedded database, to the command alone. */ -export const SCHEMA_AHEAD_FIX_ALONE = - 'x db gen "describe the change" && x stop --json && x db migrate && x dev'; +export const SCHEMA_AHEAD_FIX_ALONE = `x db gen "describe the change" && ${MIGRATE_ALONE_FIX}`; /** Whether `x db migrate` works while this `x dev` runs: any external database, or a pass it takes. */ export async function migratesBesideDev(root: string): Promise<boolean> { diff --git a/packages/cli/src/role-select.test.ts b/packages/cli/src/role-select.test.ts new file mode 100644 index 000000000..694ef2f17 --- /dev/null +++ b/packages/cli/src/role-select.test.ts @@ -0,0 +1,70 @@ +// `x dev` runs the roles `app.config.ts` declares — the same rule the container's `ROLE` is refused +// by (`assertRoleDeclared`) — so a cron task does not fire in development for an app whose deploy +// runs no scheduler. Dropped roles are named in one boot line, never silently narrowed. + +import { afterAll, afterEach, describe, expect, mock, spyOn, test } from 'bun:test'; +// why: Bun has no recursive remove, only a per-file delete. +import { mkdir, rm } from 'node:fs/promises'; +import { defineConfig, logger } from '@ultimat3/core'; +import { rolesDeclaredForDev, selectRoles, startRoles } from './role-start'; +import { fixtureRuntime, resetDevRolesState } from './role-start-fixture'; + +const ROOT = `${import.meta.dir}/../.roles-declared-fixture`; + +afterEach(() => { + mock.restore(); + resetDevRolesState(); +}); + +afterAll(async () => { + await rm(ROOT, { recursive: true, force: true }); +}); + +describe('x dev runs only the roles app.config.ts declares', () => { + test('a declared list narrows the selection and names what it dropped', () => { + const info = spyOn(logger, 'info').mockImplementation(() => undefined); + const config = defineConfig({ name: 'demo', roles: ['web', 'worker'] }); + + expect(rolesDeclaredForDev(selectRoles(undefined), config)).toEqual(['web', 'worker']); + const lines = info.mock.calls.map(([message]) => String(message)); + expect( + lines.filter((line) => line.includes('scheduler') && line.includes('sync')), + ).toHaveLength(1); + }); + + test('no config, or roles left at its default, runs the selection unchanged', () => { + const all = selectRoles(undefined); + expect(rolesDeclaredForDev(all, undefined)).toEqual(all); + expect(rolesDeclaredForDev(all, defineConfig({ name: 'demo' }))).toEqual(all); + }); + + test('a selection of nothing but undeclared roles is refused with the declared ones', () => { + const config = defineConfig({ name: 'demo', roles: ['web', 'worker'] }); + expect(() => rolesDeclaredForDev(selectRoles('scheduler'), config)).toThrow(/X_CONFIG_INVALID/); + }); + + test('the boot obeys it: a scheduler the app does not declare never starts', async () => { + await mkdir(ROOT, { recursive: true }); + await Bun.write( + `${ROOT}/app.config.ts`, + "export const config = { name: 'demo', roles: ['web'] };\n", + ); + spyOn(logger, 'info').mockImplementation(() => undefined); + const running = await startRoles({ + roles: selectRoles('web,scheduler'), + port: 0, + buildId: 'test', + runtime: fixtureRuntime(ROOT), + env: {}, + routes: [], + root: ROOT, + http: { dev: true, hostname: 'localhost' }, + }); + try { + expect(running.roles).toEqual(['web']); + expect(running.scheduler).toBeNull(); + } finally { + await running.stop(); + } + }); +}); diff --git a/packages/cli/src/role-select.ts b/packages/cli/src/role-select.ts index c69706fd1..cffe4ae45 100644 --- a/packages/cli/src/role-select.ts +++ b/packages/cli/src/role-select.ts @@ -1,10 +1,11 @@ // `x dev --role`: which roles one dev process runs. Every value that is not a runnable selection // is a flag error carrying the working invocation, never a silently narrowed or empty set. -import type { Role } from '@ultimat3/core'; -import { isRole, ROLES } from '@ultimat3/core'; +import type { AppConfig, Role } from '@ultimat3/core'; +import { ConfigInvalidError, isRole, logger, ROLES } from '@ultimat3/core'; import { BadFlagError } from './errors'; import { DEV_ROLES } from './role-start-types'; +import { roleDeclared } from './serve-env'; import { quoteArg } from './shell-quote'; /** @@ -55,3 +56,31 @@ export function selectRoles(flag: string | undefined): readonly Role[] { } return SELECTABLE_ROLES.filter((role) => selected.includes(role)); } + +/** + * The selection narrowed to the roles `app.config.ts` declares — the rule the container's `ROLE` is + * refused by (`roleDeclared`, `serve-env.ts`), so dev never fires a cron task, or binds a sync + * node, that the deploy will not run. What it drops is named in one line; a selection of nothing + * BUT undeclared roles is refused, as `rolesUnderRealtime` refuses one that would serve nothing. + */ +export function rolesDeclaredForDev( + selected: readonly Role[], + config: AppConfig | undefined, +): readonly Role[] { + const kept = selected.filter((role) => roleDeclared(role, config)); + if (kept.length === selected.length || config === undefined) return selected; + const dropped = selected.filter((role) => !kept.includes(role)); + if (kept.length === 0) { + throw new ConfigInvalidError({ + cause: `role ${dropped.join(',')} was asked for and roles in app.config.ts lists ${config.roles.join(', ')}, so this process would serve nothing`, + fix: `x dev --role ${quoteArg(config.roles.filter((role) => role !== 'migrate').join(','))}`, + meta: { key: 'roles', roles: dropped, declared: [...config.roles] }, + }); + } + // info: once per boot — what this process does NOT run, which nothing else would say. + logger.info(`roles in app.config.ts does not list ${dropped.join(', ')}: not starting them`, { + dropped, + declared: [...config.roles], + }); + return kept; +} diff --git a/packages/cli/src/role-start.ts b/packages/cli/src/role-start.ts index 8aa9fed63..c3b85ef4e 100644 --- a/packages/cli/src/role-start.ts +++ b/packages/cli/src/role-start.ts @@ -40,6 +40,7 @@ import { import { startRolePgStats } from './role-pg-stats'; import { rolesUnderRealtime } from './role-realtime'; import { startReplicator } from './role-replicator'; +import { rolesDeclaredForDev } from './role-select'; import { type DeviceMount, hostDeviceSockets } from './role-start-devices'; import type { RunningRoles, StartRolesOptions } from './role-start-types'; import { prepareSync, type RunningSync, syncReadsChanges } from './role-sync'; @@ -58,7 +59,7 @@ import { trustedHopsFromEnv } from './trusted-hops'; import { DEV_BINDING } from './web-binding'; // `--role`'s reading, in a file of its own at the line ceiling. -export { SELECTABLE_ROLES, selectRoles } from './role-select'; +export { rolesDeclaredForDev, SELECTABLE_ROLES, selectRoles } from './role-select'; // The two shapes this module takes and answers, in a file of their own at the line ceiling. export type { RunningRoles, StartRolesOptions } from './role-start-types'; // Declared beside the option types so `x dev`'s spec reads it without loading this module. @@ -226,12 +227,12 @@ function assertOneJobDriver(runtime: RunningServices): void { } export async function startRoles(options: StartRolesOptions): Promise<RunningRoles> { - // `realtime.enabled` read here, before anything binds: a refusal leaves nothing to unwind. - const selected = rolesUnderRealtime( - options.roles, - options.runtime.realtime, - (options.http ?? DEV_BINDING).dev, - ); + const dev = (options.http ?? DEV_BINDING).dev; + const config = options.root === undefined ? undefined : await loadAppConfig(options.root); + // `realtime.enabled` and `roles` read here, before anything binds: a refusal leaves nothing to + // unwind. `roles` for `x dev` only — a container's `ROLE` was refused against it at boot. + const realtime = rolesUnderRealtime(options.roles, options.runtime.realtime, dev); + const selected = dev ? rolesDeclaredForDev(realtime, config) : realtime; assertOneJobDriver(options.runtime); // Once per process, and only where a role in it can act on the line (`serve-boot-warnings.ts`): // `rateLimitStoreFor` is asked twice in a web boot, and a scheduler spends no limit at all. @@ -255,7 +256,6 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol // these roles takes back exactly this install, whatever else stacked over or under it. // Once, before any role serves: which roles core's `bootWarning` concerns, and its per-build // marker store (`runtime-boot-warnings.ts`). Released by the stop, like every frame here. - const config = options.root === undefined ? undefined : await loadAppConfig(options.root); const releaseWarnings = installRoleBootWarnings({ roles: selected, config, diff --git a/packages/cli/src/runtime-cache-frame.test.ts b/packages/cli/src/runtime-cache-frame.test.ts new file mode 100644 index 000000000..fc03fd65a --- /dev/null +++ b/packages/cli/src/runtime-cache-frame.test.ts @@ -0,0 +1,40 @@ +// The bust frame's codec, alone: what a sender writes and what any receiver, older or newer, reads. + +import { describe, expect, test } from 'bun:test'; +import { decodeBustFrame, encodeBustFrame, isFlushAll } from './runtime-cache-frame'; + +describe('unit · the bust frame', () => { + test('no shared scope cleared: the bare tag array every older receiver already reads', () => { + expect(encodeBustFrame(['post:1'])).toBe('["post:1"]'); + expect(encodeBustFrame(['post:1'], {})).toBe('["post:1"]'); + }); + + test('a scope rides after the tags, and decodes back to both', () => { + const frame = encodeBustFrame(['post:1', 'post'], { redis: 'x:v2' }); + expect(decodeBustFrame(JSON.parse(frame) as unknown[])).toEqual({ + wire: ['post:1', 'post'], + sender: { redis: 'x:v2' }, + }); + }); + + test('a frame with no scope object decodes to tags alone: every tier is busted', () => { + expect(decodeBustFrame(['post:1'])).toEqual({ wire: ['post:1'] }); + }); + + test('a malformed scope object is no scope at all', () => { + for (const odd of [ + { scopes: null }, + { scopes: ['x'] }, + { scopes: { redis: 1 } }, + { other: 1 }, + ]) { + expect(decodeBustFrame(['post:1', odd])).toEqual({ wire: ['post:1'] }); + } + }); + + test('the flush marker is an object with flush: all, and nothing else is', () => { + expect(isFlushAll({ flush: 'all' })).toBe(true); + expect(isFlushAll(['post:1', { scopes: { redis: 'x' } }])).toBe(false); + expect(isFlushAll({ scopes: { redis: 'x' } })).toBe(false); + }); +}); diff --git a/packages/cli/src/runtime-cache-frame.ts b/packages/cli/src/runtime-cache-frame.ts new file mode 100644 index 000000000..cb4ad50fe --- /dev/null +++ b/packages/cli/src/runtime-cache-frame.ts @@ -0,0 +1,46 @@ +// The bust frame on `x.cache.invalidate`: the wire tags, then — when the sender's bust cleared a +// shared tier — one `{ scopes }` object naming what it cleared. Every receiver since v30 keeps the +// array's strings only, so an older pod reads the tags and busts every tier, as it always did. + +import type { SharedTierScopes } from '@ultimat3/cache'; + +/** What a receiver reads off one frame: the tags, and the sender's scopes when it named any. */ +export interface BustFrame { + readonly wire: readonly string[]; + readonly sender?: SharedTierScopes; +} + +/** `CACHE_FLUSH_ALL`, parsed: a peer had more refused busts than it could keep. */ +export const isFlushAll = (parsed: unknown): boolean => + typeof parsed === 'object' && + parsed !== null && + !Array.isArray(parsed) && + Reflect.get(parsed, 'flush') === 'all'; + +/** The payload a bust publishes. No shared tier cleared, it is the bare tag array of old. */ +export function encodeBustFrame(wire: readonly string[], sender?: SharedTierScopes): string { + if (sender === undefined || Object.keys(sender).length === 0) return JSON.stringify(wire); + return JSON.stringify([...wire, { scopes: sender }]); +} + +/** + * A parsed frame array, read. A scopes object that is malformed in any part is read as NO scopes — + * every tier is busted — because a skipped bust is a stale row for the whole TTL. + */ +export function decodeBustFrame(parsed: readonly unknown[]): BustFrame { + const wire = parsed.filter((value): value is string => typeof value === 'string'); + const sender = parsed.map(scopesOf).find((scopes) => scopes !== undefined); + return sender === undefined ? { wire } : { wire, sender }; +} + +function scopesOf(value: unknown): SharedTierScopes | undefined { + if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined; + const scopes: unknown = Reflect.get(value, 'scopes'); + if (typeof scopes !== 'object' || scopes === null || Array.isArray(scopes)) return undefined; + const read: Record<string, string> = {}; + for (const [name, scope] of Object.entries(scopes)) { + if (typeof scope !== 'string') return undefined; + read[name] = scope; + } + return read; +} diff --git a/packages/cli/src/runtime-cache-scopes.test.ts b/packages/cli/src/runtime-cache-scopes.test.ts new file mode 100644 index 000000000..adfc95005 --- /dev/null +++ b/packages/cli/src/runtime-cache-scopes.test.ts @@ -0,0 +1,110 @@ +// The broadcast frame across a rolling deploy, in both directions: a bust names the shared scope +// it cleared after its tags, a receiver skips a shared tier only for its own scope, and a frame +// from either side of the deploy is read by the other. + +import { afterEach, describe, expect, test } from 'bun:test'; +import { declareTags, invalidateTags, isolateDeclaredTags, noopPurgeDriver } from '@ultimat3/cache'; +import type { CacheTier } from '@ultimat3/cache/adapter'; +import { InProcessTransport } from '@ultimat3/realtime/server'; +import { CACHE_INVALIDATE_SUBJECT, startCacheTiers } from './runtime-cache'; +import { turns } from './runtime-turns-fixture'; + +let release: (() => Promise<void>) | undefined; +const restoreTags = isolateDeclaredTags(); + +afterEach(async () => { + await release?.(); + release = undefined; + restoreTags(); +}); + +/** A shared rung in the namespace `scope`, counting the busts it is asked for. */ +function sharedRung(scope: string): { tier: CacheTier; busts: string[][] } { + const busts: string[][] = []; + const tier: CacheTier = { + name: 'redis', + scope, + get: () => Promise.resolve(undefined), + set: () => Promise.resolve(), + del: () => Promise.resolve(), + fence: () => Promise.reject(new TypeError('no read runs in this file')), + invalidateTags(tags) { + busts.push(tags.map((one) => `${one.entity}:${one.id ?? ''}`)); + return Promise.resolve({ tier: 'redis', keys: [] }); + }, + }; + return { tier, busts }; +} + +function boot(scope: string): { transport: InProcessTransport; busts: string[][] } { + declareTags(['post']); + const transport = new InProcessTransport(); + const rung = sharedRung(scope); + release = startCacheTiers({ + env: {}, + purge: noopPurgeDriver(), + transport, + tiers: ['redis'], + supplied: [rung.tier], + }); + return { transport, busts: rung.busts }; +} + +describe('the invalidation frame across a rolling deploy', () => { + test('a bust names the shared scope it cleared, after its tags', async () => { + const { transport } = boot('x:v2'); + const seen: string[] = []; + await transport.subscribe(CACHE_INVALIDATE_SUBJECT, (payload) => { + seen.push(payload); + }); + + await invalidateTags([{ entity: 'post', id: '1' }]); + + expect(seen.map((payload) => JSON.parse(payload))).toEqual([ + ['post:1', { scopes: { redis: 'x:v2' } }], + ]); + // What every receiver since v30 does with it (`applyBroadcast`: strings only): the tags, and + // no scope — so an older pod busts every tier, which is correct across two namespaces. + const older = (JSON.parse(seen[0] as string) as unknown[]).filter( + (value) => typeof value === 'string', + ); + expect(older).toEqual(['post:1']); + }); + + test("a peer frame naming THIS build's scope skips the shared tier", async () => { + const { transport, busts } = boot('x:v2'); + await transport.publish( + CACHE_INVALIDATE_SUBJECT, + JSON.stringify(['post:1', { scopes: { redis: 'x:v2' } }]), + ); + await turns(20); + expect(busts).toEqual([]); + }); + + test("a peer frame from another build busts this build's shared tier", async () => { + const { transport, busts } = boot('x:v1'); + await transport.publish( + CACHE_INVALIDATE_SUBJECT, + JSON.stringify(['post:1', { scopes: { redis: 'x:v2' } }]), + ); + await turns(20); + expect(busts).toEqual([['post:1']]); + }); + + test("an older pod's frame (tags only) busts the shared tier", async () => { + const { transport, busts } = boot('x:v2'); + await transport.publish(CACHE_INVALIDATE_SUBJECT, JSON.stringify(['post:1'])); + await turns(20); + expect(busts).toEqual([['post:1']]); + }); + + test('a scope entry that is not a string is no scope at all', async () => { + const { transport, busts } = boot('x:v2'); + await transport.publish( + CACHE_INVALIDATE_SUBJECT, + JSON.stringify(['post:1', { scopes: { redis: ['x:v2'] } }]), + ); + await turns(20); + expect(busts).toEqual([['post:1']]); + }); +}); diff --git a/packages/cli/src/runtime-cache.ts b/packages/cli/src/runtime-cache.ts index 026523524..19c743367 100644 --- a/packages/cli/src/runtime-cache.ts +++ b/packages/cli/src/runtime-cache.ts @@ -42,6 +42,7 @@ import { redisClient, redisUrlSource } from '@ultimat3/core/redis'; import type { Transport } from '@ultimat3/realtime/server'; import type { Env } from './runtime-bindings'; import { logCacheBus, selectCacheBus } from './runtime-cache-bus'; +import { decodeBustFrame, encodeBustFrame, isFlushAll } from './runtime-cache-frame'; import { defaultTtlOf } from './runtime-cache-ttl'; /** @@ -251,9 +252,10 @@ function warnDefaultRedis(built: readonly CacheTier[], env: Env): void { * another instance's. A message this process published is delivered back to it on every real bus * and is applied again — deliberately, with no node-id filter — to the tiers this process OWNS * (the in-process rungs): there, dropping an already-dropped key is idempotent and free, while a - * dedup table is state that can be wrong. A SHARED rung is not free and is not re-busted: the - * sender cleared the one Redis every replica reads, so `@ultimat3/cache` applies an inbound - * broadcast to no tier the process does not own. Re-emit is impossible by + * dedup table is state that can be wrong. A SHARED rung is not free: the frame names the scope + * (Redis namespace, per build) the sender's bust cleared, and a receiver skips its shared rung + * only for that same scope — another build's pod on a rolling deploy, or an older pod's frame + * naming none, still busts it (`runtime-cache-frame.ts`). Re-emit is impossible by * construction, not by a flag: `receiveInvalidationBroadcast` is the only entry point that * suppresses it, and `emit` is not a public parameter. */ @@ -320,6 +322,8 @@ export function startCacheTiers(options: CacheTiersOptions): () => Promise<void> return; } if (deferred.size === 0) return; + // Named no scope: the batch spans busts whose shared rungs may have refused, so every peer + // busts every rung — the cost of a missed skip is one load, of a wrong one a stale TTL. const batch = [...deferred]; deferred.clear(); try { @@ -368,9 +372,9 @@ export function startCacheTiers(options: CacheTiersOptions): () => Promise<void> })(); }; - registerInvalidationBroadcast(async (wireTags) => { + registerInvalidationBroadcast(async (wireTags, sender) => { try { - await send(JSON.stringify(wireTags)); + await send(encodeBustFrame(wireTags, sender)); } catch (error) { defer(wireTags); // Still thrown: the report must say the peers have not been told YET. @@ -467,13 +471,6 @@ export function startCacheTiers(options: CacheTiersOptions): () => Promise<void> */ export const broadcastErrorText = (error: unknown): string => renderThrowable(error); -/** `CACHE_FLUSH_ALL`, parsed: a peer had more refused busts than it could keep. */ -const isFlushAll = (parsed: unknown): boolean => - typeof parsed === 'object' && - parsed !== null && - !Array.isArray(parsed) && - Reflect.get(parsed, 'flush') === 'all'; - /** * A peer's wire tags, applied here. Never throws: a malformed frame or an undeclared tag must not * kill the subscriber loop, because that would silently end cross-instance invalidation for the @@ -487,8 +484,8 @@ async function applyBroadcast(payload: string): Promise<void> { return; } if (!Array.isArray(parsed)) return; - const wire = parsed.filter((value): value is string => typeof value === 'string'); - if (wire.length > 0) await receiveInvalidationBroadcast(wire); + const { wire, sender } = decodeBustFrame(parsed); + if (wire.length > 0) await receiveInvalidationBroadcast(wire, sender); } catch (error) { logger.warn('cache.broadcast.apply-failed', { error: broadcastErrorText(error) }); } diff --git a/packages/cli/src/runtime-database-ssl.test.ts b/packages/cli/src/runtime-database-ssl.test.ts index 9e1939a52..3ff88bf69 100644 --- a/packages/cli/src/runtime-database-ssl.test.ts +++ b/packages/cli/src/runtime-database-ssl.test.ts @@ -85,6 +85,25 @@ describe('unit · database.ssl', () => { } }); + test('an empty sslmode or ssl is not a stated mode', () => { + const base = 'postgres://app@db.internal:5432/app'; + for (const query of ['sslmode=', 'ssl=', 'SSLMODE=', 'sslmode=&ssl=', 'sslmode=%20']) { + const out = new URL(withRequiredTls(`${base}?${query}&application_name=web`, {})); + expect(out.searchParams.getAll('sslmode')).toEqual(['require']); + expect([...out.searchParams.keys()].sort()).toEqual(['application_name', 'sslmode']); + } + // One spelling empty, the other stated: the stated one is the operator's. + const stated = `${base}?sslmode=&ssl=true`; + expect(withRequiredTls(stated, {})).toBe(stated); + }); + + test("an upper-case SSLMODE is the operator's", () => { + for (const query of ['SSLMODE=disable', 'SslMode=verify-full', 'SSL=false', 'Ssl=true']) { + const url = `postgres://app@db.internal:5432/app?${query}`; + expect(withRequiredTls(url, {})).toBe(url); + } + }); + test('PGSSLMODE in the boot env is the operator stating the mode: nothing is added', () => { const url = 'postgres://app@db.internal:5432/app'; expect(withRequiredTls(url, { PGSSLMODE: 'verify-full' })).toBe(url); diff --git a/packages/cli/src/runtime-database-ssl.ts b/packages/cli/src/runtime-database-ssl.ts index 3d9828e57..5238ec721 100644 --- a/packages/cli/src/runtime-database-ssl.ts +++ b/packages/cli/src/runtime-database-ssl.ts @@ -9,13 +9,20 @@ import type { DevServices, Env } from './runtime-bindings'; * server with no TLS, `ERR_POSTGRES_TLS_NOT_AVAILABLE`). */ const SSL_MODE = 'sslmode'; +/** The two spellings of the mode, as the driver reads them: by name, whatever the case. */ +const isModeKey = (key: string): boolean => { + const name = key.toLowerCase(); + return name === SSL_MODE || name === 'ssl'; +}; + /** * `url` with `sslmode=require`, unless a mode is already stated — in the URL (`sslmode`, or the * `ssl` spelling some dashboards hand out) or by `PGSSLMODE` in the boot's env. Never an override: * replacing `verify-full` with `require` would drop certificate verification, and replacing * `disable` would break the sidecar or loopback hop it was written for. `require` and not * `verify-full` because a managed Postgres seldom ships its CA into the image; an operator who - * has one says so in the URL. A value no URL parser reads is handed on as it is: `postgresClient` + * has one says so in the URL. An EMPTY `sslmode=` states nothing (it would otherwise be read as + * plaintext under `database.ssl: true`) and is replaced. A value no URL parser reads is handed on as it is: `postgresClient` * refuses it by name (`X_DB_UNAVAILABLE`). */ export function withRequiredTls(url: string, env: Env): string { @@ -26,7 +33,9 @@ export function withRequiredTls(url: string, env: Env): string { } catch { return url; } - if (parsed.searchParams.has(SSL_MODE) || parsed.searchParams.has('ssl')) return url; + const modes = [...parsed.searchParams].filter(([key]) => isModeKey(key)); + if (modes.some(([, value]) => value.trim() !== '')) return url; + for (const [key] of modes) parsed.searchParams.delete(key); parsed.searchParams.set(SSL_MODE, 'require'); return parsed.toString(); } diff --git a/packages/cli/src/runtime-jobs-retry.test.ts b/packages/cli/src/runtime-jobs-retry.test.ts index c5d8614f6..c190267a6 100644 --- a/packages/cli/src/runtime-jobs-retry.test.ts +++ b/packages/cli/src/runtime-jobs-retry.test.ts @@ -1,5 +1,5 @@ // `jobs.maxAttempts` / `jobs.backoff` as the retry of a job that declares none: installed by the -// boot for every role (`startServices`), by name, and never by reading the worker's config. +// boot every entry point shares (`startQueue`), by name, and never by reading the worker's config. // Split from `runtime-jobs.test.ts` at the size ceiling. import { afterEach, describe, expect, test } from 'bun:test'; @@ -14,6 +14,7 @@ import { resetDefaultRetry } from '@ultimat3/jobs/adapter'; import { loadAppConfig } from './app-config-load'; import { resolveServices } from './runtime-bindings'; import { installJobsRetry, workerConfigOf } from './runtime-jobs'; +import { startQueue } from './runtime-queue'; import { startServices } from './runtime-services'; const dirs: string[] = []; @@ -88,4 +89,22 @@ describe('jobs.maxAttempts and jobs.backoff', () => { }, { timeout: 60_000 }, ); + + test( + 'the queue-only boot installs it: a command that enqueues stamps the attempts the worker runs', + async () => { + // `x tasks run`, `x jobs`, `x db backfill` boot `startQueue` alone, never `startServices`: + // installed only there, a row they enqueued carried 3 while the worker retried by 7. + const sweep = purge({ name: 'sweep', targets: () => [] }); + const root = await appRoot(SEVEN_FIXED); + const env = { ULTIMATE_ENV: 'development' } as const; + const queue = await startQueue(resolveServices(root, env), undefined, env, 'apply'); + try { + expect(sweep.retry).toMatchObject({ attempts: 7, backoff: 'fixed' }); + } finally { + await queue.stop(); + } + }, + { timeout: 60_000 }, + ); }); diff --git a/packages/cli/src/runtime-jobs.ts b/packages/cli/src/runtime-jobs.ts index d41af5912..71f4c9010 100644 --- a/packages/cli/src/runtime-jobs.ts +++ b/packages/cli/src/runtime-jobs.ts @@ -77,7 +77,7 @@ export function installJobsRetry(config: AppConfig | undefined): void { /** * What the boot reads of `jobs.*` for the worker, once. It installs nothing: the default retry is - * every role's, so the boot calls `installJobsRetry` itself (`runtime-services.ts`). + * every role's, so the boot calls `installJobsRetry` itself (`startQueue`, `runtime-queue.ts`). */ export function workerConfigOf(config: AppConfig | undefined, env: Env = {}): WorkerConfig { const fromEnv = workerQueuesFromEnv(env); diff --git a/packages/cli/src/runtime-queue.ts b/packages/cli/src/runtime-queue.ts index 8273b0b6c..09ff4db6c 100644 --- a/packages/cli/src/runtime-queue.ts +++ b/packages/cli/src/runtime-queue.ts @@ -35,10 +35,12 @@ import { resetJobsFacade, setJobsFacade, } from '@ultimat3/jobs'; +import { loadAppConfig } from './app-config-load'; import { applyLockedSchema, ensureSchema } from './framework-schema-apply'; import { appExtensions } from './migration-extensions'; import type { DevServices } from './runtime-bindings'; import { databaseSslOf, withRequiredTls } from './runtime-database-ssl'; +import { installJobsRetry } from './runtime-jobs'; import type { RuntimeOverrides } from './runtime-overrides'; import { QUEUE_PORT_BINDINGS } from './runtime-port-bindings-queue'; import { installPorts, type PortRelease, suppliedOr } from './runtime-ports'; @@ -357,6 +359,10 @@ export async function startQueue( ) { throw poolerSessionRequired('a step that applies migrations'); } + // Here, the boot EVERY entry point shares, and not in `startServices` alone: `x tasks run`, + // `x jobs` and `x db backfill` boot only this, and a row they enqueued was stamped with the + // framework's `max_attempts` while the worker retried by the app's (`jobs.maxAttempts`). + installJobsRetry(await loadAppConfig(services.root)); const { client: db, replica } = startDb(services, env, await databaseSslOf(services)); try { // Pay the Postgres boot here, so the first request is not the slow one and a broken database diff --git a/packages/cli/src/runtime-services.ts b/packages/cli/src/runtime-services.ts index b3d2bb502..2bf8b659f 100644 --- a/packages/cli/src/runtime-services.ts +++ b/packages/cli/src/runtime-services.ts @@ -29,7 +29,7 @@ import type { DevServices, Env } from './runtime-bindings'; import { installBootPorts } from './runtime-boot-ports'; import { selectBus } from './runtime-bus'; import { cacheTiersOf, startCacheTiers } from './runtime-cache'; -import { installJobsRetry, type WorkerConfig, workerConfigOf } from './runtime-jobs'; +import { type WorkerConfig, workerConfigOf } from './runtime-jobs'; import { jobsRetentionTargets } from './runtime-jobs-retention'; import { selectAppMailDriver } from './runtime-mail'; import { inboxRetentionOf } from './runtime-notify-retention'; @@ -281,9 +281,6 @@ async function prepareServices(input: PrepareInput) { // Fourth: `pwa.push` and its VAPID pair (`runtime-push.ts`). Resolving the pair reads env and // signs one probe — a deploy with no keys, or two halves of different pairs, refuses here. const push = await selectWebPush(config, env); - // Every role, never the worker alone: the process that enqueues stamps `max_attempts` from the - // policy the worker retries by. Called here, by name, and not as a side effect of a reader. - installJobsRetry(config); const workerConfig = workerConfigOf(config, env); const bus = selectBus({ env, realtime, roles, override: overrides?.transport, dev }); // `env`, not the ambient one: this function is HANDED the boot's environment and every other diff --git a/packages/cli/src/serve-env.ts b/packages/cli/src/serve-env.ts index 98f7443c0..a0cb954ef 100644 --- a/packages/cli/src/serve-env.ts +++ b/packages/cli/src/serve-env.ts @@ -66,6 +66,14 @@ export function roleFromEnv(env: Env): Role { return role; } +/** + * May this app run `role`? The ONE answer the container's `ROLE` (`assertRoleDeclared`) and + * `x dev`'s selection (`rolesDeclaredForDev`, `role-select.ts`) both ask, by the rule below. + */ +export function roleDeclared(role: Role, config: AppConfig | undefined): boolean { + return config === undefined || role === 'migrate' || config.roles.includes(role); +} + /** * Throws `X_CONFIG_INVALID` when `role` is absent from `config.roles`. Unset, `roles` is every * role (core's default), so an app that never wrote the key boots each one as it always did; so @@ -74,7 +82,8 @@ export function roleFromEnv(env: Env): Role { * migrations to apply. */ export function assertRoleDeclared(role: Role, config: AppConfig | undefined): void { - if (config === undefined || role === 'migrate' || config.roles.includes(role)) return; + if (roleDeclared(role, config)) return; + if (config === undefined) return; const declared = config.roles.map((name) => `'${name}'`); // Members of core's closed `ROLES` set (`defineConfig` refused the rest, `roleFromEnv` the // env's), screened all the same: a fix is pasted, and the guard reads the call, not the proof. diff --git a/packages/cli/src/serve-graph-ceilings-fixture.ts b/packages/cli/src/serve-graph-ceilings-fixture.ts index e1ae093bd..65e5f00a5 100644 --- a/packages/cli/src/serve-graph-ceilings-fixture.ts +++ b/packages/cli/src/serve-graph-ceilings-fixture.ts @@ -350,8 +350,18 @@ * raised 995 → 997, measured 997 (2026-11-19, r9 sweep 2, metafile walk): `db/src/column-drop.ts` * (a column's drop and its two consents, split from `generate.ts` at its ceiling) and * `http/src/fault-report.ts` (what a failed request owes its observers, a late fault included). + * raised 997 → 1011, measured 1011 (2026-11-19, r9 verification fixes, metafile walk against HEAD): + * `db/src/migrate-dev-fix.ts` (the embedded-dev `fix:` line and its environment probe, taken out of + * `migration-errors.ts`: a probe is not a refusal — a real SRP split, worth its one module); + * `cache/src/shared-scopes.ts` (the sender's shared-tier namespace on a bust broadcast); + * `http/src/wire-dates-cap.ts` (the `x-ultimate-dates` header cap); `cli/src/runtime-jobs.ts` + * (`startQueue` installs `jobs.maxAttempts`/`jobs.backoff`, so every enqueueing command stamps the + * worker's retry); and `entity/src/adapter.ts` with the nine driver-kit modules only it reaches + * (`define-driver`, `driver-{counters,delete,kit-types,repo-reads,repo-writes,scope, + * versioned-write,write-scope}.ts`) — `action/src/tx-scope.ts` now reads `memoryTxOpen` off + * `@ultimat3/entity/adapter`, which evaluates the whole subpath barrel. */ -export const MIGRATE_CEILING = 997; +export const MIGRATE_CEILING = 1011; // One import site for the test, which reads both pins from here. export { SERVING_ROLE_CEILING } from './serve-graph-serving-ceiling-fixture'; diff --git a/packages/cli/src/serve-graph-serving-ceiling-fixture.ts b/packages/cli/src/serve-graph-serving-ceiling-fixture.ts index 510188e3f..4421e2084 100644 --- a/packages/cli/src/serve-graph-serving-ceiling-fixture.ts +++ b/packages/cli/src/serve-graph-serving-ceiling-fixture.ts @@ -346,5 +346,9 @@ * hands an MFA-enrolled user their challenge). * raised 1556 → 1558, measured 1558 (2026-11-19, r9 sweep 2): the two on `MIGRATE_CEILING`, * `db/src/column-drop.ts` and `http/src/fault-report.ts`. + * raised 1558 → 1562, measured 1562 (2026-11-19, r9 verification fixes, metafile walk against HEAD): + * `db/src/migrate-dev-fix.ts`, `cache/src/shared-scopes.ts` and `http/src/wire-dates-cap.ts` (the + * three on `MIGRATE_CEILING`) and `cli/src/runtime-cache-frame.ts` (the bust frame's codec, split + * from `runtime-cache.ts`). `runtime-jobs.ts` and the entity driver kit were already on this graph. */ -export const SERVING_ROLE_CEILING = 1558; +export const SERVING_ROLE_CEILING = 1562; diff --git a/packages/cli/src/serve-graph-web-ceiling-fixture.ts b/packages/cli/src/serve-graph-web-ceiling-fixture.ts index e756457b7..572218334 100644 --- a/packages/cli/src/serve-graph-web-ceiling-fixture.ts +++ b/packages/cli/src/serve-graph-web-ceiling-fixture.ts @@ -303,5 +303,7 @@ * Nothing web-only. * raised 1756 → 1758, measured 1758 (2026-11-19, r9 sweep 2): the two on `SERVING_ROLE_CEILING`. * Nothing web-only. + * raised 1758 → 1762, measured 1762 (2026-11-19, r9 verification fixes): the four on + * `SERVING_ROLE_CEILING`. Nothing web-only. */ -export const WEB_ROLE_CEILING = 1758; +export const WEB_ROLE_CEILING = 1762; diff --git a/packages/cli/src/stop-run-start.test.ts b/packages/cli/src/stop-run-start.test.ts new file mode 100644 index 000000000..e3011d0d5 --- /dev/null +++ b/packages/cli/src/stop-run-start.test.ts @@ -0,0 +1,37 @@ +// "Stop the holder, run it alone, start again" is one line with one quoting rule: every site that +// prints it asks the builder, so the four spellings cannot come back. + +import { describe, expect, test } from 'bun:test'; +// why: Bun ships no path API; `join` reaches each module from this directory. +import { join } from 'node:path'; +import { stopRunStartFix } from './stop-run-start'; + +const DIR = import.meta.dir; + +describe('unit · stop, run it, start again', () => { + test('the command runs between x stop and x dev, word by word', () => { + expect(stopRunStartFix(['db', 'migrate'])).toBe('x stop --json && x db migrate && x dev'); + expect(stopRunStartFix(['db', 'rollback', '--steps', '2'])).toBe( + 'x stop --json && x db rollback --steps 2 && x dev', + ); + }); + + test('a word the shell would split or run is quoted, never spliced', () => { + expect(stopRunStartFix(['db', 'seed', 'a b; rm -rf /'])).toBe( + "x stop --json && x db seed 'a b; rm -rf /' && x dev", + ); + }); + + test('no other module assembles the line by hand', async () => { + const byHand: string[] = []; + for await (const file of new Bun.Glob('*.{ts,tsx}').scan({ cwd: DIR })) { + if (file.includes('.test.') || file === 'stop-run-start.ts') continue; + const text = await Bun.file(join(DIR, file)).text(); + // A restart (`x stop --json && x dev`) is another instruction: nothing runs in between. + if (/x stop --json && x (?!dev\b)/.test(text) || /'stop', '--json', '&&'/.test(text)) { + byHand.push(file); + } + } + expect(byHand).toEqual([]); + }); +}); diff --git a/packages/cli/src/stop-run-start.ts b/packages/cli/src/stop-run-start.ts new file mode 100644 index 000000000..9fc0c61df --- /dev/null +++ b/packages/cli/src/stop-run-start.ts @@ -0,0 +1,12 @@ +// The one "stop the holder, run it alone, start again" fix line: what a command that needs the +// embedded database to itself is told beside a live `x dev`. One builder, one quoting rule. + +import { quoteArg } from './shell-quote'; + +/** + * `x stop --json && x <command> && x dev`. `x stop`, not `kill <pid>`: a kill returns before the + * drain ends and the next boot refuses. `command` is the refused command's own words, each quoted + * on its own (`quoteArg`), never spliced; a caller's trailing `# remark` goes after the line. + */ +export const stopRunStartFix = (command: readonly string[]): string => + ['x', 'stop', '--json', '&&', 'x', ...command.map(quoteArg), '&&', 'x', 'dev'].join(' '); diff --git a/packages/cli/src/templates/sign-in-action-tests.ts b/packages/cli/src/templates/sign-in-action-tests.ts index fdf516a0f..6bf68b8db 100644 --- a/packages/cli/src/templates/sign-in-action-tests.ts +++ b/packages/cli/src/templates/sign-in-action-tests.ts @@ -77,9 +77,9 @@ export const createSessionTest = (): string => `// createSession, run inside a real request over the app's migrated database: a wrong password is // refused, a right one sets the session cookie, and a second factor still owed holds the challenge. import { toRoute } from '@ultimat3/action'; -import { generateTotpSecret, register, saveTotpSecret } from '@ultimat3/auth'; +import { generateTotpSecret, MFA_CHALLENGE_COOKIE, register, saveTotpSecret } from '@ultimat3/auth'; ${SHARED_IMPORTS} -import { MFA_CHALLENGE_COOKIE, SECOND_FACTOR_PATH } from '../sign-in-challenge'; +import { SECOND_FACTOR_PATH } from '../sign-in-challenge'; import { AFTER_SIGN_IN } from '../sign-in-flow'; import { createSession } from './create-session'; @@ -146,47 +146,26 @@ unitTest('a second factor still owed holds the challenge and sets no session', a }); `; -/** - * Where the test reads the sealed challenge and its cookie's name from. The password shape's own - * module exports both; the OIDC shape's challenge is auth's cookie, so its test derives them. - */ -export interface ChallengeAccess { - /** Extra names for the `@ultimat3/auth` import, already sorted into it. */ - readonly authImports: readonly string[]; - /** Import lines after the shared ones, and declarations after the database block. */ - readonly imports: readonly string[]; - readonly prelude: string; -} - -const PASSWORD_CHALLENGE: ChallengeAccess = { - authImports: [], - imports: ["import { challengeOf, MFA_CHALLENGE_COOKIE } from '../sign-in-challenge';"], - prelude: '', -}; - -export const confirmSessionTest = ( - access: ChallengeAccess = PASSWORD_CHALLENGE, -): string => `// confirmSession, run inside a real request over the app's migrated database: with no challenge +export const confirmSessionTest = + (): string => `// confirmSession, run inside a real request over the app's migrated database: with no challenge // held it refuses, a wrong code is refused, and the held challenge plus the right code signs in. +// The challenge and its cookie's name are auth's, whichever shape's first leg held it. import { toRoute } from '@ultimat3/action'; import { -${[ - ...access.authImports, - 'generateTotpSecret', - 'login', - 'register', - 'saveTotpSecret', - 'totpCode', - 'totpStep', -] - .map((name) => ` ${name},`) - .join('\n')} + generateTotpSecret, + login, + MFA_CHALLENGE_COOKIE, + mfaChallengeOf, + register, + saveTotpSecret, + totpCode, + totpStep, } from '@ultimat3/auth'; ${SHARED_IMPORTS} -${[...access.imports, "import { confirmSession } from './confirm-session';"].join('\n')} +import { confirmSession } from './confirm-session'; ${DATABASE} -${access.prelude} + const target = confirmSession.named('confirmSession'); const PASSWORD = 'a long scaffold test passphrase'; @@ -207,7 +186,7 @@ const challenged = async (email: string) => { const secret = generateTotpSecret(); await saveTotpSecret(appAuth(), user.id, secret); const first = await login(appAuth(), { email, password: PASSWORD }).catch((e: unknown) => e); - const challenge = challengeOf(first); + const challenge = mfaChallengeOf(first); expect(challenge).not.toBeNull(); return { secret, cookie: \`\${MFA_CHALLENGE_COOKIE}=\${challenge}\` }; }; diff --git a/packages/cli/src/templates/sign-in-challenge.ts b/packages/cli/src/templates/sign-in-challenge.ts new file mode 100644 index 000000000..87a4bb2ad --- /dev/null +++ b/packages/cli/src/templates/sign-in-challenge.ts @@ -0,0 +1,62 @@ +// `sign-in-challenge.ts` as both `x g sign-in` shapes write it: the second-factor challenge rides +// auth's ONE cookie (`__Host-x_mfa`), written, read and cleared through `@ultimat3/auth`. The +// password shape also holds it (its own first leg); OIDC's is held by `oauthLogin({ mfaPath })`. + +import { SIGN_IN_PATH } from './sign-in-shared'; + +const HEADER: Readonly<Record<'password' | 'oidc', string>> = { + password: `// The second-factor challenge between the two legs: a sealed, five-minute credential \`login()\` +// hands back inside \`X_MFA_REQUIRED\`, carried in auth's own HttpOnly cookie — never a URL a log +// keeps — and read back by \`confirmSession\` through here.`, + oidc: `// The second-factor challenge between the provider's callback and the code. \`oauthLogin({ mfaPath })\` +// sends an enrolled user to SECOND_FACTOR_PATH with it sealed in auth's own HttpOnly cookie — never +// a URL a log keeps — and \`confirmSession\` reads it back through here.`, +}; + +const PATH_DOC: Readonly<Record<'password' | 'oidc', string>> = { + password: + '/** Where `createSession` sends a person who owes a code, and the page that posts it. */', + oidc: '/** The `mfaPath` `oidc.ts` hands `oauthLogin`, and the page that posts the code. */', +}; + +const HOLD = ` +/** Auth's own line: the cookie a built-in callback sets, living as long as the challenge. */ +export const holdChallenge = (challenge: string): void => { + useRequestContext('holdChallenge').headers.append('set-cookie', mfaChallengeCookie(challenge)); +}; +`; + +export const challengeSource = (shape: 'password' | 'oidc'): string => { + const names = [ + 'clearMfaChallengeCookie', + ...(shape === 'password' ? ['mfaChallengeCookie'] : []), + 'readMfaChallenge', + ]; + return `${HEADER[shape]} +import { ${names.join(', ')} } from '@ultimat3/auth'; +import { useRequestContext, useRequestHeaders } from '@ultimat3/http'; + +${PATH_DOC[shape]} +export const SECOND_FACTOR_PATH = '${SIGN_IN_PATH}/second-factor'; +${shape === 'password' ? HOLD : ''} +export const heldChallenge = (): string | null => { + const value = readMfaChallenge({ headers: useRequestHeaders() }); + return value === null || value === '' ? null : value; +}; + +/** Auth's own clearing line, relayed as it is: the cookie's name and attributes are auth's. */ +export const dropChallenge = (): void => { + useRequestContext('dropChallenge').headers.append('set-cookie', clearMfaChallengeCookie()); +}; +`; +}; + +export const challengeTest = + (): string => `// The path the second leg lives at is the page this app serves the second-factor form at. +import { expect, unitTest } from '@ultimat3/testing'; +import { SECOND_FACTOR_PATH } from './sign-in-challenge'; + +unitTest('the second leg lives under the sign-in page', () => { + expect(SECOND_FACTOR_PATH).toBe('${SIGN_IN_PATH}/second-factor'); +}); +`; diff --git a/packages/cli/src/templates/sign-in-oidc-mfa.ts b/packages/cli/src/templates/sign-in-oidc-mfa.ts index 6e6ef4655..8155e06b6 100644 --- a/packages/cli/src/templates/sign-in-oidc-mfa.ts +++ b/packages/cli/src/templates/sign-in-oidc-mfa.ts @@ -3,58 +3,11 @@ // scaffold passes that path and ships the page and the action behind it (auth README, MFA). import type { GeneratedFile } from './naming'; -import { type ChallengeAccess, confirmSessionTest } from './sign-in-action-tests'; +import { confirmSessionTest } from './sign-in-action-tests'; +import { challengeSource, challengeTest } from './sign-in-challenge'; import { secondFactorSource, signInPageTest } from './sign-in-pages'; import { confirmSessionSource, POSTS_AT } from './sign-in-password'; -import { AUTH_DIR, SIGN_IN_PATH } from './sign-in-shared'; - -const challengeSource = - (): string => `// The second-factor challenge between the provider's callback and the code. \`oauthLogin({ mfaPath })\` -// sends an enrolled user to SECOND_FACTOR_PATH with it sealed in auth's own HttpOnly cookie — never -// a URL a log keeps — and \`confirmSession\` reads it back through here. -import { clearMfaChallengeCookie, readMfaChallenge } from '@ultimat3/auth'; -import { useRequestContext, useRequestHeaders } from '@ultimat3/http'; - -/** The \`mfaPath\` \`oidc.ts\` hands \`oauthLogin\`, and the page that posts the code. */ -export const SECOND_FACTOR_PATH = '${SIGN_IN_PATH}/second-factor'; - -export const heldChallenge = (): string | null => { - const value = readMfaChallenge({ headers: useRequestHeaders() }); - return value === null || value === '' ? null : value; -}; - -/** Auth's own clearing line, relayed as it is: the cookie's name and attributes are auth's. */ -export const dropChallenge = (): void => { - useRequestContext('dropChallenge').headers.append('set-cookie', clearMfaChallengeCookie()); -}; -`; - -const challengeTest = - (): string => `// The path the callback redirects to is the page this app serves the second-factor form at. -import { expect, unitTest } from '@ultimat3/testing'; -import { SECOND_FACTOR_PATH } from './sign-in-challenge'; - -unitTest('the second leg lives under the sign-in page', () => { - expect(SECOND_FACTOR_PATH).toBe('${SIGN_IN_PATH}/second-factor'); -}); -`; - -/** The confirm test reads the challenge off `login()`'s refusal and names auth's own cookie. */ -const OIDC_CHALLENGE: ChallengeAccess = { - authImports: ['clearMfaChallengeCookie'], - imports: [], - prelude: ` -/** The cookie the callback seals the challenge in, read off the line that clears it. */ -const MFA_CHALLENGE_COOKIE = clearMfaChallengeCookie().split('=')[0] ?? ''; - -/** The sealed challenge an \`X_MFA_REQUIRED\` carries, or \`null\` for any other throw. */ -const challengeOf = (error: unknown): string | null => { - const meta = (error as { meta?: Readonly<Record<string, unknown>> } | null)?.meta; - const challenge = meta?.['challenge']; - return typeof challenge === 'string' && challenge !== '' ? challenge : null; -}; -`, -}; +import { AUTH_DIR } from './sign-in-shared'; /** The `import` and the option `oidc.ts` gains: the callback's way to the second-factor page. */ export const OIDC_MFA_IMPORT = "import { SECOND_FACTOR_PATH } from './sign-in-challenge';"; @@ -62,12 +15,12 @@ export const OIDC_MFA_OPTION = 'mfaPath: SECOND_FACTOR_PATH,'; export function oidcSecondFactorFiles(module: string | undefined): readonly GeneratedFile[] { return [ - { path: `${AUTH_DIR}/sign-in-challenge.ts`, contents: challengeSource() }, + { path: `${AUTH_DIR}/sign-in-challenge.ts`, contents: challengeSource('oidc') }, { path: `${AUTH_DIR}/sign-in-challenge.test.ts`, contents: challengeTest() }, { path: `${AUTH_DIR}/actions/confirm-session.ts`, contents: confirmSessionSource() }, { path: `${AUTH_DIR}/actions/confirm-session.test.ts`, - contents: confirmSessionTest(OIDC_CHALLENGE), + contents: confirmSessionTest(), }, { path: `${AUTH_DIR}/sign-in/second-factor/page.tsx`, contents: secondFactorSource(module) }, { diff --git a/packages/cli/src/templates/sign-in-oidc.test.ts b/packages/cli/src/templates/sign-in-oidc.test.ts index 3b22928cf..4640c3773 100644 --- a/packages/cli/src/templates/sign-in-oidc.test.ts +++ b/packages/cli/src/templates/sign-in-oidc.test.ts @@ -78,7 +78,11 @@ describe('unit · x g sign-in --oidc carries an MFA-enrolled user through', () = // The cookie is named by auth alone: no generated file spells it. for (const [path, contents] of files) { expect(`${path}: ${contents.includes('__Host-x_mfa')}`).toBe(`${path}: false`); + // …and none recovers the name from a serialised line, or re-reads `meta.challenge` by hand. + expect(`${path}: ${contents.includes(".split('=')")}`).toBe(`${path}: false`); + expect(`${path}: ${contents.includes("meta?.['challenge']")}`).toBe(`${path}: false`); } + expect(ofName('/actions/confirm-session.test.ts')).toContain(' MFA_CHALLENGE_COOKIE,\n'); }); test('every locale gets the second-factor copy the page renders', () => { diff --git a/packages/cli/src/templates/sign-in-password.test.ts b/packages/cli/src/templates/sign-in-password.test.ts index 025cf9559..edb4d4414 100644 --- a/packages/cli/src/templates/sign-in-password.test.ts +++ b/packages/cli/src/templates/sign-in-password.test.ts @@ -36,4 +36,23 @@ describe('unit · password sign-in keeps ?next= across the second factor', () => '<input type="hidden" name={NEXT_PARAM} value={nextPath(props.query?.[NEXT_PARAM])} />', ); }); + + // One MFA challenge cookie (auth's `__Host-x_mfa`): the scaffold neither names one of its own + // nor re-implements how a challenge is read off `X_MFA_REQUIRED`. + test('the challenge is held, read and dropped through auth, in auth’s own cookie', () => { + const challenge = source('sign-in-challenge.ts'); + expect(challenge).toContain("headers.append('set-cookie', mfaChallengeCookie(challenge))"); + expect(challenge).toContain('readMfaChallenge({ headers: useRequestHeaders() })'); + expect(challenge).toContain("headers.append('set-cookie', clearMfaChallengeCookie())"); + expect(source('actions/create-session.ts')).toContain('mfaChallengeOf(error)'); + for (const file of files) { + if (typeof file.contents !== 'string') continue; + for (const own of ['x_mfa_challenge', '__Host-x_mfa', "error.meta?.['challenge']"]) { + expect(`${file.path}: ${file.contents.includes(own)}`).toBe(`${file.path}: false`); + } + expect(`${file.path}: ${/\bsetCookie\(|\bdeleteCookie\(/.test(file.contents)}`).toBe( + `${file.path}: false`, + ); + } + }); }); diff --git a/packages/cli/src/templates/sign-in-password.ts b/packages/cli/src/templates/sign-in-password.ts index 25aa4e48d..2de149d58 100644 --- a/packages/cli/src/templates/sign-in-password.ts +++ b/packages/cli/src/templates/sign-in-password.ts @@ -6,6 +6,7 @@ import { catalogJson } from './catalog-json'; import { catalogPath } from './locales'; import type { GeneratedFile } from './naming'; import { confirmSessionTest, createSessionTest } from './sign-in-action-tests'; +import { challengeSource, challengeTest } from './sign-in-challenge'; import { SIGN_IN_CATALOG, type SignInForm, @@ -14,66 +15,21 @@ import { signInPageSource, signInPageTest, } from './sign-in-pages'; -import { AUTH_DIR, SIGN_IN_PATH, sharedSignInFiles } from './sign-in-shared'; +import { AUTH_DIR, sharedSignInFiles } from './sign-in-shared'; /** The master key seals the second-factor challenge between the two legs. */ export const PASSWORD_SIGN_IN_ENV: readonly string[] = ['ULTIMATE_SECRETS_KEY']; -const challengeSource = - (): string => `// The second-factor challenge between the two legs: a sealed, five-minute credential \`login()\` -// hands back inside \`X_MFA_REQUIRED\`, carried in an HttpOnly cookie rather than a URL a log keeps. -import { MFA_CHALLENGE_TTL_MS } from '@ultimat3/auth'; -import { isUltimateError } from '@ultimat3/core'; -import { deleteCookie, setCookie, useRequestCookie } from '@ultimat3/http'; - -export const MFA_CHALLENGE_COOKIE = 'x_mfa_challenge'; -export const SECOND_FACTOR_PATH = '${SIGN_IN_PATH}/second-factor'; - -/** The sealed challenge an \`X_MFA_REQUIRED\` carries, or \`null\` for any other throw. */ -export const challengeOf = (error: unknown): string | null => { - if (!isUltimateError(error) || error.code !== 'X_MFA_REQUIRED') return null; - const challenge = error.meta?.['challenge']; - return typeof challenge === 'string' && challenge !== '' ? challenge : null; -}; - -export const holdChallenge = (challenge: string): void => - setCookie(MFA_CHALLENGE_COOKIE, challenge, { maxAge: Math.floor(MFA_CHALLENGE_TTL_MS / 1000) }); - -export const heldChallenge = (): string | null => { - const value = useRequestCookie(MFA_CHALLENGE_COOKIE); - return value === null || value === '' ? null : value; -}; - -export const dropChallenge = (): void => deleteCookie(MFA_CHALLENGE_COOKIE); -`; - -const challengeTest = - (): string => `// Only an X_MFA_REQUIRED carrying a challenge is a second leg; every other throw is not. -import { UltimateError } from '@ultimat3/core'; -import { expect, unitTest } from '@ultimat3/testing'; -import { challengeOf } from './sign-in-challenge'; - -const coded = (code: string, meta?: Record<string, unknown>) => - new UltimateError({ code, cause: 'a test throw', fix: 'none', ...(meta ? { meta } : {}) }); - -unitTest('a sealed challenge is read off X_MFA_REQUIRED, and nothing else is one', () => { - expect(challengeOf(coded('X_MFA_REQUIRED', { challenge: 'sealed' }))).toBe('sealed'); - expect(challengeOf(coded('X_MFA_REQUIRED'))).toBeNull(); - expect(challengeOf(coded('X_UNAUTHENTICATED', { challenge: 'sealed' }))).toBeNull(); - expect(challengeOf('X_MFA_REQUIRED')).toBeNull(); -}); -`; - const createSessionSource = (): string => `// Sign in with an address and a password. \`login()\` is the whole check — the hash, the lockout and // one indistinguishable \`X_UNAUTHENTICATED\` for every way a credential is wrong. A second factor // still owed stops here with the sealed challenge held for the next page. import { action, t } from '@ultimat3/action'; -import { login } from '@ultimat3/auth'; +import { login, mfaChallengeOf } from '@ultimat3/auth'; import { useRequestContext } from '@ultimat3/http'; import { allow } from '@ultimat3/policy'; import { appAuth } from '../auth'; -import { challengeOf, holdChallenge, SECOND_FACTOR_PATH } from '../sign-in-challenge'; +import { holdChallenge, SECOND_FACTOR_PATH } from '../sign-in-challenge'; import { NEXT_PARAM, nextPath } from '../sign-in-flow'; export const createSession = action({ @@ -99,7 +55,7 @@ export const createSession = action({ request.headers.append('set-cookie', signedIn.cookie); return { ok: true, next: nextPath(input[NEXT_PARAM]), secondFactor: false }; } catch (error) { - const challenge = challengeOf(error); + const challenge = mfaChallengeOf(error); if (challenge === null) throw error; holdChallenge(challenge); // The way on survives the second leg: its form posts \`next\` back to \`confirmSession\`. @@ -114,7 +70,7 @@ export const createSession = action({ }); `; -/** Both shapes' second leg: it reads the challenge through `../sign-in-challenge`, whichever holds it. */ +/** Both shapes' second leg: it reads the challenge through `../sign-in-challenge`, whoever held it. */ export const confirmSessionSource = (): string => `// The second leg: the six digits (or one recovery code) against the challenge the first leg held. // \`completeMfa()\` meters the guess against the same lockout a password guess spends. @@ -195,7 +151,7 @@ export function passwordSignInFiles(options: SignInTemplateOptions): readonly Ge PASSWORD_SIGN_IN_ENV, 'The master key seals the second-factor challenge between the two legs.', ), - { path: `${AUTH_DIR}/sign-in-challenge.ts`, contents: challengeSource() }, + { path: `${AUTH_DIR}/sign-in-challenge.ts`, contents: challengeSource('password') }, { path: `${AUTH_DIR}/sign-in-challenge.test.ts`, contents: challengeTest() }, { path: `${AUTH_DIR}/actions/create-session.ts`, contents: createSessionSource() }, { diff --git a/packages/core/src/error-reporter-sentry-dsn.test.ts b/packages/core/src/error-reporter-sentry-dsn.test.ts new file mode 100644 index 000000000..db5150455 --- /dev/null +++ b/packages/core/src/error-reporter-sentry-dsn.test.ts @@ -0,0 +1,33 @@ +// A DSN the parser refuses is described, never echoed: a legacy `key:secret@` DSN carries a +// credential, and the refusal lands in a log line and an error's `meta` where nothing redacts it. + +import { describe, expect, test } from 'bun:test'; +import { parseSentryDsn } from './error-reporter-sentry'; +import { isUltimateError } from './errors'; + +/** The refusal's cause and meta, rendered as one string to search. */ +function refusalText(dsn: string): string { + try { + parseSentryDsn(dsn); + } catch (error) { + if (!isUltimateError(error)) return expect.unreachable('not an UltimateError'); + expect(error.code).toBe('X_ERROR_REPORTER_DSN_INVALID'); + return `${error.cause} ${JSON.stringify(error.meta)}`; + } + return expect.unreachable('the DSN was accepted'); +} + +describe('a refused DSN never echoes its secret', () => { + test('a scheme-less key:secret DSN never echoes the secret', () => { + // `new URL` reads `pub:` as the scheme and `sekrit@host/1` as an opaque path. + const text = refusalText('pub:sekrit@errors.example.com/1'); + expect(text).not.toContain('sekrit'); + expect(text).not.toContain('pub:'); + }); + + test('an http DSN with no key names where it points, still without userinfo', () => { + const text = refusalText('https://:sekrit@errors.example.com/'); + expect(text).not.toContain('sekrit'); + expect(text).toContain('errors.example.com'); + }); +}); diff --git a/packages/core/src/error-reporter-sentry.ts b/packages/core/src/error-reporter-sentry.ts index df0e1095f..261cf2a3e 100644 --- a/packages/core/src/error-reporter-sentry.ts +++ b/packages/core/src/error-reporter-sentry.ts @@ -67,7 +67,10 @@ export function parseSentryDsn(dsn: string): SentryDsn { projectId === undefined ) { // The userinfo dropped, as in the cause: the key and any legacy secret stay out of `meta`. - const where = `${url.protocol}//${url.host}${url.pathname}`; + // Only an HTTP URL HAS a userinfo to drop: a scheme-less `key:secret@host/1` parses as scheme + // `key:` over an opaque path `secret@host/1`, so it is described, never spelled. + const http = url.protocol === 'https:' || url.protocol === 'http:'; + const where = http ? `${url.protocol}//${url.host}${url.pathname}` : describeValue(dsn); throw new ErrorReporterDsnInvalidError({ cause: `"${where}" has no publicKey, no projectId or a non-HTTP scheme`, fix: DSN_FIX, diff --git a/packages/core/src/lifecycle-deadline.test.ts b/packages/core/src/lifecycle-deadline.test.ts index 9096babff..6af571565 100644 --- a/packages/core/src/lifecycle-deadline.test.ts +++ b/packages/core/src/lifecycle-deadline.test.ts @@ -252,4 +252,39 @@ describe('the drain deadline', () => { expect(drift).toBeLessThan(deadlineMs * 2); expect(seen).toBeGreaterThan(systemClock.monotonic()); }); + + test("the reason carries where the in-flight wait ends: the deadline less the hooks' reserve", async () => { + configureLifecycle({ deadlineMs: 10_000 }); + const seen: { deadlineAt: number; inflightUntil: number | undefined }[] = []; + onShutdown( + 'probe', + (reason) => { + seen.push({ deadlineAt: reason.deadlineAt, inflightUntil: reason.inflightUntil }); + }, + { phase: 'accept' }, + ); + onShutdown('pool', () => undefined); + + await drain('SIGTERM'); + + // One owner of the instant: a role that cuts its own work short measures back from it. + expect(seen).toHaveLength(1); + expect((seen[0]?.deadlineAt ?? 0) - (seen[0]?.inflightUntil ?? 0)).toBe(2_000); + }); + + test('with no inflight or close hook there is no reserve: the wait ends at the deadline', async () => { + configureLifecycle({ deadlineMs: 10_000 }); + let gap: number | undefined; + onShutdown( + 'probe', + (reason) => { + gap = reason.deadlineAt - (reason.inflightUntil ?? Number.NaN); + }, + { phase: 'accept' }, + ); + + await drain('SIGTERM'); + + expect(gap).toBe(0); + }); }); diff --git a/packages/core/src/lifecycle-types.ts b/packages/core/src/lifecycle-types.ts index f0b68735e..dc244941a 100644 --- a/packages/core/src/lifecycle-types.ts +++ b/packages/core/src/lifecycle-types.ts @@ -30,6 +30,14 @@ export interface ShutdownReason { * `waitForIdle` went on sleeping on a real `setTimeout`. `clock` still owns `uptimeMs`. */ readonly deadlineAt: number; + /** + * Real monotonic ms at which the drain stops waiting for in-flight work (`beginWork()`), at or + * before `deadlineAt`: the rest of the budget is the `inflight`/`close` hooks' reserve. The ONE + * owner of that instant — a role that cuts its own work short (the jobs worker's cut-off) + * measures back from it, so the cut work has unwound before the wait ends. Absent on a reason + * built outside `drain()`: read it as `deadlineAt`. + */ + readonly inflightUntil?: number | undefined; } export type ShutdownHook = (reason: ShutdownReason) => void | Promise<void>; diff --git a/packages/core/src/lifecycle.ts b/packages/core/src/lifecycle.ts index fa2d3c1ac..97f6491f2 100644 --- a/packages/core/src/lifecycle.ts +++ b/packages/core/src/lifecycle.ts @@ -336,15 +336,18 @@ async function runDrain(signal: string): Promise<void> { const grace = readinessGraceMs(); report('info', 'draining', { signal, deadlineMs, readinessGraceMs: grace, inflight }); if (grace > 0) await Bun.sleep(grace); - const reason: ShutdownReason = { signal, deadlineAt: systemClock.monotonic() + deadlineMs }; + // A stuck request must not starve the hooks behind it to 0 ms: the OTLP flush that carries + // this very incident and the pool close get a slice the in-flight wait never spends. Decided + // BEFORE the `accept` phase and handed to it as `inflightUntil`: a role cutting its own work + // short (the jobs worker) must finish before this wait ends, not race it to the same instant. + const reserve = laterHooksReserveMs(); + const deadlineAt = systemClock.monotonic() + deadlineMs; + const reason: ShutdownReason = { signal, deadlineAt, inflightUntil: deadlineAt - reserve }; await runPhase('accept', reason); // Real monotonic, like `deadlineAt` itself: `waitForIdle` sleeps on a real `setTimeout`, and // a budget read off an injected clock is a number that timer will never honour. - // A stuck request must not starve the hooks behind it to 0 ms: the OTLP flush that carries - // this very incident and the pool close get a slice the in-flight wait never spends. - const reserve = laterHooksReserveMs(); - const remaining = Math.max(0, reason.deadlineAt - systemClock.monotonic() - reserve); + const remaining = Math.max(0, deadlineAt - reserve - systemClock.monotonic()); const idle = await waitForIdle(remaining); if (!idle) { abandoned = true; diff --git a/packages/db/README.md b/packages/db/README.md index b8a27c7f8..c920cc7db 100644 --- a/packages/db/README.md +++ b/packages/db/README.md @@ -73,7 +73,7 @@ await withTransaction(async (tx) => { | `isNonTransactional()` / `NO_TRANSACTION_MARKER` / `isConcurrentIndexStatement()` / `concurrentIndexTarget()` | `As of 2026-10-31`: the `-- transaction: false` marker a migration carries to run outside a transaction, and the concurrent index statements that need it → [Indexes built concurrently](#indexes-built-concurrently-and-every-index-drop) | | `rollingUnsafeStatements()` / `hasRollingUnsafeMarker()` / `ROLLING_UNSAFE_MARKER` / `retiredColumnsIn()` / `retireAndContractPending()` / `migrationRollingUnsafe()` | `As of 2026-11-02`: the rolling-deploy rail — would the previous release trip over this `up`? A closed list (`drop column` with no earlier `-- retires`, `rename column`, `rename table`), read by the `drift` step past `rollingSince`, and the pair `migrate()` refuses pending together in production | | `recordRetired()` | `As of 2026-11-02`: `snapshotOf` one step on, keeping a retired column and what hangs off it on the record. `x db gen` and the `drift` step both read through it, so they cannot disagree about one | -| a column leaving a table (`column-drop.ts`) | `As of 2026-11-19`: a plain column declared `generated` is `drop column` + `add column`, so it is asked what an ordinary drop is asked — `X_MIGRATION_ROLLING_UNSAFE` unless the column was retired first or `rollingUnsafe` is set, then `X_MIGRATION_IRREVERSIBLE` unless `allowDestructive` — and the result carries `rollingUnsafe: true` for a column never retired. The `down` of any column drop re-creates the indexes and foreign keys the previous snapshot recorded over the column (a key whose target table the same migration drops is a `--` note); the rows are not restored. A `.snapshot.json` whose `dataType` holds a second statement is not a snapshot (`parseSnapshot` answers `undefined`) | +| a column leaving a table (`column-drop.ts`) | `As of 2026-11-19`: a plain column declared `generated` is `drop column` + `add column`, so it is asked what an ordinary drop is asked — `X_MIGRATION_ROLLING_UNSAFE` unless the column was retired first or `rollingUnsafe` is set, then `X_MIGRATION_IRREVERSIBLE` unless `allowDestructive` — and the result carries `rollingUnsafe: true` for a column never retired. The `down` of any column drop re-creates the indexes and foreign keys the previous snapshot recorded over the column (a key whose target table the same migration drops is a `--` note); the rows are not restored. An index counts as over the column when it depends on it any way Postgres drops it for — a key, an `include` column, a partial predicate or an expression that reads it — so its restore is in the drop's own `down`, never a follow-up step's. A `.snapshot.json` whose `dataType` holds a second statement is not a snapshot (`parseSnapshot` answers `undefined`) | | `destructiveStatements()` / `hasDestructiveMarker()` / `isDestructiveMigration()` / `DESTRUCTIVE_MARKER` | `As of 2026-08`: the destructive-SQL rail — does this `up` drop, truncate or retype, and does the file declare it with `-- destructive: true`? One classifier, read by `x db gen` when it writes the marker and by `x verify` when it demands one | | `stripSqlNoise()` | comments, literals, dollar-quoted bodies and quoted identifiers blanked **in source order**, so a reader sees the operation and not the prose. Shared by `readOnlyQuery()` and the destructive rail | | `introspectSchema()` | live schema → `SchemaDescription`. **App tables only**, `As of 2026-08-24`: a relation an extension owns (`pg_depend`, `deptype = 'e'`) and anything that is not an ordinary or partitioned table are excluded before the fold, and an explicit `exclude` cannot bring them back. **A partition is not app schema either** (`relispartition`, `As of 2026-11-06`): its parent is judged — keys, indexes, checks, triggers — and carries `partitioned: true`; a key Postgres clones per partition (`conparentid <> 0`) is not read | diff --git a/packages/db/src/column-drop.ts b/packages/db/src/column-drop.ts index 542ed3630..55b3aff04 100644 --- a/packages/db/src/column-drop.ts +++ b/packages/db/src/column-drop.ts @@ -12,6 +12,7 @@ import type { ColumnDescription, TableDescription } from './introspect'; import { migrationIrreversible } from './migration-errors'; import { migrationNameArg } from './primary-key'; import { contractsMarkerFor } from './retired'; +import { indexDependsOn } from './retype-dependents'; import { columnDropNotRetired, columnRebuildNotRetired } from './rolling-errors'; import { identifier } from './sql'; @@ -82,7 +83,8 @@ export function admitRebuilds( /** * What hung off the dropped columns, as the previous snapshot recorded it: `drop column` took every - * index and foreign key over one, and `add column` brings none of them back. Without these a + * foreign key over one and every index that depends on one (`indexDependsOn`: a key, an INCLUDE + * column, a predicate or an expression that reads it), and `add column` brings none of them back. Without these a * rollback left a database its own snapshot called drifted (`missing-index`, * `missing-foreign-key`), and the `down` before it dropped a constraint that was not there * (`42704`). A CHECK is `checkPlan`'s, already restored. @@ -109,7 +111,7 @@ function restoreDependents( ); } for (const index of live.indexes) { - if (index.primary || !over(index.columns)) continue; + if (index.primary || ![...dropped].some((column) => indexDependsOn(index, column))) continue; restores.push(createIndex(live.name, asDeclared(index))); } plan.down.push(...restores.filter((statement) => !plan.down.includes(statement))); diff --git a/packages/db/src/generate-rolling.test.ts b/packages/db/src/generate-rolling.test.ts index 12931393d..0a49688c6 100644 --- a/packages/db/src/generate-rolling.test.ts +++ b/packages/db/src/generate-rolling.test.ts @@ -230,6 +230,53 @@ describe('the printed path, end to end', () => { expect(at('create index "posts_legacy_idx"')).toBeGreaterThan(at('add column "legacy"')); }); + // `drop column` takes every index that DEPENDS on the column, not only one keyed by it. Left to + // the removal step, its `down` was `create index … where ("legacy" …)` on a table with no + // `legacy` (42703), and the drop's own snapshot still recorded an index the database had lost. + test('a partial index whose predicate reads the dropped column is restored by the drop’s own down', () => { + const plain = { unique: false, order: null }; + const before = tableOf('posts', [textColumn('legacy'), textColumn('title')], { + indexes: [ + { name: 'posts_p', columns: ['title'], where: '"legacy" is not null', ...plain }, + { + name: 'posts_e', + columns: ['legacy'], + expression: 'lower(legacy)', + where: null, + ...plain, + }, + { name: 'posts_i', columns: ['title'], include: ['legacy'], where: null, ...plain }, + // Kept by the entity and tied to nothing leaving: no arm may touch it. `'legacy'` here is + // data, never a reference. + { name: 'posts_k', columns: ['title'], where: "title <> 'legacy'", ...plain }, + ], + }); + const after = tableOf('posts', [textColumn('title')], { + indexes: [{ name: 'posts_k', columns: ['title'], where: "title <> 'legacy'", ...plain }], + }); + const drop = generateMigration({ + entities: [after], + current: snapshotOf([before]), + name: 'drop', + now: AT, + allowDestructive: true, + rollingUnsafe: true, + }); + const down = statementsOf(drop.down); + const at = (needle: string): number => down.findIndex((each) => each.includes(needle)); + for (const name of ['posts_p', 'posts_e', 'posts_i']) { + expect(`${name}: ${at(`create index "${name}"`) > at('add column "legacy"')}`).toBe( + `${name}: true`, + ); + // Postgres already took it with the column: no drop beside it, here or in a follow-up. + expect(`${drop.up}${drop.followUp?.up ?? ''}`).not.toContain(`"${name}"`); + expect(drop.followUp?.down ?? '').not.toContain(`"${name}"`); + } + expect(at('add column "legacy"')).toBeGreaterThanOrEqual(0); + expect(`${drop.up}${drop.down}${drop.followUp?.up ?? ''}`).not.toContain('"posts_k"'); + expect(drop.snapshot.tables[0]?.indexes.map((index) => index.name)).toEqual(['posts_k']); + }); + test('declaring a retired column again records the un-retire, or the flag would stick', () => { const first = generateMigration({ entities: [retired], diff --git a/packages/db/src/index-plan.ts b/packages/db/src/index-plan.ts index 625794a6c..edf289a35 100644 --- a/packages/db/src/index-plan.ts +++ b/packages/db/src/index-plan.ts @@ -36,6 +36,7 @@ import { import type { TableDescription } from './introspect'; import { declaredIndexes } from './invariant-ddl'; import { LOCK_HEAVY_MARKER } from './migration-lock-lint'; +import { indexDependsOn } from './retype-dependents'; /** * An existing table's index is built `concurrently` unless the entity says `concurrently: false`: @@ -153,6 +154,7 @@ export function indexPlan( * | already in `context.moved` | a retype dropped it ahead of the ALTER — a second drop is 42704 | * | over a column in `context.rebuilt` | it went with the `drop column` half of `regenerate` — 42704 | * | over a column this migration DROPS | `alter table … drop column` takes it, so a drop beside it says nothing new. The rule `foreignKeyPlan` applies to a constraint on a dropped column | + * | reads a dropped column (predicate, expression, INCLUDE) | the same drop takes it (`indexDependsOn`); deferred to a follow-up, its `down` rebuilt a predicate over a column not there (42703) | * * A doomed TABLE needs no arm: `generate.ts` only reaches a diff for a table an entity still * declares, so `drop table` and this function never meet. @@ -164,11 +166,17 @@ function removeUndeclared( declared: ReadonlySet<string>, ): void { const columns = new Set(entity.columns.map((column) => column.column)); + // `dropColumns`' own reading of "leaving": recorded, neither declared nor retired. + const retired = new Set(entity.retired ?? []); + const leaving = live.columns + .map((column) => column.name) + .filter((column) => !columns.has(column) && !retired.has(column)); for (const recorded of live.indexes) { if (recorded.primary || declared.has(recorded.name)) continue; if (context.moved.has(recorded.name)) continue; if (recorded.columns.some((column) => context.rebuilt.has(column))) continue; if (!recorded.columns.every((column) => columns.has(column))) continue; + if (leaving.some((column) => indexDependsOn(recorded, column))) continue; removeConcurrently(live.name, recorded, context.concurrent); } } diff --git a/packages/db/src/migrate-dev-fix.ts b/packages/db/src/migrate-dev-fix.ts new file mode 100644 index 000000000..b41e90838 --- /dev/null +++ b/packages/db/src/migrate-dev-fix.ts @@ -0,0 +1,30 @@ +// Single responsibility: the `fix:` a migration refusal names on the embedded development database, +// where a deploy's lines cannot run: no image to roll forward to, no `DATABASE_URL` for psql, no git +// history for a migration written a minute ago. Its own module — an environment probe is not a +// refusal — at the cost of one module on `ROLE=migrate`'s pinned graph (`MIGRATE_CEILING`). + +import { tryResolveEnvironment } from '@ultimat3/core'; + +type Env = Readonly<Record<string, string | undefined>>; + +/** + * Development, and no `DATABASE_URL`: the database is PGlite under the checkout's `.x/`, which is + * what `x db reset` rebuilds. The non-throwing read on purpose — this runs while an error is being + * built, and a typo in `ULTIMATE_ENV` must not replace that error; it reads as "not development". + * `test` is not development either: a suite's database is the suite's to rebuild. + */ +export function embeddedDev(env: Env = Bun.env): boolean { + return ( + tryResolveEnvironment({ env }) === 'development' && (env['DATABASE_URL'] ?? '').trim() === '' + ); +} + +/** + * The one command that always ends a ledger this checkout cannot reconcile: rebuild the embedded + * database from the migrations on disk. `x stop` first because `x db reset` refuses beside a + * running `x dev` (it holds the data directory), and it exits 0 when none is running — so the line + * runs as pasted either way. `why` is the caller's: what made the ledger irreconcilable, and what + * to do instead when the rows matter. + */ +export const embeddedResetFix = (why: string): string => + `x stop --json && x db reset # development: rebuilds the embedded database from the migrations on disk, and its rows are lost (x db seed refills them) — ${why}; then x dev`; diff --git a/packages/db/src/migrate-rollback.ts b/packages/db/src/migrate-rollback.ts index 3019b2548..1494a9eab 100644 --- a/packages/db/src/migrate-rollback.ts +++ b/packages/db/src/migrate-rollback.ts @@ -5,7 +5,7 @@ import { renderFixShellArg } from '@ultimat3/core'; import { isDestructiveMigration } from './destructive'; import { DbError } from './errors'; -import { embeddedDev, embeddedResetFix } from './migration-errors'; +import { embeddedDev, embeddedResetFix } from './migrate-dev-fix'; import type { LedgerRow, Migration } from './migration-ledger'; import { pendingMigrations } from './migration-ledger'; diff --git a/packages/db/src/migrate.ts b/packages/db/src/migrate.ts index 297a4e18b..a8c8cdade 100644 --- a/packages/db/src/migrate.ts +++ b/packages/db/src/migrate.ts @@ -13,15 +13,10 @@ import { } from '@ultimat3/core'; import { baseClient, type DbClient, type DbConnection, isReservable } from './client'; import { expectedQueryLoop } from './expected-loop'; +import { embeddedDev, embeddedResetFix } from './migrate-dev-fix'; import { MIGRATION_LOCK_RETRIES } from './migrate-lock-retry'; import { destructiveBit, ledgerAheadOfBuild } from './migrate-rollback'; -import { - embeddedDev, - embeddedResetFix, - migrateConcurrent, - migrationConflict, - rollbackStepsInvalid, -} from './migration-errors'; +import { migrateConcurrent, migrationConflict, rollbackStepsInvalid } from './migration-errors'; import type { LedgerRow, Migration } from './migration-ledger'; import { auditLedger, diff --git a/packages/db/src/migration-errors-dev.test.ts b/packages/db/src/migration-errors-dev.test.ts index f187fcd32..1e5303242 100644 --- a/packages/db/src/migration-errors-dev.test.ts +++ b/packages/db/src/migration-errors-dev.test.ts @@ -6,8 +6,8 @@ import { describe, expect, test } from 'bun:test'; import { recordingClient } from './fake'; import { type LedgerRow, type Migration, migrationChecksum, rollback } from './migrate'; +import { embeddedDev, embeddedResetFix } from './migrate-dev-fix'; import { ledgerAheadOfBuild } from './migrate-rollback'; -import { embeddedDev, embeddedResetFix } from './migration-errors'; import { auditLedger } from './migration-ledger'; const posts: Migration = { diff --git a/packages/db/src/migration-errors.ts b/packages/db/src/migration-errors.ts index 5156dca91..4810bc744 100644 --- a/packages/db/src/migration-errors.ts +++ b/packages/db/src/migration-errors.ts @@ -6,7 +6,7 @@ // `invariant-errors.ts` was: every code below is still declared, titled and registered there, and // `DbError` is still the one class. One direction only — nothing here is imported back. -import { renderFixShellArg, tryResolveEnvironment } from '@ultimat3/core'; +import { renderFixShellArg } from '@ultimat3/core'; import { DESTRUCTIVE_CAUSE, DESTRUCTIVE_MARKER, type DestructiveStatement } from './destructive'; import { DbError } from './errors'; import type { MigrationFork } from './migration-fork'; @@ -269,31 +269,3 @@ export const migrationConcurrentPartitioned = ( meta: { id, sqlState: '0A000' }, sourceError, }); - -// The `fix:` a migration refusal names on the embedded development database, where a deploy's -// lines cannot run: no image to roll forward to, no `DATABASE_URL` for psql, no git history for a -// migration written a minute ago. Here, not a module of its own: `ROLE=migrate`'s graph is pinned. - -type Env = Readonly<Record<string, string | undefined>>; - -/** - * Development, and no `DATABASE_URL`: the database is PGlite under the checkout's `.x/`, which is - * what `x db reset` rebuilds. The non-throwing read on purpose — this runs while an error is being - * built, and a typo in `ULTIMATE_ENV` must not replace that error; it reads as "not development". - * `test` is not development either: a suite's database is the suite's to rebuild. - */ -export function embeddedDev(env: Env = Bun.env): boolean { - return ( - tryResolveEnvironment({ env }) === 'development' && (env['DATABASE_URL'] ?? '').trim() === '' - ); -} - -/** - * The one command that always ends a ledger this checkout cannot reconcile: rebuild the embedded - * database from the migrations on disk. `x stop` first because `x db reset` refuses beside a - * running `x dev` (it holds the data directory), and it exits 0 when none is running — so the line - * runs as pasted either way. `why` is the caller's: what made the ledger irreconcilable, and what - * to do instead when the rows matter. - */ -export const embeddedResetFix = (why: string): string => - `x stop --json && x db reset # development: rebuilds the embedded database from the migrations on disk, and its rows are lost (x db seed refills them) — ${why}; then x dev`; diff --git a/packages/db/src/migration-ledger.ts b/packages/db/src/migration-ledger.ts index 6c847a00d..c2aacaaa8 100644 --- a/packages/db/src/migration-ledger.ts +++ b/packages/db/src/migration-ledger.ts @@ -6,7 +6,8 @@ import { isFixShellSafe } from '@ultimat3/core'; import type { DbClient } from './client'; import type { SchemaDescription } from './introspect'; -import { embeddedDev, embeddedResetFix, migrationConflict } from './migration-errors'; +import { embeddedDev, embeddedResetFix } from './migrate-dev-fix'; +import { migrationConflict } from './migration-errors'; import { raw, sql } from './sql'; import { SQLSTATE, sqlState } from './sqlstate'; diff --git a/packages/db/src/retype-dependents.ts b/packages/db/src/retype-dependents.ts index 25ccc163e..a2ea4ffa2 100644 --- a/packages/db/src/retype-dependents.ts +++ b/packages/db/src/retype-dependents.ts @@ -64,6 +64,23 @@ export function referencesColumn(expression: string, column: string): boolean { return false; } +/** + * Whether `drop column` takes `index` with it: Postgres drops every index that DEPENDS on the + * column — keyed by it, carrying it as INCLUDE payload, or reading it in its predicate or its + * expression key (measured on PGlite: `posts_p on (title) where "legacy" is not null` goes with + * `legacy`). A catalog-read expression key sits in `columns` in parentheses, so it is read too. + */ +export function indexDependsOn(index: IndexDescription, column: string): boolean { + return ( + index.columns.some((key) => + key.startsWith('(') ? referencesColumn(key, column) : key === column, + ) || + (index.include ?? []).includes(column) || + (index.where !== null && referencesColumn(index.where, column)) || + (index.expression !== undefined && referencesColumn(index.expression, column)) + ); +} + /** The recorded objects a retype of `column` cannot leave in place. */ export interface RetypeDependents { /** diff --git a/packages/entity/package.json b/packages/entity/package.json index 6e41c1948..fb0f832bd 100644 --- a/packages/entity/package.json +++ b/packages/entity/package.json @@ -26,6 +26,7 @@ "exports": { ".": "./src/index.ts", "./adapter": "./src/adapter.ts", + "./internal/memory-tx": "./src/memory-tx-entry.ts", "./record": "./src/record.ts" }, "files": [ diff --git a/packages/entity/src/batch-read.test.ts b/packages/entity/src/batch-read.test.ts new file mode 100644 index 000000000..f74e48d04 --- /dev/null +++ b/packages/entity/src/batch-read.test.ts @@ -0,0 +1,73 @@ +// `readByIds`' bisect, driven through a scripted client: a value the server refuses fails only the +// id that carried it, and a half that fails for a reason of its own answers THAT reason — only a +// transaction the first refusal aborted (`25P02`) inherits the first refusal. + +import { afterAll, describe, expect, test } from 'bun:test'; +import type { DbClient, SqlFragment } from '@ultimat3/db'; +import { type PointRead, readByIds } from './batch-read'; +import { text } from './columns'; +import { bigint } from './columns-data'; +import { entity } from './entity'; +import { clearRegistry } from './registry'; + +afterAll(() => { + clearRegistry(); +}); + +const rows = entity('batch_read_bisect_rows', { + columns: { id: bigint().primaryKey(), label: text({ max: 8 }) }, +}); + +const serverError = (code: string) => ({ severity: 'ERROR', code, message: `refused ${code}` }); + +const BAD = 'abc'; +const IDS: readonly string[] = ['1', '2', '3', BAD]; +const isId = (value: unknown): value is string => typeof value === 'string' && IDS.includes(value); + +/** A client whose answer to each statement is `answer(ids)`: rows, or a thrown server error. */ +const scripted = (answer: (ids: readonly unknown[]) => unknown): DbClient => { + const query = async <T>(fragment: SqlFragment): Promise<readonly T[]> => { + const out = answer(fragment.values.flat().filter(isId)); + if (Array.isArray(out)) return out; + throw out; + }; + return { + query, + one: async () => null, + execute: async () => 0, + }; +}; + +const read = (client: DbClient): PointRead<typeof rows.$row> => ({ + entity: rows, + client, + scoped: { entity: rows.$name, where: [], orderBy: [], limit: 1 }, + shape: { includeDeleted: false }, + key: { property: 'id', column: 'id', kind: 'bigint' }, +}); + +describe('readByIds bisect', () => { + test('a half that fails for a connection reason answers that reason, not the first refusal', async () => { + const failover = serverError('57P01'); + const client = scripted((ids) => { + if (ids.includes(BAD)) return serverError('22P02'); + if (ids.includes('1')) return failover; + return ids.map((id) => ({ id, label: 'x' })); + }); + const answers = await readByIds(read(client), IDS); + expect(answers.get('1')).toEqual({ error: failover }); + expect(answers.get('2')).toEqual({ error: failover }); + expect(answers.get(BAD)).toEqual({ error: serverError('22P02') }); + }); + + test('a half the first refusal aborted (25P02) is answered with that first refusal', async () => { + const first = serverError('22P02'); + let sent = 0; + const client = scripted(() => { + sent += 1; + return sent === 1 ? first : serverError('25P02'); + }); + const answers = await readByIds(read(client), IDS); + for (const id of IDS) expect(answers.get(id)).toEqual({ error: first }); + }); +}); diff --git a/packages/entity/src/batch-read.ts b/packages/entity/src/batch-read.ts index 25bd8a1b2..cd744fa6f 100644 --- a/packages/entity/src/batch-read.ts +++ b/packages/entity/src/batch-read.ts @@ -146,6 +146,9 @@ const readStatement = async <Row>( return answers; }; +/** `in_failed_transaction`: a statement sent after the first refusal aborted the transaction. */ +const IN_FAILED_TRANSACTION = '25P02'; + /** SQLSTATE class 22, data exception: the server refused a VALUE, not the statement's shape. */ const isDataError = (error: unknown): boolean => sqlState(error)?.startsWith('22') === true; @@ -157,9 +160,9 @@ const isDataError = (error: unknown): boolean => sqlState(error)?.startsWith('22 * stands alone: about `2k·log2(n)` statements for `k` bad ids, never one per id. * * Anything else — a dropped connection, a timeout, a stale schema — is the statement's own failure - * and is rethrown for every caller, as before. So is a retry that fails for a reason of its own - * (a transaction the first refusal aborted answers `25P02`): those ids get the FIRST refusal, the - * one the unsplit statement gave them. + * and is rethrown for every caller, as before; a half that fails that way answers its ids with its + * own failure. Only a half sent into a transaction the first refusal aborted (`25P02`) gets the + * FIRST refusal, the one the unsplit statement gave them. */ export const readByIds = async <Row>( read: PointRead<Row>, @@ -191,7 +194,9 @@ const isolate = async <Row>( await isolate(read, half, error, answers); continue; } - const own = isDataError(error) ? error : refusal; + // Only a transaction the first refusal ABORTED inherits it; a half's own failure (a pool + // timeout, a failover's 57P01) is that half's answer, never "invalid input syntax". + const own = sqlState(error) === IN_FAILED_TRANSACTION ? refusal : error; for (const id of half) answers.set(keyOf(read.key.kind, id), { error: own }); } } diff --git a/packages/entity/src/index.ts b/packages/entity/src/index.ts index c2863bed5..1a449c8db 100644 --- a/packages/entity/src/index.ts +++ b/packages/entity/src/index.ts @@ -87,7 +87,7 @@ export { MAX_LOCK_KEYS } from './lock-key'; export type { CountByOptions, Measure, MeasureFn, MeasureMap } from './measures'; export { MAX_MEASURES } from './measures'; // Whether a memory transaction has ended: `@ultimat3/action`'s settle scope asks it, never a probe. -export { memoryJournal, memoryTxOpen } from './memory-journal'; +export { memoryJournal } from './memory-journal'; // How Postgres compares two values of one column, decided by the column's declared KIND. Exported // because `@ultimat3/query`'s matcher and in-memory source ask the same question — and a second // answer there is how a live window and the database returned one read in two orders. diff --git a/packages/entity/src/memory-journal.test.ts b/packages/entity/src/memory-journal.test.ts index d910b2aeb..b31920e20 100644 --- a/packages/entity/src/memory-journal.test.ts +++ b/packages/entity/src/memory-journal.test.ts @@ -1,10 +1,13 @@ // Single responsibility: a memory transaction is ambient — a write inside it that names no `tx` is // undone when it rolls back, whichever door it came through — and a commit keeps every write. import { afterAll, describe, expect, test } from 'bun:test'; +import * as adapter from './adapter'; import { text } from './columns'; import { entity } from './entity'; -import { memoryJournal, memoryTxOpen } from './index'; +import * as barrel from './index'; +import { memoryJournal } from './index'; import { memoryRepo, memoryTransactor } from './memory-repo'; +import { memoryTxOpen } from './memory-tx-entry'; import { clearRegistry } from './registry'; import type { Tx } from './repo'; @@ -135,7 +138,16 @@ describe('a lock taken with no tx inside a memory transaction', () => { }); }); -describe('memoryTxOpen, through the package entry', () => { +describe('memoryTxOpen, through its internal leaf entry', () => { + test('is on `/internal/memory-tx` alone: never the app barrel, never the driver kit', async () => { + expect(Object.keys(barrel)).not.toContain('memoryTxOpen'); + expect(Object.keys(adapter)).not.toContain('memoryTxOpen'); + const manifest: unknown = await Bun.file(new URL('../package.json', import.meta.url)).json(); + expect(manifest).toMatchObject({ + exports: { './internal/memory-tx': './src/memory-tx-entry.ts' }, + }); + }); + test('is true while the root is open and false once it commits or rolls back', async () => { let committed: Tx | undefined; let nested: Tx | undefined; diff --git a/packages/entity/src/memory-journal.ts b/packages/entity/src/memory-journal.ts index 9f26707e7..4f91ba085 100644 --- a/packages/entity/src/memory-journal.ts +++ b/packages/entity/src/memory-journal.ts @@ -47,7 +47,7 @@ export const enrolMemoryScope = (scope: Tx, tx: Tx | undefined): void => { /** * Whether a memory `tx` may still take a write — its root has neither committed nor rolled back. A * `Tx` the memory transactor never handed out has no root here, so it answers `true`, the same pass - * `refuseIfMemoryTxClosed` gives it. + * `refuseIfMemoryTxClosed` gives it. Off the barrel: `@ultimat3/entity/internal/memory-tx`. */ export const memoryTxOpen = (tx: Tx): boolean => (scopes.get(tx)?.outcome.value ?? 'open') === 'open'; diff --git a/packages/entity/src/memory-tx-entry.ts b/packages/entity/src/memory-tx-entry.ts new file mode 100644 index 000000000..dc8d7019d --- /dev/null +++ b/packages/entity/src/memory-tx-entry.ts @@ -0,0 +1,5 @@ +// `@ultimat3/entity/internal/memory-tx` — whether a memory transaction's root is still open, for +// `@ultimat3/action`'s settle scope. INTERNAL and a leaf on purpose: the barrel is an app's, and +// `/adapter` (the driver kit) put ten modules into every role's serve graph; this costs one. + +export { memoryTxOpen } from './memory-journal'; diff --git a/packages/entity/src/predicate-operand.test.ts b/packages/entity/src/predicate-operand.test.ts index aab638c9d..463e80890 100644 --- a/packages/entity/src/predicate-operand.test.ts +++ b/packages/entity/src/predicate-operand.test.ts @@ -219,6 +219,17 @@ describe('uuid(): an operand that is no uuid equals no row, in both drivers', () expect(await both({ column: 'ref', op: 'in', value: ['nope', null] })).toEqual([[1], [1]]); }); + // Memory ordered the TEXT; Postgres refused the parameter (`22P02`). A range has no "no row" to + // agree on — every row is above or below SOMETHING — so both drivers refuse it. + test.each(['gt', 'gte', 'lt', 'lte'] as const)( + 'a range operator %s against text that is no uuid is refused by both drivers', + async (op) => { + expect(await both({ column: 'id', op, value: 'nope' })).toEqual(REFUSED); + expect(await both({ column: 'ref', op, value: 5 })).toEqual(REFUSED); + expect(await both({ column: 'id', op, value: idAt(1) })).not.toEqual(REFUSED); + }, + ); + test('a malformed id is a row that is not there: null to findById, X_NOT_FOUND to a write', async () => { for (const repo of [memory, postgres]) { expect(await repo.findById('nope')).toBeNull(); diff --git a/packages/entity/src/predicate-operand.ts b/packages/entity/src/predicate-operand.ts index 6df8f5af9..27b06eb18 100644 --- a/packages/entity/src/predicate-operand.ts +++ b/packages/entity/src/predicate-operand.ts @@ -215,6 +215,8 @@ const inList = <Row>( ); }; +const RANGE = new Set(['gt', 'gte', 'lt', 'lte']); + /** * The predicate with its operand in the one form both drivers read, or a refusal. Every operator * outside the comparing set passes through untouched — containment, NULL tests and search have @@ -242,5 +244,15 @@ export const operandFor = <Row>(entity: EntityCore<Row>, predicate: Predicate): if (predicate.op === 'eq' && equalsNoValue(kind, value)) { return { ...predicate, op: 'in', value: [] }; } + // A range has no "no row" answer to agree on: memory ordered the text, Postgres refused the + // parameter (`22P02`). Refused in both, as a fraction against an integer is. + if (RANGE.has(predicate.op) && equalsNoValue(kind, value)) { + throw refused( + entity, + predicate, + `expected a uuid for a uuid column, ${got(value)}`, + `if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)) return [] // check the operand before .andWhere(${renderFixLiteral(predicate.column, "'<column>'")}, '${predicate.op}', value): a uuid column orders uuids only`, + ); + } return value === predicate.value ? predicate : { ...predicate, value }; }; diff --git a/packages/http/README.md b/packages/http/README.md index cce8b004e..7f22a1501 100644 --- a/packages/http/README.md +++ b/packages/http/README.md @@ -72,6 +72,14 @@ core's constants (`idempotency-key`, `x-request-timeout-ms`, `traceparent`; `x-u `x-ultimate-dates`, `x-ultimate-replayed`, `ratelimit-*`, `deprecation`, `sunset`, `link`), so listing an origin is the whole declaration. A list of the app's own replaces the default whole. +`x-ultimate-dates` is capped at `WIRE_DATES_MAX_BYTES` (4,096 bytes), `As of 2026-11-19`. +`cappedWireDates(data, ctx?)` is the one writer — an action's and a query's 200, and a streamed +frame's `dates:` line. An answer whose instants need one path each (a `string | Date` column, a +`[label, instant]` tuple) past the cap is sent with **no** header: a proxy refuses a response whose +headers outgrow its buffer (nginx's default `proxy_buffer_size` is one page). The client then reads +those instants as the ISO strings the body holds, and the route's name is logged once per process +at `warn` (`http.wire_dates_dropped`, with `paths`, `bytes`, `maxBytes`). + `AppHttpConfig` is `Omit<HttpConfigInput, BootOwnedHttpKey>` — `port`, `hostname`, `dev`, `buildId`, `signInPath`, `trustProxy`, `trustedProxyHops` and `rateLimit.scope` are the boot's, and writing one here is a **type error** rather than a value silently overwritten at the next boot. @@ -129,7 +137,7 @@ What the lifecycle refuses on the caller's behalf, `As of 2026-08`: | a handler silent for longer than Bun's 10 s idle default | ANSWERED: `start()` hands `Bun.serve` an `idleTimeout` of `socketIdleTimeoutSeconds(requestTimeoutMs)` — `ceil(ms / 1000) + 2` s, `0` (off) for no deadline or one past Bun's 255 s ceiling — so the socket outlives the deadline. `As of 27.16.0`: Bun's default cut every such request at ~10–12 s, a 502 behind a proxy, whatever `requestTimeoutMs` said | | a budget above `2_147_483_647` ms | no timer holds it: `requestTimeoutMs` past it is `X_CONFIG_INVALID`, and an `x-request-timeout-ms` past it is ignored — it used to arm a ~1 ms timer | | the caller going away mid-request | `ctx.signal` aborts on the inbound `Request.signal` too, so a closed tab unwinds cooperative work instead of holding its pool slot for the rest of the budget. Both halves are one signal — the caller's abort is forwarded into the deadline's controller, first abort wins with its own reason — and `requestTimeoutMs: 0` still delivers the caller's . A handler that rejects with that hang-up (the signal's own uncoded reason, or an `AbortError` raised for it) is answered `X_ABORTED` (499): logged at `info`, handed to `hooks.onError` as the coded error, never reported to the error monitor and never a 5xx in the request metric. Any other throw after a hang-up is still a 500 | -| a fault after the response left (a streamed body's producer) | `reportLateFault(error, ctx?)` records it exactly as the `error-map` stage would — the monitor for a 5xx, `hooks.onError`, the one log line — once per request; `false` when no pipeline request is behind the context. `isCallerAbort(error, signal)` is the hang-up test it is paired with. `@ultimat3/action`'s streamed answer is the caller | +| a fault after the response left (a streamed body's producer) | `reportLateFault(error, ctx?)` records it exactly as the `error-map` stage would — the monitor for a 5xx, `hooks.onError`, the one log line — once per request; `false`, and nothing recorded, when no pipeline request is behind the context. A caller's hang-up (the context's signal aborted with an uncoded reason, the throw that reason or an `AbortError`) is not a fault: it records nothing and leaves the one report unspent. `@ultimat3/action`'s streamed answer is the caller | | an unclassified 500's `code` outside dev | `X_INTERNAL` in `code`, `type` and the error page unless the throwable's code has the framework's shape (`X_…`): a driver's SQLSTATE or `ENOENT` is the server's business, like its message (`callerCode`) | | a request while the process is draining | SERVED, with `connection: close` so the client's next request lands on another pod, `As of 2026-09-23` — refusing it failed 598 of 7,690 requests across one helm upgrade on kind, every one on a kept-alive connection inside the readiness grace. Only a STOPPED process (resources closed) answers `X_DRAINING` (503) + `retry-after` | | SIGTERM | `/readyz` answers 503 at once, the listener stays open for `drain.readinessGraceMs` (core; 5000 ms outside development/test, 0 inside), then closes and the drain runs. Pass `httpServer({ …, drain: appConfig.drain })` so `app.config.ts`'s value is the one applied; omitted, core's default holds and a `configureLifecycle({ readinessGraceMs })` stands | @@ -148,6 +156,7 @@ What the lifecycle refuses on the caller's behalf, `As of 2026-08`: | a 5xx whose cause is withheld | its `fix` is the error's `callerFix`, else `x errors explain <CODE> --json` — never the developer's `fix:`, which is written from the same statement, row or path the cause was | | `buildId: null` | skew detection off, whatever `BUILD_ID` says; `hostname` never defaults from `HOSTNAME` (the container id under Docker) | | an `x-forwarded-client-cert` value in quotes | unescaped ONCE, after the pairs are split — `Subject="O=Acme; Inc,CN=svc-one"` is that whole subject, not `O=Acme` | +| an `x-forwarded-client-cert` list | read from the RIGHT, `As of 2026-11-19`: only the elements the trusted hops appended are parsed, so no quote or backslash the client wrote before them can move the hop index onto its own `URI=`. A trusted element must be well formed — a quoted value is `="…"` whole, `\"` inside it — or `ctx.peer` is `null`: a raw `"` in an unquoted value (`URI=spiffe://a/b"c`) is no peer | | a request past `maxInflight` (1000) | `X_OVERLOADED` (503) + `retry-after`, shed in the `admit` stage before any work | | `shedLagMs: 250` and an event loop whose lag p99 (two seconds, sampled every 20 ms) is past it | `X_OVERLOADED` (503) + `retry-after: 1` from `admit`: the CPU-bound overload `maxInflight` cannot see. **Off by default in 31.x** (`0`): no sampler runs, nothing is shed on lag, `As of 2026-11` | | a request slower than `slowRequestMs` (1000; `0` off) | one `http.request.slow` line at `warn` (`SLOW_REQUEST_MESSAGE`): `http.request.method`, `http.route` (the pattern), `http.response.status_code`, `durationMs`, `gateMs` (the stages before the handler), `handlerMs`, `dbStatements`, `dbMs`, `renderMs`, `cacheHits`, `cacheMisses`, and the request and trace ids. No per-request access log: the request metric and the trace are that record | diff --git a/packages/http/src/context.ts b/packages/http/src/context.ts index fd97210e9..84e011d47 100644 --- a/packages/http/src/context.ts +++ b/packages/http/src/context.ts @@ -338,18 +338,29 @@ export const assertInRequest = (member: string, ctx = ambientContext()): Request return ctx; }; +/** + * The HTTP request behind `from` (the ambient context by default): the context itself, or the + * nearest one it was derived inside (`parentContext`). `undefined` for a job, a task, the build's + * `llms.txt` pass. For a reader of what the PIPELINE set — the matched route — which a derived + * child does not carry. Not on the barrel: app code reads a header or a cookie, never the proof. + */ +export const requestBehind = ( + from: Ctx | undefined = tryUseContext(), +): RequestContext | undefined => { + for (let ctx = from; ctx !== undefined; ctx = parentContext(ctx)) { + // The inverse of `asCtx`, proven by the one field only the pipeline sets (`assertInRequest`). + if (Reflect.get(ctx, 'requestHeaders') !== undefined) return ctx as unknown as RequestContext; + } + return undefined; +}; + /** * Whether an HTTP request is behind the ambient context: the context itself, or any it was derived * inside (`parentContext`). A child does not carry the request's headers, so a reader still * refuses there (`X_NO_REQUEST`); this only tells "no request at all" (a job, a task, the build's * `llms.txt` pass) from "a request this scope cannot read", for a reader whose answer is `null`. */ -export const hasRequest = (): boolean => { - for (let ctx = tryUseContext(); ctx !== undefined; ctx = parentContext(ctx)) { - if (Reflect.get(ctx, 'requestHeaders') !== undefined) return true; - } - return false; -}; +export const hasRequest = (): boolean => requestBehind() !== undefined; /** * Read the ambient request context. Throws outside a request via core's ALS — and, since a job, a diff --git a/packages/http/src/fault-report.test.ts b/packages/http/src/fault-report.test.ts index c976006eb..3e8d1cbc7 100644 --- a/packages/http/src/fault-report.test.ts +++ b/packages/http/src/fault-report.test.ts @@ -84,6 +84,40 @@ describe('reportLateFault', () => { expect(reporter.events).toEqual([]); }); + // The stream's producer unwinds on the abort when its reader leaves: nobody is there to answer + // and nothing failed. Asked here, so a caller of this function never judges a hang-up itself. + test("a caller's hang-up is nobody's incident: nothing recorded, the one report unspent", () => { + const caller = new AbortController(); + const ctx = request(caller.signal); + const seen: unknown[] = []; + bindLateFault(ctx, { onError: (error) => void seen.push(error) }); + caller.abort(new DOMException('The connection was closed.', 'AbortError')); + + expect(reportLateFault(caller.signal.reason, asCtx(ctx))).toBe(true); + expect(seen).toEqual([]); + expect(reporter.events).toEqual([]); + + // A defect that merely happened after the hang-up is still a defect, and still reported. + const defect = fault(); + expect(reportLateFault(defect, asCtx(ctx))).toBe(true); + expect(seen).toEqual([defect]); + expect(reporter.events).toHaveLength(1); + }); + + test('a hang-up on a signal a derived context added is read from that context', () => { + const ctx = request(); + const seen: unknown[] = []; + bindLateFault(ctx, { onError: (error) => void seen.push(error) }); + const left = new AbortController(); + runWithContext(asCtx(ctx), () => + withChildContext({ signal: left.signal }, () => { + left.abort(); + expect(reportLateFault(left.signal.reason)).toBe(true); + }), + ); + expect(seen).toEqual([]); + }); + test('a sink that throws is contained: nothing is above a late fault', () => { const ctx = request(); bindLateFault(ctx, { diff --git a/packages/http/src/fault-report.ts b/packages/http/src/fault-report.ts index 07ecda1ce..6c684c638 100644 --- a/packages/http/src/fault-report.ts +++ b/packages/http/src/fault-report.ts @@ -109,12 +109,17 @@ export const bindLateFault = (ctx: RequestContext, hooks: ServerHooks): void => * Records a fault that surfaced after the response was handed over — a streamed body's producer — * exactly as the `error-map` stage would have: monitor (5xx), `hooks.onError`, the log line. ONCE * per request; a second call records nothing. `false` only when no pipeline request is behind - * `ctx`, and the caller then owns the report. Never throws: nothing is above it. + * `ctx`: nothing is recorded, since a producer driven outside the pipeline is a test. + * + * The caller's hang-up (`isCallerAbort` on `ctx.signal`, which carries every signal a context it + * was derived inside brought) is not a fault: nobody is there to answer and nothing failed, so it + * records nothing and leaves the request's one report unspent. Never throws: nothing is above it. */ export const reportLateFault = ( error: unknown, ctx: Ctx | undefined = tryUseContext(), ): boolean => { + if (ctx !== undefined && isCallerAbort(error, ctx.signal)) return true; for (let scope = ctx; scope !== undefined; scope = parentContext(scope)) { const record = late.get(scope); if (record === undefined) continue; diff --git a/packages/http/src/index.ts b/packages/http/src/index.ts index f2d773db2..93bf65e0b 100644 --- a/packages/http/src/index.ts +++ b/packages/http/src/index.ts @@ -81,7 +81,7 @@ export { unauthenticated, } from './errors'; /** A fault AFTER the response left (a streamed body's producer), recorded as `error-map` would. */ -export { isCallerAbort, reportLateFault } from './fault-report'; +export { reportLateFault } from './fault-report'; export type { ForwardedInput, ForwardedSplit } from './forwarded'; export { clientAddress, forwardedElement } from './forwarded'; export type { Authenticator, AuthenticatorOptions, AuthzDecision, ServerHooks } from './hooks'; @@ -226,3 +226,5 @@ export type { VerifiedWebhook, WebhookVerifyOptions } from './webhook-verify'; export { DEFAULT_WEBHOOK_BODY_LIMIT, verifyWebhookSignature } from './webhook-verify'; export type { JoinedWebSocketMounts } from './websocket-mounts'; export { joinWebSocketMounts } from './websocket-mounts'; +/** An answer's `x-ultimate-dates` value, or none past the size a proxy takes in a header. */ +export { cappedWireDates, WIRE_DATES_MAX_BYTES } from './wire-dates-cap'; diff --git a/packages/http/src/peer-identity.test.ts b/packages/http/src/peer-identity.test.ts index a27ad3c0b..892c4201c 100644 --- a/packages/http/src/peer-identity.test.ts +++ b/packages/http/src/peer-identity.test.ts @@ -25,18 +25,18 @@ const read = (header: string | undefined, hops: number | undefined, certHeader = describe('peerIdentity', () => { // The proxy APPENDS to what the client sent, so the client writes the text before the first - // trusted comma. Nothing it writes there may move the hop index onto its own element. + // trusted comma. Nothing it writes there may move the hop index onto its own element — and + // nothing it writes there may cost the proxy's element its reading either. test('a client prefix ending in an open quote or a backslash never names the peer', () => { const plain = 'By=spiffe://cluster.local/gw;Hash=abc;URI=spiffe://cluster.local/ns/real'; const forged = 'URI=spiffe://cluster.local/ns/admin'; for (const hops of [1, 2]) { const inner = hops === 1 ? '' : `,${plain}`; for (const proxied of [plain, SPIFFE]) { - expect(read(`${forged};X=",${proxied}${inner}`, hops)).toBeNull(); - expect(read(`${forged};X="\\,${proxied}${inner}`, hops)).toBeNull(); - const escaped = read(`${forged};X=\\,${proxied}${inner}`, hops); - expect(escaped?.id).not.toBe('spiffe://cluster.local/ns/admin'); - expect(escaped?.id).toBe(read(proxied, 1)?.id); + const honest = read(proxied, 1); + for (const tail of [';X="', ';X="\\', ';X=\\', '"', '\\"', ';X="a\\\\']) { + expect(read(`${forged}${tail},${proxied}${inner}`, hops)).toEqual(honest); + } } } }); @@ -160,3 +160,140 @@ describe('ctx.peer through the pipeline', () => { ).toBe('spiffe://cluster.local/ns/default/sa/checkout'); }); }); + +// The sweep-2 parser read left to right, so the CLIENT's text decided the quote state the proxy's +// element was read in: one odd quote and the proxy's own `\"` closed a quote instead of escaping +// one, the trusted comma was swallowed and the client's `URI=` named the peer. Only the suffix the +// trusted hops wrote is read now, from the right. +describe('only the proxy-written suffix is read', () => { + const ADMIN = 'spiffe://mesh/admin'; + const REAL = 'spiffe://mesh/real'; + const INNER = 'By=spiffe://mesh/gw;Hash=ff;URI=spiffe://mesh/edge'; + const ESCAPED = `By=spiffe://mesh/gw;Subject="CN=a\\"b";URI=${REAL}`; + /** `client` + what `hops` trusted proxies appended; the outermost one wrote `element`. */ + const chain = (client: string, element: string, hops: number, joint = ','): string => + [client, element, ...(hops === 2 ? [INNER] : [])].join(joint); + + const PREFIXES: readonly (readonly [name: string, client: string])[] = [ + ['an open quote', `URI=${ADMIN};X="`], + ['an open quote after a comma of its own', `URI=${ADMIN},X="`], + ['a quote that closes', `URI=${ADMIN};X="a"`], + ['three quotes', `"""URI=${ADMIN}`], + ['an escaped quote', `URI=${ADMIN};X=\\"`], + ['a trailing backslash', `URI=${ADMIN};X=\\`], + ['an open quote and a trailing backslash', `URI=${ADMIN};X="\\`], + ['an even run of backslashes', `URI=${ADMIN};X="a\\\\`], + ['empty elements', `URI=${ADMIN},, ,`], + ['whitespace', ` URI=${ADMIN} ;X=" `], + ['a megabyte of open quotes', `URI=${ADMIN};X=${'"'.repeat(1_000_001)}`], + ]; + const ELEMENTS: readonly (readonly [name: string, element: string, subject: string | null])[] = [ + ['an unquoted element', `By=spiffe://mesh/gw;Hash=ab;URI=${REAL}`, null], + ['an escaped quote in Subject', ESCAPED, 'CN=a"b'], + [ + 'two escaped quotes and a comma', + `Subject="CN=\\"a\\",O=x, Inc";URI=${REAL}`, + 'CN="a",O=x, Inc', + ], + ['an escaped backslash before the closing quote', `Subject="CN=a\\\\";URI=${REAL}`, 'CN=a\\'], + ['a quoted value last', `URI=${REAL};Subject="CN=a\\"b"`, 'CN=a"b'], + ]; + + for (const hops of [1, 2]) { + for (const [prefix, client] of PREFIXES) { + for (const [shape, element, subject] of ELEMENTS) { + test(`hops ${hops}: ${prefix} before ${shape} resolves the proxy's element`, () => { + for (const joint of [',', ', ', ' ,\t']) { + const peer = read(chain(client, element, hops, joint), hops); + expect(peer?.id).toBe(REAL); + expect(peer?.uriSans).toEqual([REAL]); + expect(peer?.subject).toBe(subject); + } + }); + } + } + } + + test('honest input reads exactly as it did: no client text, hops 1 and 2', () => { + for (const [, element, subject] of ELEMENTS) { + for (const hops of [1, 2]) { + const peer = read(hops === 1 ? element : `${element},${INNER}`, hops); + expect(peer?.id).toBe(REAL); + expect(peer?.subject).toBe(subject); + } + } + }); + + // A raw `"` in a value the proxy did not quote leaves no reading of the element that the + // client's text cannot change, so there is none. + test('a raw quote inside an unquoted URI SAN is no peer, whatever the client wrote', () => { + const raw = 'By=spiffe://mesh/gw;URI=spiffe://mesh/re"al'; + for (const hops of [1, 2]) { + expect(read(chain('', raw, hops).replace(/^,/, ''), hops)).toBeNull(); + for (const [, client] of PREFIXES) expect(read(chain(client, raw, hops), hops)).toBeNull(); + } + // Closing the quote it opens does not make it an element either: a value is quoted whole. + expect(read(`URI=${ADMIN};X=",By=gw;URI=spiffe://mesh/re"al;DNS=a.test`, 1)).toBeNull(); + expect(read('By=gw;URI=spiffe://mesh/real"', 1)).toBeNull(); + }); + + test('an element that is not well formed is no peer', () => { + for (const element of [ + `URI=${REAL};Subject="CN=a`, // never closed + `URI=${REAL};Subject=CN=a"`, // never opened + `Subject="CN=a"x;URI=${REAL}`, // text after the closing quote + `Subject=x"CN=a";URI=${REAL}`, // text before the opening quote + `Subject="CN=a\\";URI=${REAL}`, // the closing quote is escaped + `Subject=\\"CN=a";URI=${REAL}`, + ]) { + expect(read(element, 1)).toBeNull(); + expect(read(`URI=${ADMIN},${element}`, 1)).toBeNull(); + expect(read(`URI=${ADMIN},${element},${INNER}`, 2)).toBeNull(); + } + }); + + test('empty elements and whitespace never count as a hop', () => { + expect(read(`URI=${ADMIN}, ,${ESCAPED},,`, 1)?.id).toBe(REAL); + expect(read(`URI=${ADMIN},${ESCAPED}, ,${INNER} , `, 2)?.id).toBe(REAL); + expect(read(' , ,, ', 1)).toBeNull(); + expect(read(`${INNER},,`, 2)).toBeNull(); + }); + + // Two `x-forwarded-client-cert` lines reach `Headers` as one value joined by `, `. + test('two header lines are one list, read from the right', () => { + const headers = new Headers(); + headers.append('x-forwarded-client-cert', `URI=${ADMIN};X="`); + headers.append('x-forwarded-client-cert', ESCAPED); + const peer = peerIdentity({ + headers, + config: defineHttpConfig({ + rateLimit: { scope: 'process' }, + trustClientCertHeader: true, + trustProxy: true, + trustedProxyHops: 1, + }), + socketAddress: '10.42.0.7', + urlProtocol: 'http:', + }); + expect(peer?.id).toBe(REAL); + expect(peer?.subject).toBe('CN=a"b'); + }); + + // Each shape is one the old parser, or a naive right-to-left one, walks more than once. + test('a megabyte of anything is read in linear time', () => { + const size = 1_000_000; + const shapes = [ + `${'"'.repeat(size)},${ESCAPED}`, + `${'\\'.repeat(size)},${ESCAPED}`, + `Subject="${'\\"'.repeat(size / 2)}";URI=${REAL}`, + `Subject="${'\\'.repeat(size)}";URI=${REAL}`, + `URI=${REAL}${'\\'.repeat(size)}"`, + `${',"'.repeat(size / 2)}`, + `${'a,'.repeat(size / 2)}${ESCAPED}`, + ]; + const started = performance.now(); + const read1 = shapes.map((header) => read(header, 1)?.id ?? null); + expect(performance.now() - started).toBeLessThan(2_000); + expect(read1).toEqual([REAL, REAL, REAL, REAL, null, null, REAL]); + }); +}); diff --git a/packages/http/src/peer-identity.ts b/packages/http/src/peer-identity.ts index 983895371..a87ca17ac 100644 --- a/packages/http/src/peer-identity.ts +++ b/packages/http/src/peer-identity.ts @@ -3,7 +3,12 @@ // Envoy's `x-forwarded-client-cert`, at the hop index `x-forwarded-for` is read at. Untrusted, // this header is worse than nothing — it authenticates — so an untrusted read answers `null`. -import { FORWARDED_CLIENT_CERT, type ForwardedInput, forwardedElement } from './forwarded'; +import { + FORWARDED_CLIENT_CERT, + type ForwardedInput, + type ForwardedSplit, + forwardedElement, +} from './forwarded'; /** * The peer's certificate facts, declared structurally rather than imported: `@ultimat3/auth` owns @@ -29,15 +34,74 @@ export interface PeerIdentity { readonly by: string | null; } +/** True when the `"` at `at` is escaped: an odd run of backslashes sits directly before it. */ +const escapedQuote = (value: string, at: number): boolean => { + let run = at - 1; + while (run >= 0 && value[run] === '\\') run -= 1; + return (at - 1 - run) % 2 === 1; +}; + +/** Nothing but whitespace from `from` up to the pair's end: a `;`, or the element's own end. */ +const endsPair = (value: string, from: number, end: number): boolean => { + for (let at = from; at < end; at += 1) { + const char = value[at]; + if (char === ';') return true; + if (char !== ' ' && char !== '\t') return false; + } + return true; +}; + /** - * Splits on a separator outside double quotes, keeping the quotes and escapes EXACTLY as written. - * Raw on purpose: the element split and the pair split both run over this text, and an element - * split that also stripped quotes left `pairsOf` splitting `O=Acme; Inc` a second time, unquoted. - * Unescaping happens once, per value, in `unquote`. + * The last `hops` elements of the list — the ones the trusted proxies appended — and nothing + * else. Read from the RIGHT, because the client writes everything before them: a left-to-right + * reader carries the client's quote state into the proxy's text, so one odd `"` turned the + * proxy's own `\"` into a closing quote, swallowed the trusted comma and handed the hop index to + * the client's `URI=`. From the right, where an element starts depends only on what is in it. * - * The client writes the text before the first trusted comma, so nothing there may swallow it: a - * backslash escapes only INSIDE quotes (outside, `\,` hid the separator), and a quote still open - * at the end means the client's text ran into the proxy's — no element is trustworthy, so none. + * An element is isolated only when it is well formed, since anything else can be re-read by what + * precedes it: a quoted value is `="…"` whole — the opening quote directly after `=`, the closing + * one ending its pair — and a `"` anywhere else is no element. That, or a quote still open at the + * start of the header, answers `[]`: no element is trustworthy, so `peerIdentity` is `null`. + * Empty elements are not hops, as in every other forwarded list. + */ +const trustedSuffix = + (hops: number): ForwardedSplit => + (value, separator) => { + const found: string[] = []; + let end = value.length; + let quoted = false; + const take = (from: number): void => { + const element = value.slice(from, end).trim(); + if (element.length > 0) found.push(element); + end = from - 1; + }; + for (let at = value.length - 1; at >= 0 && found.length < hops; at -= 1) { + const char = value[at]; + if (char === '"') { + const escaped = escapedQuote(value, at); + if (quoted) { + if (escaped) continue; + if (value[at - 1] !== '=') return []; + quoted = false; + } else { + if (escaped || !endsPair(value, at + 1, end)) return []; + quoted = true; + } + } else if (char === separator && !quoted) { + take(at + 1); + } + } + if (quoted) return []; + if (found.length < hops) take(0); + return found.reverse(); + }; + +/** + * Splits ONE isolated element on a separator outside double quotes, keeping the quotes and escapes + * EXACTLY as written. Raw on purpose: an element split that also stripped quotes left `pairsOf` + * splitting `O=Acme; Inc` a second time, unquoted. Unescaping happens once, per value, in + * `unquote`. Left to right is safe here and only here: every character is the proxy's, and + * `trustedSuffix` has already refused a quote this reading would pair differently. */ const splitRaw = (value: string, separator: string): readonly string[] => { const out: string[] = []; @@ -99,7 +163,7 @@ export const peerIdentity = (input: ForwardedInput): PeerIdentity | null => { const element = forwardedElement( input.headers.get(FORWARDED_CLIENT_CERT), input.config.trustedProxyHops, - splitRaw, + trustedSuffix(input.config.trustedProxyHops), ); if (element === undefined) return null; const pairs = pairsOf(element); diff --git a/packages/http/src/wire-dates-cap.test.ts b/packages/http/src/wire-dates-cap.test.ts new file mode 100644 index 000000000..79f3c04f1 --- /dev/null +++ b/packages/http/src/wire-dates-cap.test.ts @@ -0,0 +1,121 @@ +// An answer's instants are named in `x-ultimate-dates` only while the value fits a response +// header: past the cap there is none, the body is untouched, and one `warn` per operation says so. + +import { afterEach, beforeEach, describe, expect, test } from 'bun:test'; +import { + ctxOf, + installLogSink, + reviveWireDates, + runWithContext, + wireDatePaths, + withChildContext, +} from '@ultimat3/core'; +import { defineHttpConfig } from './config'; +import { asCtx, requestContext } from './context'; +import type { Route } from './router'; +import { cappedWireDates, resetWireDatesCap, WIRE_DATES_MAX_BYTES } from './wire-dates-cap'; + +const AT = new Date('2026-03-04T05:06:07.089Z'); +/** A chart series: the string beside each instant shares its pattern, so no path folds. */ +const series = (points: number) => ({ + points: Array.from({ length: points }, (_, index) => [`series-${index % 3}`, AT] as const), +}); + +const routed = (name: string) => { + const ctx = requestContext({ + url: new URL('http://app.test/chart'), + method: 'POST', + role: 'web', + config: defineHttpConfig({ rateLimit: { scope: 'process' }, dev: false }), + }); + const route: Route = { + method: 'POST', + path: '/chart', + meta: { name, auth: 'public' }, + handler: () => new Response(null), + }; + ctx.route = route; + return asCtx(ctx); +}; + +let lines: { readonly level: string; readonly line: string }[] = []; +let release: () => void = () => undefined; + +beforeEach(() => { + resetWireDatesCap(); + lines = []; + release = installLogSink((line, level) => void lines.push({ level, line })); +}); + +afterEach(() => release()); + +const dropped = () => lines.filter(({ line }) => line.includes('http.wire_dates_dropped')); + +describe('cappedWireDates', () => { + test('a value that fits is the value wireDatePaths wrote, and nothing is logged', () => { + const rows = Array.from({ length: 20_000 }, () => ({ at: AT, title: 'folds to one path' })); + expect(cappedWireDates(rows, routed('feed'))).toBe(wireDatePaths(rows)); + expect(cappedWireDates({ n: 1 }, routed('feed'))).toBeUndefined(); + expect(cappedWireDates(series(20), routed('feed'))).toBe(wireDatePaths(series(20))); + expect(dropped()).toEqual([]); + }); + + test('the cap is a header a default proxy buffer still takes', () => { + expect(WIRE_DATES_MAX_BYTES).toBe(4_096); + }); + + test('an answer whose instants cannot fold stays under the cap: past it, no value at all', () => { + for (const points of [200, 2_000, 20_000]) { + expect(wireDatePaths(series(points))?.length).toBeGreaterThan(WIRE_DATES_MAX_BYTES); + expect(cappedWireDates(series(points), routed('chart'))).toBeUndefined(); + } + }); + + test('the boundary is the encoded length: at the cap it is sent, one byte over it is not', () => { + // One exact path per element; grow the answer until the encoded value crosses the cap. + let points = 1; + while ((wireDatePaths(series(points + 1))?.length ?? 0) <= WIRE_DATES_MAX_BYTES) points += 1; + const fits = cappedWireDates(series(points), routed('edge')); + expect(fits?.length).toBeLessThanOrEqual(WIRE_DATES_MAX_BYTES); + expect(reviveWireDates(JSON.parse(JSON.stringify(series(points))), fits ?? null)).toEqual( + JSON.parse(JSON.stringify(series(points)), (_key, value) => + value === AT.toISOString() ? AT : value, + ), + ); + expect(cappedWireDates(series(points + 1), routed('edge'))).toBeUndefined(); + }); + + test('one warn per operation, naming it, the path count and the size', () => { + for (let call = 0; call < 3; call += 1) cappedWireDates(series(2_000), routed('chart')); + cappedWireDates(series(300), routed('otherChart')); + const seen = dropped(); + expect(seen.map(({ level }) => level)).toEqual(['warn', 'warn']); + const first = JSON.parse(seen[0]?.line ?? '{}') as Record<string, unknown>; + expect(first).toMatchObject({ + operation: 'chart', + paths: 2_000, + bytes: wireDatePaths(series(2_000))?.length, + maxBytes: WIRE_DATES_MAX_BYTES, + }); + expect(JSON.parse(seen[1]?.line ?? '{}')).toMatchObject({ + operation: 'otherChart', + paths: 300, + }); + }); + + test('the operation is read from the request a derived context runs inside', () => { + runWithContext(routed('streamed'), () => + withChildContext({ locale: 'en' }, () => { + expect(cappedWireDates(series(500))).toBeUndefined(); + }), + ); + expect(JSON.parse(dropped()[0]?.line ?? '{}')).toMatchObject({ operation: 'streamed' }); + }); + + test('with no request behind it the answer is the same, logged once under one name', () => { + expect(cappedWireDates(series(500), ctxOf({}))).toBeUndefined(); + expect(cappedWireDates(series(500), undefined)).toBeUndefined(); + expect(cappedWireDates(series(20), undefined)).toBe(wireDatePaths(series(20))); + expect(dropped()).toHaveLength(1); + }); +}); diff --git a/packages/http/src/wire-dates-cap.ts b/packages/http/src/wire-dates-cap.ts new file mode 100644 index 000000000..582ce7ad3 --- /dev/null +++ b/packages/http/src/wire-dates-cap.ts @@ -0,0 +1,55 @@ +// Single responsibility: the size limit on an answer's `x-ultimate-dates` value. A header is not a +// body: a proxy buffers it whole (nginx's default `proxy_buffer_size` is one page, 4 KB or 8 KB), +// so an answer that needs one path per instant is sent with none rather than answered 502. + +import { type Ctx, logger, tryUseContext, wireDatePaths } from '@ultimat3/core'; +import { requestBehind } from './context'; + +/** + * The longest `x-ultimate-dates` value sent, in bytes (the value is URI-encoded, so ASCII). The + * smallest default a reverse proxy gives an upstream's WHOLE header block, which this value shares + * with every other header of the response. + */ +export const WIRE_DATES_MAX_BYTES = 4_096; + +/** Operations already warned about. Bounded by the route table; the ceiling is the belt. */ +const warned = new Set<string>(); +const MAX_OPERATIONS = 4_096; +const NO_REQUEST = 'outside a request'; + +const warnOnce = (value: string, ctx: Ctx | undefined): void => { + const operation = requestBehind(ctx)?.route?.meta.name ?? NO_REQUEST; + if (warned.has(operation)) return; + if (warned.size >= MAX_OPERATIONS) warned.clear(); + warned.add(operation); + // `wireDatePaths` wrote this value a line ago, so it parses; counted once per operation. + const paths = (JSON.parse(decodeURIComponent(value)) as readonly unknown[]).length; + (ctx?.logger ?? logger).warn('http.wire_dates_dropped', { + operation, + paths, + bytes: value.length, + maxBytes: WIRE_DATES_MAX_BYTES, + }); +}; + +/** + * The `x-ultimate-dates` value for `data` (core's `wireDatePaths`), or `undefined` when it holds + * no instant OR the value is past `WIRE_DATES_MAX_BYTES`. Past the cap there is no partial list: + * the client reads every instant as the ISO string the body always held, and the operation — the + * route's name, read off the request behind `ctx` — is logged ONCE at `warn` with the path count. + * The one function an answer's header and a streamed frame's `dates:` line are both written from. + */ +export const cappedWireDates = ( + data: unknown, + ctx: Ctx | undefined = tryUseContext(), +): string | undefined => { + const value = wireDatePaths(data); + if (value === undefined || value.length <= WIRE_DATES_MAX_BYTES) return value; + warnOnce(value, ctx); + return undefined; +}; + +/** TEST SEAM: forget which operations were warned about. */ +export const resetWireDatesCap = (): void => { + warned.clear(); +}; diff --git a/packages/i18n/src/subset.test.ts b/packages/i18n/src/subset.test.ts index f5c13b858..7ec00f594 100644 --- a/packages/i18n/src/subset.test.ts +++ b/packages/i18n/src/subset.test.ts @@ -77,6 +77,21 @@ describe('catalogSubset', () => { } }); + test("a second subset from one translator lists the catalog's keys no second time", () => { + let listed = 0; + const counted = Object.assign((key: string) => server(key), { + raw: server.raw, + keys: (): string[] => { + listed += 1; + return server.keys(); + }, + locale: server.locale, + }); + catalogSubset(counted, ['ui.retry']); + catalogSubset(counted, ['app.likes']); + expect(listed).toBe(1); + }); + test('a __proto__ key in the parsed subset stays a key', () => { const island = subsetTranslator( JSON.parse('{"locale":"en","catalog":{"__proto__":"x","ui.retry":"Retry"}}'), diff --git a/packages/i18n/src/subset.ts b/packages/i18n/src/subset.ts index cf5295bdb..ea2869aba 100644 --- a/packages/i18n/src/subset.ts +++ b/packages/i18n/src/subset.ts @@ -34,6 +34,28 @@ export interface RawTranslator { /** The infix of a family member: `<key>_select_<value>`, `<key>_ordinal_<category>`. */ const FAMILY = /_(?:select|ordinal)_/g; +/** + * Each translator's family members by stem, listed once: a subset is cut per island per request, + * and scanning a 4,000-key catalog each time cost 0.78 ms where the lookups cost 0.006. A + * translator's catalog is fixed for its life (a reload builds a new one), so the index never stales. + */ +const families = new WeakMap<RawTranslator, ReadonlyMap<string, readonly string[]>>(); + +function familiesOf(t: RawTranslator): ReadonlyMap<string, readonly string[]> { + const known = families.get(t); + if (known !== undefined) return known; + const index = new Map<string, string[]>(); + for (const name of t.keys?.() ?? []) { + // Every infix, never only the first: a named key may itself spell `_select_`. + for (const infix of name.matchAll(FAMILY)) { + const stem = name.slice(0, infix.index); + index.set(stem, [...(index.get(stem) ?? []), name]); + } + } + families.set(t, index); + return index; +} + /** * The templates `keys` name in `t`'s locale, each with every plural variant and every `select` and * `ordinal` family member the catalog holds, so `t(key, { count, select, ordinal })` in the island @@ -49,12 +71,9 @@ export function catalogSubset(t: RawTranslator, keys: readonly string[]): Catalo for (const key of keys) { for (const name of [key, ...pluralVariantsOf(key)]) copy(name); } - const wanted = new Set(keys); - for (const name of t.keys?.() ?? []) { - // Every infix, never only the first: a named key may itself spell `_select_`. - for (const infix of name.matchAll(FAMILY)) { - if (wanted.has(name.slice(0, infix.index))) copy(name); - } + const index = familiesOf(t); + for (const key of keys) { + for (const name of index.get(key) ?? []) copy(name); } return { locale: t.locale, catalog }; } diff --git a/packages/jobs/CLAUDE.md b/packages/jobs/CLAUDE.md index 3bc82bf6e..65c581432 100644 --- a/packages/jobs/CLAUDE.md +++ b/packages/jobs/CLAUDE.md @@ -108,7 +108,8 @@ A rule or row marked `†` has its full text in [`docs/history/jobs-rules.md`](. - **A claimed job is counted with core's `beginWork()`**: the drain's in-flight phase waits. The teardown's wait is bounded on SIGTERM (`drain-wait.ts`), unbounded on `stop()`; one teardown, joined. - **A deploy lets a running job FINISH**: SIGTERM only stops claiming; `X_DRAINING` at - `deadlineAt − margin`; settles `interrupted`. † + `inflightUntil − margin` (core's `ShutdownReason.inflightUntil`, where its in-flight wait ends; else + `deadlineAt`); settles `interrupted`. † - **`X_RATE_LIMITED` defers uncounted** (`rateLimitDeferralMs`). - **The drain waits out the claim round it races** — `tick()` registers its round in `rounds` synchronously with its guard. diff --git a/packages/jobs/README.md b/packages/jobs/README.md index ebfd8bb25..cf421e423 100644 --- a/packages/jobs/README.md +++ b/packages/jobs/README.md @@ -254,6 +254,12 @@ so an inline run would be a second execution path next to the worker's — with dedupe and no dead letter. Its idempotency key is the job's own, so a manual `task.enqueue()` and the scheduler's occurrence-scoped fire stay distinct rows on purpose. +**One entry the scheduler cannot queue fails the whole occurrence** (`As of 2026-11`): a `tenant()` +that throws or answers empty, or an empty concurrency key, on any entry of a task's `enqueue`. +Nothing is queued and the watermark stays; `jobs.scheduler.entry-refused` (error) names the task, +the job and the entry index. The next tick owes the same occurrence and logs it again, until the +declaration or the data is repaired — then that tick queues every entry. Never a partial fire. + With no facade installed, `enqueue` publishes straight to `jobDriver()`; with none of those either, it is `X_DRIVER_UNAVAILABLE` at the call, not a silently dropped job. @@ -1664,12 +1670,14 @@ retrySchedule({ attempts: 5, backoff: 'exponential', delay: 1000 }) **A job that declares no `retry` runs under the app's default** (`As of 2026-11`): `jobs.maxAttempts` and `jobs.backoff` in `app.config.ts`, which the boot installs in every role -(`installDefaultRetry`, on `@ultimat3/jobs/adapter`). With neither key set it is `DEFAULT_RETRY`: -3 attempts, exponential. +(`installDefaultRetry`, on `@ultimat3/jobs/adapter`; the CLI's `startQueue`, the boot every entry +point shares — `x tasks run`, `x jobs` and `x db backfill` included). With neither key set it is +`DEFAULT_RETRY`: 3 attempts, exponential. | Declared | Attempts | Backoff | |---|---|---| -| no `retry` — a factory's is optional (`purge()`, `backfill()`, `rollup()`, …), or `retry: DEFAULT_RETRY` | `jobs.maxAttempts` | `jobs.backoff` | +| no `retry` — a factory's is optional (`purge()`, `backfill()`, `rollup()`, …), or `retry: undefined` on `job()` (the key is required, its value may be `undefined`) | `jobs.maxAttempts` | `jobs.backoff` | +| `retry: { ...DEFAULT_RETRY }` — a policy, spelled out | 3 | `'exponential'` | | `retry: { attempts: 5 }` | 5 | `jobs.backoff` | | `retry: { attempts: 5, backoff: 'linear' }` | 5 | `'linear'` | diff --git a/packages/jobs/src/backfill.ts b/packages/jobs/src/backfill.ts index b46613c10..39351ae19 100644 --- a/packages/jobs/src/backfill.ts +++ b/packages/jobs/src/backfill.ts @@ -27,8 +27,7 @@ import { stampBackfill } from './backfill-registry'; import type { AnyBackfill } from './backfill-source'; import { assertBackfillSource, ledgerNameFor, scopedPayload } from './backfill-source'; import type { JobHandle } from './job'; -import { job } from './job'; -import { DEFAULT_RETRY } from './retry'; +import { factoryJob } from './job'; import type { JobTenant } from './tenant'; /** @@ -100,7 +99,7 @@ export function backfill<Row, I>( }); const scope = definition.scope; - const handle = job<BackfillInput & { readonly input?: unknown }>({ + const handle = factoryJob<BackfillInput & { readonly input?: unknown }>({ name: definition.name, // Unscoped: byte-identical to before scopes existed. Scoped: the force flag and the input. input: @@ -114,7 +113,7 @@ export function backfill<Row, I>( // Forwarded verbatim, like every other job field this factory carries: a backfill that // declared its tenant and then ran under somebody else's would be a factory deciding authz. tenant: definition.tenant as JobTenant<BackfillInput & { readonly input?: unknown }>, - retry: definition.retry ?? DEFAULT_RETRY, + retry: definition.retry, ...(definition.queue === undefined ? {} : { queue: definition.queue }), ...(definition.timeout === undefined ? {} : { timeout: definition.timeout }), run: (args) => diff --git a/packages/jobs/src/consumer.ts b/packages/jobs/src/consumer.ts index 486507631..d294c1b0c 100644 --- a/packages/jobs/src/consumer.ts +++ b/packages/jobs/src/consumer.ts @@ -12,10 +12,9 @@ import { stampConsumer } from './consumer-registry'; import type { ConsumerDefinition, ConsumerHandle, ConsumerInput } from './consumer-types'; import type { EnqueueResult } from './driver'; import type { JobHandle } from './job'; -import { job } from './job'; +import { factoryJob } from './job'; import type { EnqueueManyOptions } from './job-enqueue-many'; import type { EnqueueOptions } from './outbox'; -import { DEFAULT_RETRY } from './retry'; import { task } from './task'; const MINUTE_MS = 60_000; @@ -82,7 +81,7 @@ export function consumer<Item, C>(definition: ConsumerDefinition<Item, C>): Cons const cron = rearmCron(name, definition.rearm ?? '1m'); const queue = definition.queue === undefined ? {} : { queue: definition.queue }; - const handle: JobHandle<ConsumerInput> = job<ConsumerInput>({ + const handle: JobHandle<ConsumerInput> = factoryJob<ConsumerInput>({ name, input: t.object({ key: t.string.min(1) }), tenant: definition.tenant, @@ -91,7 +90,7 @@ export function consumer<Item, C>(definition: ConsumerDefinition<Item, C>): Cons idempotencyKey: ({ key }) => `consumer:${name}:${key}`, // The backstop the key alone cannot be: two rows of one key never run at once. concurrency: { key: ({ key }) => key, limit: 1, whenBusy: 'wait' }, - retry: definition.retry ?? DEFAULT_RETRY, + retry: definition.retry, ...queue, run: (args) => asConsumer(name, () => consumerRun({ definition, size }, args)), }); @@ -114,12 +113,12 @@ export function consumer<Item, C>(definition: ConsumerDefinition<Item, C>): Cons // `keys` may read the database, and a task's entries are synchronous — so the tick enqueues // this one arm run, which asks `keys` and enqueues every key it answers. - const arm = job<Record<string, never>>({ + const arm = factoryJob<Record<string, never>>({ name: `${name}.arm`, input: t.object({}), tenant: 'none', idempotencyKey: () => `consumer:${name}:arm`, - retry: DEFAULT_RETRY, + retry: undefined, ...queue, async run({ ctx, step }) { const keys = await definition.keys({ ctx }); diff --git a/packages/jobs/src/errors-declaration.ts b/packages/jobs/src/errors-declaration.ts index 2402e98e3..8e2b23812 100644 --- a/packages/jobs/src/errors-declaration.ts +++ b/packages/jobs/src/errors-declaration.ts @@ -34,14 +34,19 @@ export class JobDeclarationInvalidError extends UltimateError { } } -/** The required fields a definition lacks, in declaration order. Read off the value, not the type. */ -export function missingJobFields(definition: object): string[] { +/** + * The required fields a definition lacks, in declaration order. Read off the value, not the type. + * `factory`: a factory over `job()` may pass `retry: undefined`, "declares none" (`factoryJob`). + */ +export function missingJobFields(definition: object, factory = false): string[] { const loose = definition as unknown as Readonly<Record<string, unknown>>; const missing: string[] = []; if (typeof loose['input'] !== 'object' || loose['input'] === null) missing.push('input'); if (typeof loose['idempotencyKey'] !== 'function') missing.push('idempotencyKey'); if (loose['tenant'] === undefined) missing.push('tenant'); - if (typeof loose['retry'] !== 'object' || loose['retry'] === null) missing.push('retry'); + const retry = loose['retry']; + const declaresNone = factory && retry === undefined; + if (!declaresNone && (typeof retry !== 'object' || retry === null)) missing.push('retry'); if (typeof loose['run'] !== 'function') missing.push('run'); return missing; } diff --git a/packages/jobs/src/export.ts b/packages/jobs/src/export.ts index 07b0f5943..086cc59f4 100644 --- a/packages/jobs/src/export.ts +++ b/packages/jobs/src/export.ts @@ -30,9 +30,8 @@ import { EXPORT_FORMATS } from './export-format'; import { exportPass } from './export-pass'; import type { ExportSink } from './export-sink'; import type { JobHandle } from './job'; -import { job } from './job'; +import { factoryJob } from './job'; import type { RetryPolicy } from './retry'; -import { DEFAULT_RETRY } from './retry'; import type { JobTenant } from './tenant'; /** @@ -187,7 +186,7 @@ export function exportRows<Row, I>(definition: ExportDefinition<Row, I>): JobHan sink: { put: (key, body) => definition.sink().put(key, body) }, }; - return job<I>({ + return factoryJob<I>({ name: definition.name, input: definition.input, // ONE live pass per artifact, derived rather than declared: two runs writing the same prefix @@ -196,7 +195,7 @@ export function exportRows<Row, I>(definition: ExportDefinition<Row, I>): JobHan // second answer to the question the key exists to settle. idempotencyKey: (input) => `${definition.name}:${definition.prefix(input)}`, tenant: definition.tenant, - retry: definition.retry ?? DEFAULT_RETRY, + retry: definition.retry, ...(definition.queue === undefined ? {} : { queue: definition.queue }), ...(definition.timeout === undefined ? {} : { timeout: definition.timeout }), run: (args) => diff --git a/packages/jobs/src/import.ts b/packages/jobs/src/import.ts index a75b51d72..87afc90be 100644 --- a/packages/jobs/src/import.ts +++ b/packages/jobs/src/import.ts @@ -20,9 +20,8 @@ import type { ExportSink } from './export-sink'; import { importPass } from './import-pass'; import type { ImportSource } from './import-source'; import type { JobHandle } from './job'; -import { job } from './job'; +import { factoryJob } from './job'; import type { RetryPolicy } from './retry'; -import { DEFAULT_RETRY } from './retry'; import type { JobTenant } from './tenant'; /** Records per `handle` call: one statement's worth. A page hands over its whole read in these. */ @@ -160,14 +159,14 @@ export function importRows<Rec, I>(definition: ImportDefinition<Rec, I>): JobHan pace, }; - return job<I>({ + return factoryJob<I>({ name, input: definition.input, // ONE live pass per file, derived rather than declared, as an export's per prefix: two passes // over one file would hand every row to `handle` twice and race over every error part. idempotencyKey: (input) => `${name}:${definition.key(input)}`, tenant: definition.tenant, - retry: definition.retry ?? DEFAULT_RETRY, + retry: definition.retry, ...(definition.queue === undefined ? {} : { queue: definition.queue }), ...(definition.timeout === undefined ? {} : { timeout: definition.timeout }), run: (args) => importPass<Rec, I>(plan, args), diff --git a/packages/jobs/src/job-types.ts b/packages/jobs/src/job-types.ts index 038a335d6..69330364a 100644 --- a/packages/jobs/src/job-types.ts +++ b/packages/jobs/src/job-types.ts @@ -263,3 +263,13 @@ export interface JobHandle<I = unknown> { } export type AnyJobHandle = JobHandle<unknown>; + +/** + * What a factory over `job()` declares (`factoryJob`, `job.ts`): the same definition, with `retry` + * `undefined` meaning "declares none" — the app's default (`jobs.maxAttempts`, `jobs.backoff`), + * resolved when `handle.retry` is read (`retry-default.ts`). Internal: an app's `job()` states its + * retry, and widening `JobDefinition.retry` itself is a public-API change. + */ +export interface FactoryJobDefinition<I, R = unknown> extends Omit<JobDefinition<I, R>, 'retry'> { + readonly retry: RetryPolicy | undefined; +} diff --git a/packages/jobs/src/job.ts b/packages/jobs/src/job.ts index 2c28b698e..80b354ffc 100644 --- a/packages/jobs/src/job.ts +++ b/packages/jobs/src/job.ts @@ -33,7 +33,14 @@ import { assertJobTenant, jobTenantFor } from './tenant'; export type { AnyJobHandle, JobActor, JobDefinition, JobHandle, JobRunArgs } from './job-types'; -import type { AnyJobHandle, JobActor, JobDefinition, JobHandle, JobRunArgs } from './job-types'; +import type { + AnyJobHandle, + FactoryJobDefinition, + JobActor, + JobDefinition, + JobHandle, + JobRunArgs, +} from './job-types'; /** * The registry, and its name-sorted list cached until the next write. Every claim reads the list @@ -83,13 +90,25 @@ interface JobOrigin { const origin = new WeakMap<object, JobOrigin>(); export function job<I, R = unknown>(definition: JobDefinition<I, R>): JobHandle<I> { + return declareJob(definition, false); +} + +/** + * `job()` for a factory over it (`purge()`, `backfill()`, …): `retry: undefined` is "declares + * none", the app's default read when `handle.retry` is. Internal — not on the barrel. + */ +export function factoryJob<I, R = unknown>(definition: FactoryJobDefinition<I, R>): JobHandle<I> { + return declareJob(definition, true); +} + +function declareJob<I, R>(definition: FactoryJobDefinition<I, R>, factory: boolean): JobHandle<I> { anonymous += 1; const name = definition.name ?? `anonymous-job-${anonymous}`; // Runtime backstops for generated code and JS callers; TS already forbids omitting any of them. // Collected, never one at a time — see `JobDeclarationInvalidError`. The two fields with a code // of their own keep it when they are the only thing missing: shipped codes keep their meaning. - const missing = missingJobFields(definition); + const missing = missingJobFields(definition, factory); if (missing.length === 1 && missing[0] === 'idempotencyKey') { throw new IdempotencyRequiredError({ job: name, positional: definition.name === undefined }); } @@ -100,8 +119,10 @@ export function job<I, R = unknown>(definition: JobDefinition<I, R>): JobHandle< // A COUNT, so whole and finite as well as at least 1: `>= 1` alone admitted `Infinity` and // `1.5`, which the memory driver ran and Postgres refused at the first enqueue (`$7::int`). // Zero is not "never retries" — that is `attempts: 1` — it is a job that never executes at all. - finiteCount(`job "${name}"`, 'retry.attempts', definition.retry.attempts, 1); - assertRetryJitter(name, definition.retry.jitter); + if (definition.retry !== undefined) { + finiteCount(`job "${name}"`, 'retry.attempts', definition.retry.attempts, 1); + assertRetryJitter(name, definition.retry.jitter); + } // `concurrency: 0` is not "no cap" — it is a fleet slot table that grants nothing, and the job // is permanently unrunnable with no log line. Refused where it is written, plain or keyed. const concurrency = resolveConcurrency(name, definition.concurrency); diff --git a/packages/jobs/src/ledger.ts b/packages/jobs/src/ledger.ts index 4abd1bd63..5d23a23fa 100644 --- a/packages/jobs/src/ledger.ts +++ b/packages/jobs/src/ledger.ts @@ -7,11 +7,10 @@ import type { MoneyValue, StandardSchemaV1 } from '@ultimat3/schema'; import { isCurrencyCode, isMoneyScale, t } from '@ultimat3/schema'; import type { DurationInput } from './clock'; import type { JobHandle } from './job'; -import { job } from './job'; +import { factoryJob } from './job'; import type { LedgerBook, LedgerLine } from './ledger-book'; import { LedgerEntryInvalidError, LedgerUnbalancedError } from './ledger-errors'; import type { RetryPolicy } from './retry'; -import { DEFAULT_RETRY } from './retry'; import type { JobTenant } from './tenant'; /** One leg: an account the app names and a signed amount. Debit or credit is the sign's, not ours. */ @@ -125,13 +124,13 @@ export const ledgerLines = (posting: LedgerPosting): readonly LedgerLine[] => })); export function ledger(definition: LedgerDefinition): JobHandle<LedgerPosting> { - return job<LedgerPosting>({ + return factoryJob<LedgerPosting>({ name: definition.name, input: postingSchema, tenant: definition.tenant, // One live run per posting; the book's `(postingKey, line)` holds it after the run is gone. idempotencyKey: (posting) => `${definition.name}:${posting.key}`, - retry: definition.retry ?? DEFAULT_RETRY, + retry: definition.retry, ...(definition.queue === undefined ? {} : { queue: definition.queue }), ...(definition.timeout === undefined ? {} : { timeout: definition.timeout }), run: async ({ step, input }): Promise<LedgerReport> => { diff --git a/packages/jobs/src/limits-abandon.test.ts b/packages/jobs/src/limits-abandon.test.ts index 17561d15b..495fa798f 100644 --- a/packages/jobs/src/limits-abandon.test.ts +++ b/packages/jobs/src/limits-abandon.test.ts @@ -4,6 +4,7 @@ import { describe, expect, test } from 'bun:test'; import type { Clock, Ctx } from '@ultimat3/core'; +import { nowMs } from './clock'; import type { ClaimedJob, JobDriver } from './driver'; import { concurrencyLimiter } from './limits'; import { createAdmission } from './worker-admit'; @@ -94,6 +95,7 @@ function admission(grants: (SlotGrant | Error)[]) { fleetSlots, workerId: 'w1', pollIntervalMs: 25, + visibilityTimeoutMs: 30_000, context: () => ({}) as Ctx, }); return { admit, limiter }; @@ -102,29 +104,29 @@ function admission(grants: (SlotGrant | Error)[]) { describe('the admission hands the rate back with the slot', () => { test('a job shed over job.concurrency does not spend its tenant a start', async () => { const { admit, limiter } = admission([{ outcome: 'wait', limit: 1, key: undefined }]); - expect((await admit(claimed('j1'), 'default', () => [])).kind).toBe('waiting'); + expect((await admit(claimed('j1'), 'default', () => [], nowMs())).kind).toBe('waiting'); expect(limiter.inFlight()).toBe(0); // limit 1: the shed above was the tenant's whole window before the fix. - expect((await admit(claimed('j1'), 'default', () => [])).kind).toBe('run'); + expect((await admit(claimed('j1'), 'default', () => [], nowMs())).kind).toBe('run'); }); test('a lease-store failure hands the rate back too', async () => { const { admit } = admission([new Error('57P01')]); let thrown: unknown; try { - await admit(claimed('j1'), 'default', () => []); + await admit(claimed('j1'), 'default', () => [], nowMs()); } catch (error) { thrown = error; } expect((thrown as Error).message).toBe('57P01'); - expect((await admit(claimed('j1'), 'default', () => [])).kind).toBe('run'); + expect((await admit(claimed('j1'), 'default', () => [], nowMs())).kind).toBe('run'); }); test('an undecidable key STARTS — the attempt fails in executeJob — and keeps its stamp', async () => { const { admit } = admission([{ outcome: 'undecidable', error: new Error('no key') }]); - const first = await admit(claimed('j1'), 'default', () => []); + const first = await admit(claimed('j1'), 'default', () => [], nowMs()); expect(first.kind).toBe('run'); if (first.kind === 'run') first.lease.release(); - expect((await admit(claimed('j2'), 'default', () => [])).kind).toBe('waiting'); + expect((await admit(claimed('j2'), 'default', () => [], nowMs())).kind).toBe('waiting'); }); }); diff --git a/packages/jobs/src/partitions.ts b/packages/jobs/src/partitions.ts index 49aa2b47c..35b403e56 100644 --- a/packages/jobs/src/partitions.ts +++ b/packages/jobs/src/partitions.ts @@ -12,9 +12,8 @@ import { t } from '@ultimat3/schema'; import type { DurationInput } from './clock'; import { nowMs } from './clock'; import type { JobHandle } from './job'; -import { job } from './job'; +import { factoryJob } from './job'; import type { RetryPolicy } from './retry'; -import { DEFAULT_RETRY } from './retry'; import type { TaskHandle } from './task'; import { task } from './task'; @@ -94,7 +93,7 @@ function fromOf(name: string, from: string | undefined): Date | undefined { export function partitions(definition: PartitionsDefinition = {}): PartitionsJob { const name = definition.name ?? DEFAULT_PARTITIONS_NAME; const clock = definition.clock ?? liveClock; - const handle = job<PartitionsInput>({ + const handle = factoryJob<PartitionsInput>({ name, input: t.object({ from: t.string.optional() }), // Partitions are tables, not any tenant's rows. @@ -102,7 +101,7 @@ export function partitions(definition: PartitionsDefinition = {}): PartitionsJob // One live pass: a second tick while one runs is the same pass, and the SQL is idempotent anyway. // A `from` run is a different pass: it must not fold into the schedule's. idempotencyKey: (input) => (input.from === undefined ? name : `${name}:from:${input.from}`), - retry: definition.retry ?? DEFAULT_RETRY, + retry: definition.retry, ...(definition.queue === undefined ? {} : { queue: definition.queue }), ...(definition.timeout === undefined ? {} : { timeout: definition.timeout }), async run({ input, step }): Promise<PartitionsReport> { diff --git a/packages/jobs/src/purge.ts b/packages/jobs/src/purge.ts index 6ae1e1c56..b2a9246bd 100644 --- a/packages/jobs/src/purge.ts +++ b/packages/jobs/src/purge.ts @@ -18,10 +18,9 @@ import { t } from '@ultimat3/schema'; import type { DurationInput } from './clock'; import { nowMs } from './clock'; import type { JobHandle } from './job'; -import { job } from './job'; +import { factoryJob } from './job'; import { entityTargets, type PurgeEntities, recordPurgeCoverage } from './purge-entities'; import type { RetryPolicy } from './retry'; -import { DEFAULT_RETRY } from './retry'; /** * One table's worth of expired rows, behind the narrowest possible seam. @@ -131,7 +130,7 @@ export function purge(definition: PurgeDefinition): JobHandle<PurgeInput> { const clock = definition.clock; recordPurgeCoverage(definition.entities); - return job<PurgeInput>({ + return factoryJob<PurgeInput>({ ...(definition.name === undefined ? {} : { name: definition.name }), input: t.object({}), // One live sweep, forever: a second enqueue while a pass is still running is the same pass, @@ -141,7 +140,7 @@ export function purge(definition: PurgeDefinition): JobHandle<PurgeInput> { // Framework tables, not an org's rows. Every statement behind a target is raw SQL over the // whole table, so there is no tenant-scoped read here to fail closed. tenant: 'none', - retry: definition.retry ?? DEFAULT_RETRY, + retry: definition.retry, ...(definition.queue === undefined ? {} : { queue: definition.queue }), ...(definition.timeout === undefined ? {} : { timeout: definition.timeout }), async run({ step }): Promise<PurgeReport> { diff --git a/packages/jobs/src/refresh-view.ts b/packages/jobs/src/refresh-view.ts index fc344ca09..7469abfb7 100644 --- a/packages/jobs/src/refresh-view.ts +++ b/packages/jobs/src/refresh-view.ts @@ -7,8 +7,8 @@ import type { EntityCore } from '@ultimat3/entity'; import { t } from '@ultimat3/schema'; import type { DurationInput } from './clock'; import type { JobHandle } from './job'; -import { job } from './job'; -import { DEFAULT_RETRY, type RetryPolicy } from './retry'; +import { factoryJob } from './job'; +import type { RetryPolicy } from './retry'; import { RefreshViewInvalidError } from './rollup-errors'; export interface RefreshViewDefinition { @@ -61,14 +61,14 @@ export function refreshView(definition: RefreshViewDefinition): JobHandle<Record const statement = concurrently ? sql`refresh materialized view concurrently ${target}` : sql`refresh materialized view ${target}`; - return job<Record<string, never>, RefreshViewReport>({ + return factoryJob<Record<string, never>, RefreshViewReport>({ name: definition.name, input: t.object({}), // One refresh at a time: a second enqueue while one runs would compute the same rows again. idempotencyKey: () => `refresh-view:${definition.name}`, // A materialized view spans every tenant's rows; the read path scopes them, not the refresh. tenant: 'none', - retry: definition.retry ?? DEFAULT_RETRY, + retry: definition.retry, ...(definition.queue === undefined ? {} : { queue: definition.queue }), ...(definition.timeout === undefined ? {} : { timeout: definition.timeout }), run: ({ step }) => diff --git a/packages/jobs/src/retry-default.test.ts b/packages/jobs/src/retry-default.test.ts index 59695e66e..3a57199a2 100644 --- a/packages/jobs/src/retry-default.test.ts +++ b/packages/jobs/src/retry-default.test.ts @@ -10,7 +10,7 @@ import { resetJobDriver, } from './adapter'; import { memoryJobDriver } from './driver-memory'; -import { job, resetJobs } from './job'; +import { factoryJob, job, resetJobs } from './job'; import { resetJobsFacade } from './outbox'; import { purge } from './purge'; import { DEFAULT_RETRY, retrySchedule } from './retry'; @@ -89,4 +89,37 @@ describe('the retry of a job that declares none', () => { expect(() => installDefaultRetry({ attempts: 2.5, backoff: 'fixed' })).toThrow(/X_INVARIANT/); expect(purge({ name: 'sweep', targets: () => [] }).retry).toEqual(DEFAULT_RETRY); }); + + test('a factory\'s `retry: undefined` is "declares none": the installed default, read late', () => { + const none = factoryJob({ + tenant: 'none', + name: 'none', + input: passthrough<Record<string, never>>(), + idempotencyKey: () => 'k', + retry: undefined, + run: () => Promise.resolve(), + }); + expect(none.retry).toEqual(DEFAULT_RETRY); + installDefaultRetry({ attempts: 5, backoff: 'fixed' }); + expect(none.retry).toEqual({ ...DEFAULT_RETRY, attempts: 5, backoff: 'fixed' }); + }); + + test("a policy spelled out as DEFAULT_RETRY's values is DECLARED: its own 3 attempts", () => { + installDefaultRetry({ attempts: 5, backoff: 'fixed' }); + expect(declared({ ...DEFAULT_RETRY }).retry.attempts).toBe(3); + }); + + test('job() still refuses an omitted or undefined retry: an app states its own', () => { + const loose = { + tenant: 'none', + name: 'omitted', + input: passthrough<Record<string, never>>(), + idempotencyKey: () => 'k', + run: () => Promise.resolve(), + } as unknown as Parameters<typeof job>[0]; + expect(() => job(loose)).toThrow(/X_JOB_DECLARATION_INVALID/); + expect(() => job({ ...loose, retry: undefined } as unknown as typeof loose)).toThrow( + /X_JOB_DECLARATION_INVALID/, + ); + }); }); diff --git a/packages/jobs/src/retry-default.ts b/packages/jobs/src/retry-default.ts index b6d0c7570..a4cbcab09 100644 --- a/packages/jobs/src/retry-default.ts +++ b/packages/jobs/src/retry-default.ts @@ -1,6 +1,6 @@ -// The retry a job that declares none runs under: `DEFAULT_RETRY`, or what the app's boot installed -// over it from `jobs.maxAttempts` / `jobs.backoff`. Resolved on READ, never at declaration: a handle -// is built when its module is imported, which is before the boot has read the config. +// The retry a job that declares none (`retry: undefined`) runs under: `DEFAULT_RETRY`, or what the +// app's boot installed over it from `jobs.maxAttempts` / `jobs.backoff`. Resolved on READ, never at +// declaration: a handle is built when its module is imported, before the boot has read the config. import { finiteCount } from '@ultimat3/core'; import type { BackoffStrategy, RetryPolicy } from './retry'; @@ -33,13 +33,17 @@ export function resetDefaultRetry(): void { } /** - * The policy a handle runs under, given what its definition was handed. `DEFAULT_RETRY` ITSELF is - * "declares none" — what every factory passes for an omitted `retry` — and takes the installed - * attempts and curve. A declared policy keeps its own attempts, and the installed curve only when - * it names none. + * The policy a handle runs under, given what its definition was handed. `undefined` is "declares + * none" — what every factory passes for an omitted `retry` — and takes the installed attempts and + * curve. A declared policy keeps its own attempts, and the installed curve only when it names none. */ -export function resolvedRetry(declared: RetryPolicy): RetryPolicy { +export function resolvedRetry(declared: RetryPolicy | undefined): RetryPolicy { + // `=== DEFAULT_RETRY` is the identity sentinel this replaces, kept ONLY so the factories outside + // this package that still pass `definition.retry ?? DEFAULT_RETRY` (`@ultimat3/notify`'s + // `notifier.ts`, `@ultimat3/scraping`'s `scrape.ts`) keep the app's default until they pass + // `undefined`. Delete it with the last of them; nothing in this package relies on it. + if (declared === undefined || declared === DEFAULT_RETRY) + return { ...DEFAULT_RETRY, ...installed }; if (installed === undefined) return { ...DEFAULT_RETRY, ...declared }; - if (declared === DEFAULT_RETRY) return { ...DEFAULT_RETRY, ...installed }; return { ...DEFAULT_RETRY, backoff: installed.backoff, ...declared }; } diff --git a/packages/jobs/src/rollup.ts b/packages/jobs/src/rollup.ts index a1e52972b..4e78ba626 100644 --- a/packages/jobs/src/rollup.ts +++ b/packages/jobs/src/rollup.ts @@ -10,8 +10,8 @@ import { t } from '@ultimat3/schema'; import { isValidTimeZone } from '@ultimat3/time'; import { type DurationInput, finiteDurationMs, nowMs } from './clock'; import type { JobHandle } from './job'; -import { job } from './job'; -import { DEFAULT_RETRY, type RetryPolicy } from './retry'; +import { factoryJob } from './job'; +import type { RetryPolicy } from './retry'; import { RollupInvalidError } from './rollup-errors'; import type { JobTenant } from './tenant'; @@ -160,13 +160,13 @@ export function rollup<S, Into, W>( unit: definition.bucket.unit, timeZone: definition.bucket.timeZone, }; - return job<RollupInput, RollupReport>({ + return factoryJob<RollupInput, RollupReport>({ name: definition.name, input: t.object({ orgId: t.string.optional() }), // One live run per window: a second enqueue while one is running is the same recomputation. idempotencyKey: (input) => `rollup:${definition.name}:${input.orgId ?? '*'}`, tenant: definition.tenant, - retry: definition.retry ?? DEFAULT_RETRY, + retry: definition.retry, ...(definition.queue === undefined ? {} : { queue: definition.queue }), ...(definition.timeout === undefined ? {} : { timeout: definition.timeout }), run: ({ ctx, input, step }) => diff --git a/packages/jobs/src/scheduler-dispatch.ts b/packages/jobs/src/scheduler-dispatch.ts index e1d8e59b7..046d68e1f 100644 --- a/packages/jobs/src/scheduler-dispatch.ts +++ b/packages/jobs/src/scheduler-dispatch.ts @@ -2,7 +2,7 @@ // watermark in ONE step (`SchedulerState.fire`). Apart from `scheduler.ts` because that file is the // round — which occurrences are owed, under which lease — and this is what firing one of them is. -import { logger } from '@ultimat3/core'; +import { logger, renderThrowable } from '@ultimat3/core'; import type { JobDriver } from './driver'; import { signalEnqueued } from './enqueue-signal'; import { instrumentedFire } from './job-instrument'; @@ -37,12 +37,28 @@ export async function dispatchOccurrence( ): Promise<DispatchedOccurrence | undefined> { // The occurrence, not `at`: a catch-up dispatch runs long after the instant it fires for, // and the payload has to describe the occurrence the email/report claims to be about. - const requests = handle.entries(occurrenceMs).map(([handleForJob, input]) => { - // The facade's refusal, at the one enqueue that does not go through it: an empty key. - handleForJob.concurrencyKeyFor(input); - // The org the payload names, as the facade queues it (`enqueue-record.ts`): the key's - // namespace is `(name, tenant, key)`, so a fan-out per org queued for nobody is ONE row. - const tenantId = handleForJob.tenantFor(input); + const requests = handle.entries(occurrenceMs).map(([handleForJob, input], entry) => { + let tenantId: string | undefined; + try { + // The facade's refusal, at the one enqueue that does not go through it: an empty key. + handleForJob.concurrencyKeyFor(input); + // The org the payload names, as the facade queues it (`enqueue-record.ts`): the key's + // namespace is `(name, tenant, key)`, so a fan-out per org queued for nobody is ONE row. + tenantId = handleForJob.tenantFor(input); + } catch (error) { + // The WHOLE occurrence fails, before anything is queued or the watermark moves: the next + // tick owes it again, and logs this again, until the declaration or the data is repaired — + // then every entry fires. Loud and retried, never a partial fire or a silent skip. The + // round's `jobs.task.round_failed` names the task; this names the entry that failed it. + logger.error('jobs.scheduler.entry-refused', { + task: handle.name, + job: handleForJob.name, + entry, + occurrence: new Date(occurrenceMs).toISOString(), + error: renderThrowable(error), + }); + throw error; + } return { name: handleForJob.name, queue: handleForJob.queue, diff --git a/packages/jobs/src/scheduler-tenant.test.ts b/packages/jobs/src/scheduler-tenant.test.ts index fb399029b..65e063b4c 100644 --- a/packages/jobs/src/scheduler-tenant.test.ts +++ b/packages/jobs/src/scheduler-tenant.test.ts @@ -2,8 +2,8 @@ // is `(name, tenant, key)`, so a fan-out per org that left the tenant off deduped every org onto // the first one's row — and `perTenant` counted the survivor as nobody's. -import { afterEach, beforeEach, describe, expect, test } from 'bun:test'; -import type { Clock } from '@ultimat3/core'; +import { afterEach, beforeEach, describe, expect, mock, spyOn, test } from 'bun:test'; +import { type Clock, logger } from '@ultimat3/core'; import type { StandardSchemaV1 } from '@ultimat3/schema'; import { resetJobDriver } from './adapter'; import { memoryJobDriver } from './driver-memory'; @@ -56,6 +56,7 @@ beforeEach(() => { }); afterEach(() => { + mock.restore(); resetJobDriver(); resetJobsFacade(); }); @@ -113,4 +114,61 @@ describe('a scheduler fire and the tenant a job declares', () => { const [row] = (await driver.introspect?.list()) ?? []; expect(row?.tenantId).toBeUndefined(); }); + + // Decided 2026-11-19: an entry whose tenant() throws (or answers empty) fails the WHOLE + // occurrence — the same as a refused key one line above it — and loudly: one error naming the + // task, the job and the entry. Nothing is queued and the watermark stays, so the next tick owes + // the same occurrence again and says so again; once the declaration or the data is repaired, + // that tick queues every entry of it. Never a partial fire, never a silent skip. + test('one entry whose tenant() throws: the occurrence queues nothing, says which entry, and the next tick retries it', async () => { + let broken = true; + const digest = job<OrgInput>({ + tenant: (input) => (broken && input.orgId === 'B' ? '' : input.orgId), + name: 'digest', + input: passthrough<OrgInput>(), + idempotencyKey: () => 'digest', + retry: { attempts: 1 }, + run: () => Promise.resolve(), + }); + task({ + name: 'nightlyDigest', + cron: '0 3 * * *', + tz: 'UTC', + enqueue: () => [ + [digest, { orgId: 'A' }], + [digest, { orgId: 'B' }], + ], + }); + const clock = fakeClock(T0); + const driver = memoryJobDriver({ clock }); + const scheduler = jobScheduler({ driver, clock, cron: dailyAt3 }); + const error = spyOn(logger, 'error').mockImplementation(() => undefined); + const refusals = () => + error.mock.calls.filter(([message]) => message === 'jobs.scheduler.entry-refused'); + + await scheduler.tick(); + clock.advance(4 * 3_600_000); + expect(await scheduler.tick()).toEqual([]); + + expect((await driver.introspect?.list()) ?? []).toEqual([]); + expect(refusals()).toEqual([ + [ + 'jobs.scheduler.entry-refused', + expect.objectContaining({ task: 'nightlyDigest', job: 'digest', entry: 1 }), + ], + ]); + + // Still owed: the next tick tries the same occurrence and says so again. + clock.advance(60_000); + expect(await scheduler.tick()).toEqual([]); + expect(refusals()).toHaveLength(2); + + // Repaired: the same occurrence fires whole, both orgs, nothing lost. + broken = false; + clock.advance(60_000); + const [dispatched] = await scheduler.tick(); + expect(dispatched?.occurrenceMs).toBe(T0 + 3 * 3_600_000); + const rows = (await driver.introspect?.list()) ?? []; + expect(rows.map((row) => row.tenantId).sort()).toEqual(['A', 'B']); + }); }); diff --git a/packages/jobs/src/subject-jobs.ts b/packages/jobs/src/subject-jobs.ts index 3eacebd3f..a37ad0fa8 100644 --- a/packages/jobs/src/subject-jobs.ts +++ b/packages/jobs/src/subject-jobs.ts @@ -13,9 +13,8 @@ import type { ExportSink } from './export-sink'; import { auditedErase } from './gdpr-audit'; import { unerasedPersonalData } from './gdpr-coverage'; import type { JobHandle } from './job'; -import { job } from './job'; +import { factoryJob } from './job'; import type { RetryPolicy } from './retry'; -import { DEFAULT_RETRY } from './retry'; import type { StepApi } from './steps-api'; import type { Subject } from './subject'; import type { SubjectEraseReport } from './subject-erase-pass'; @@ -73,14 +72,14 @@ const common = <I>(definition: SubjectJobDefinition<I>) => ({ name: definition.name, input: definition.input, tenant: definition.tenant, - retry: definition.retry ?? DEFAULT_RETRY, + retry: definition.retry, ...(definition.queue === undefined ? {} : { queue: definition.queue }), ...(definition.timeout === undefined ? {} : { timeout: definition.timeout }), }); export function subjectErase<I>(definition: SubjectJobDefinition<I>): JobHandle<I> { const { subject } = definition; - return job<I>({ + return factoryJob<I>({ ...common(definition), // One live erase per person: a second request while one runs is the same run. idempotencyKey: (input) => `${definition.name}:${subject.init.key(input)}`, @@ -94,7 +93,7 @@ export function subjectErase<I>(definition: SubjectJobDefinition<I>): JobHandle< export function subjectExport<I>(definition: SubjectExportDefinition<I>): JobHandle<I> { const { subject } = definition; const clock = definition.clock ?? liveClock; - return job<I>({ + return factoryJob<I>({ ...common(definition), // One live pass per artifact, derived as `exportRows()` derives it. idempotencyKey: (input) => `${definition.name}:${definition.prefix(input)}`, diff --git a/packages/jobs/src/webhook-receiver.ts b/packages/jobs/src/webhook-receiver.ts index 8c15c3996..48d7cb23a 100644 --- a/packages/jobs/src/webhook-receiver.ts +++ b/packages/jobs/src/webhook-receiver.ts @@ -15,8 +15,7 @@ import { DEFAULT_WEBHOOK_BODY_LIMIT } from '@ultimat3/http'; import type { JsonValue } from '@ultimat3/schema'; import { t } from '@ultimat3/schema'; import { JobTenantMismatchError } from './errors-tenant'; -import { job, registeredJobs } from './job'; -import { DEFAULT_RETRY } from './retry'; +import { factoryJob, registeredJobs } from './job'; import type { JobTenant } from './tenant'; import { WebhookReceiverInvalidError } from './webhook-receiver-errors'; import { receiverRoutes } from './webhook-receiver-route'; @@ -40,13 +39,13 @@ export function webhookReceiver<P extends JsonValue = JsonValue>( definition: WebhookReceiverDefinition<P>, ): WebhookReceiver { const maxBytes = assertReceiver(definition); - const handle = job<WebhookReceiverInput>({ + const handle = factoryJob<WebhookReceiverInput>({ name: definition.name, input, // `eventId` alone: the namespace is already (name, tenant, key), so one vendor event is one row. idempotencyKey: ({ eventId }) => eventId, tenant: tenantOf(definition), - retry: definition.retry ?? DEFAULT_RETRY, + retry: definition.retry, ...(definition.queue === undefined ? {} : { queue: definition.queue }), run: ({ input: row, ctx, step, attempt }) => definition.handle({ diff --git a/packages/jobs/src/webhook.ts b/packages/jobs/src/webhook.ts index fcb89379c..0382ecf9f 100644 --- a/packages/jobs/src/webhook.ts +++ b/packages/jobs/src/webhook.ts @@ -32,9 +32,8 @@ import type { DurationInput } from './clock'; import { nowMs } from './clock'; import { JobTenantMismatchError } from './errors-tenant'; import type { JobHandle } from './job'; -import { job } from './job'; +import { factoryJob } from './job'; import type { RetryPolicy } from './retry'; -import { DEFAULT_RETRY } from './retry'; import type { JobTenant } from './tenant'; import type { Outcome, WebhookFetch } from './webhook-attempt'; import { attemptDelivery, deliveryError, deliverySignal } from './webhook-attempt'; @@ -202,14 +201,14 @@ export function webhook(definition: WebhookDefinition): JobHandle<WebhookDeliver definition.fetch ?? ((url, init) => fetch(url, { ...init, signal: init.signal ?? null })); // Named so `run` can read the deadline `job()` resolved — one parse of `timeout`, never two. - const handle: JobHandle<WebhookDeliveryInput> = job<WebhookDeliveryInput>({ + const handle: JobHandle<WebhookDeliveryInput> = factoryJob<WebhookDeliveryInput>({ name: definition.name, input: t.object({ endpointId: t.string, eventId: t.string, orgId: t.optional(t.string) }), // Endpoint AND event: the same event fans out to every subscribed endpoint, so a key on the // event alone would dedupe every one of those deliveries into the first endpoint's row. idempotencyKey: ({ endpointId, eventId }) => `${definition.name}:${endpointId}:${eventId}`, tenant: tenantOf(definition), - retry: definition.retry ?? DEFAULT_RETRY, + retry: definition.retry, ...(definition.queue === undefined ? {} : { queue: definition.queue }), ...(definition.timeout === undefined ? {} : { timeout: definition.timeout }), async run({ input, ctx, attempt }): Promise<WebhookReport> { diff --git a/packages/jobs/src/worker-admit.test.ts b/packages/jobs/src/worker-admit.test.ts index 31f72c4cb..d85d7f61f 100644 --- a/packages/jobs/src/worker-admit.test.ts +++ b/packages/jobs/src/worker-admit.test.ts @@ -3,8 +3,9 @@ // lease lapsed, an attempt spent on a body that never started, and on the final attempt the claim // dead-lettered it. What is proven: it goes back with the jobs behind it, uncounted. -import { describe, expect, test } from 'bun:test'; -import { ctxOf } from '@ultimat3/core'; +import { afterEach, describe, expect, mock, spyOn, test } from 'bun:test'; +import { ctxOf, frozenClock, logger } from '@ultimat3/core'; +import { nowMs } from './clock'; import type { ClaimedJob, JobDriver } from './driver'; import { memoryJobDriver } from './driver-memory'; import { concurrencyLimiter } from './limits'; @@ -49,6 +50,10 @@ async function claimedPair() { return { driver, claimed, rows }; } +afterEach(() => { + mock.restore(); +}); + const slots = (grant: SlotGrant): FleetSlots => ({ acquire: () => Promise.resolve(grant), startRenewal: () => () => undefined, @@ -62,7 +67,7 @@ async function admitRejects( if (job === undefined) return expect.unreachable('nothing was claimed'); let thrown: unknown; try { - await admit(job, 'default', () => behind); + await admit(job, 'default', () => behind, nowMs()); } catch (error) { thrown = error; } @@ -82,6 +87,7 @@ describe('a shed whose nack fails hands the job back with the rest', () => { fleetSlots: slots({ outcome: 'granted' }), workerId: 'w1', pollIntervalMs: 25, + visibilityTimeoutMs: 30_000, context: () => ctxOf(), }); @@ -101,6 +107,7 @@ describe('a shed whose nack fails hands the job back with the rest', () => { fleetSlots: slots({ outcome: 'wait', limit: 1, key: undefined }), workerId: 'w1', pollIntervalMs: 25, + visibilityTimeoutMs: 30_000, context: () => ctxOf(), }); @@ -112,3 +119,62 @@ describe('a shed whose nack fails hands the job back with the rest', () => { } }); }); + +describe('a run admitted after its claim window', () => { + test('is handed back as a shed: no lost lease, no settle failure, the slot given back', async () => { + const clock = frozenClock('2026-11-19T00:00:00.000Z'); + const driver = memoryJobDriver({ clock }); + await driver.enqueue({ + name: 'late', + queue: 'default', + input: {}, + idempotencyKey: 'late:1', + maxAttempts: 3, + }); + const askedAt = clock.now().getTime(); + const [job] = await driver.claim({ + queues: ['default'], + limit: 1, + visibilityTimeoutMs: 30_000, + workerId: 'w1', + }); + if (job === undefined) return expect.unreachable('nothing was claimed'); + const released: string[] = []; + const admit = createAdmission({ + driver, + limiter: concurrencyLimiter({}), + // The slot write of a slow store: the batch's tail is admitted past its whole window. + fleetSlots: { + acquire: () => { + clock.advance(30_000); + return Promise.resolve({ outcome: 'granted' }); + }, + startRenewal: () => () => undefined, + release: (jobId) => { + released.push(jobId); + return Promise.resolve(); + }, + }, + workerId: 'w1', + pollIntervalMs: 25, + visibilityTimeoutMs: 30_000, + clock, + context: () => ctxOf(), + }); + const debug = spyOn(logger, 'debug').mockImplementation(() => undefined); + const error = spyOn(logger, 'error').mockImplementation(() => undefined); + const admission = await admit(job, 'default', () => [], askedAt); + + // Before: admitted as a run, its heartbeat reported `jobs.lease.lost` (counted: "may run + // twice") and the round logged `jobs.worker.settle-failed` for a body that never started. + expect(admission.kind).toBe('waiting'); + expect(released).toEqual([job.id]); + expect(debug.mock.calls.filter(([message]) => message === 'jobs.worker.shed')).toEqual([ + ['jobs.worker.shed', expect.objectContaining({ jobId: job.id, reason: 'admitted-late' })], + ]); + expect(error).not.toHaveBeenCalled(); + const row = await driver.introspect?.job(job.id); + expect(row?.state).toBe('ready'); + expect(row?.attempt).toBe(0); + }); +}); diff --git a/packages/jobs/src/worker-admit.ts b/packages/jobs/src/worker-admit.ts index fbd3f4886..a6c665012 100644 --- a/packages/jobs/src/worker-admit.ts +++ b/packages/jobs/src/worker-admit.ts @@ -5,6 +5,7 @@ import type { Clock, Ctx } from '@ultimat3/core'; import { logger } from '@ultimat3/core'; +import { nowMs } from './clock'; import type { ClaimedJob, JobDriver } from './driver'; import { claimOf } from './driver'; import type { JobExecution } from './execute-result'; @@ -19,6 +20,8 @@ export interface AdmissionOptions { readonly fleetSlots: FleetSlots; readonly workerId: string; readonly pollIntervalMs: number; + /** The claim's lease window: a job admitted past it is shed, never run (`admitted-late`). */ + readonly visibilityTimeoutMs: number; readonly clock?: Clock; /** `WorkerOptions.context` — a refused run's `onSettled` is scoped from it. */ readonly context: () => Ctx; @@ -37,15 +40,17 @@ export type Admission = /** * `behind` is the rest of the claimed batch: handed back before a store failure is rethrown. A * thunk, read only on that failure: a slice per admitted job made a batch O(batch²) to admit. + * `askedAt` is when the claim was asked, on `clock` — where the lease's window starts. */ export type Admit = ( job: ClaimedJob, queue: string, behind: () => readonly ClaimedJob[], + askedAt: number, ) => Promise<Admission>; export function createAdmission(options: AdmissionOptions): Admit { - const { driver, limiter, fleetSlots, workerId, pollIntervalMs } = options; + const { driver, limiter, fleetSlots, workerId, pollIntervalMs, visibilityTimeoutMs } = options; const back = { delayMs: pollIntervalMs, workerId }; /** @@ -70,7 +75,24 @@ export function createAdmission(options: AdmissionOptions): Admit { }); }; - return async (job, queue, behind) => { + /** + * Admission (a slow store's fleet-slot writes, one per job ahead in the batch) outlasted the + * claim's whole window: the queue may already have handed the row on. Not a lost lease — no body + * started here, so `jobs.lease.lost` ("this job may now run twice") and a settle failure would + * both be false — but a shed: back uncounted, fenced on the claim, so a re-claimed row ignores it. + */ + const late = (askedAt: number): boolean => nowMs(options.clock) - askedAt >= visibilityTimeoutMs; + + return async (job, queue, behind, askedAt) => { + if (late(askedAt)) { + try { + await shed(job, queue, 'admitted-late'); + } catch (error) { + await handBack(driver, [job, ...behind()], back); + throw error; + } + return { kind: 'waiting' }; + } const key = { queue, ...(job.tenantId === undefined ? {} : { tenantId: job.tenantId }) }; const lease = limiter.tryAcquire(key); if (lease === undefined) { @@ -107,10 +129,24 @@ export function createAdmission(options: AdmissionOptions): Admit { await handBack(driver, [job, ...behind()], back); throw error; } - if (grant.outcome === 'granted') return { kind: 'run', lease }; - // A key that could not be derived RUNS — into `executeJob`'s failure path, which raises the - // refusal before the body: it fails as an attempt, never as a round. - if (grant.outcome === 'undecidable') return { kind: 'run', lease, refusal: grant.error }; + if (grant.outcome === 'granted' || grant.outcome === 'undecidable') { + // The slot write is where the time goes: asked again past it. + if (late(askedAt)) { + lease.abandon(); + try { + await fleetSlots.release(job.id); + await shed(job, queue, 'admitted-late'); + } catch (error) { + await handBack(driver, [job, ...behind()], back); + throw error; + } + return { kind: 'waiting' }; + } + // A key that could not be derived RUNS — into `executeJob`'s failure path, which raises the + // refusal before the body: it fails as an attempt, never as a round. + if (grant.outcome === 'undecidable') return { kind: 'run', lease, refusal: grant.error }; + return { kind: 'run', lease }; + } // Over the fleet cap, so this run does not start: `abandon`, never `release`, or a tenant // waiting behind a full `job.concurrency` pays one `ratePerTenant` start per poll interval. diff --git a/packages/jobs/src/worker-drain-cutoff.test.ts b/packages/jobs/src/worker-drain-cutoff.test.ts new file mode 100644 index 000000000..aa0336aa4 --- /dev/null +++ b/packages/jobs/src/worker-drain-cutoff.test.ts @@ -0,0 +1,26 @@ +// The cut-off's arithmetic: measured back from where core's in-flight wait ends +// (`ShutdownReason.inflightUntil`), so a job told to stop has the margin to unwind before that wait +// gives up — never the same instant, which a nack's round trip loses (`X_SHUTDOWN_TIMEOUT`, exit 70). + +import { describe, expect, test } from 'bun:test'; +import { cutoffTimes, DRAIN_CANCEL_MARGIN_MS } from './worker-drain-cutoff'; + +describe('cutoffTimes', () => { + test('with no in-flight end, the margin is measured back from the deadline', () => { + expect(cutoffTimes(10_000, 0)).toEqual({ cancelAt: 8_000, handBackAt: 9_000 }); + }); + + test('the hand-back lands a margin before the in-flight wait ends, not at it', () => { + const times = cutoffTimes(10_000, 0, 8_000); + expect(times).toEqual({ cancelAt: 6_000, handBackAt: 7_000 }); + expect(8_000 - times.cancelAt).toBe(DRAIN_CANCEL_MARGIN_MS); + }); + + test('a small budget still keeps half of what is left before the wait ends', () => { + expect(cutoffTimes(300, 0, 240)).toEqual({ cancelAt: 120, handBackAt: 180 }); + }); + + test('an in-flight end past the deadline is the deadline', () => { + expect(cutoffTimes(10_000, 0, 12_000)).toEqual(cutoffTimes(10_000, 0)); + }); +}); diff --git a/packages/jobs/src/worker-drain-cutoff.ts b/packages/jobs/src/worker-drain-cutoff.ts index a1ef9dbc8..6f85fb2eb 100644 --- a/packages/jobs/src/worker-drain-cutoff.ts +++ b/packages/jobs/src/worker-drain-cutoff.ts @@ -23,11 +23,21 @@ export interface CutoffTimes { readonly handBackAt: number; } -/** The cut-off for a deadline, read against the instant it was bound. */ -export function cutoffTimes(deadlineAt: number, now: number): CutoffTimes { - const remaining = Math.max(0, deadlineAt - now); +/** + * The cut-off for a deadline, read against the instant it was bound. Measured back from + * `inflightUntil` — core's `ShutdownReason.inflightUntil`, the instant its in-flight wait ends — + * and not from `deadlineAt`: a cancel at the very instant that wait gives up loses the race to a + * nack that takes one round trip, and the drain exits `X_SHUTDOWN_TIMEOUT` for a job it handed back. + */ +export function cutoffTimes( + deadlineAt: number, + now: number, + inflightUntil: number = deadlineAt, +): CutoffTimes { + const end = Math.min(deadlineAt, inflightUntil); + const remaining = Math.max(0, end - now); const margin = Math.min(DRAIN_CANCEL_MARGIN_MS, remaining / 2); - return { cancelAt: deadlineAt - margin, handBackAt: deadlineAt - margin / 2 }; + return { cancelAt: end - margin, handBackAt: end - margin / 2 }; } export interface DrainCutoff { @@ -43,6 +53,8 @@ export interface DrainCutoff { export function armDrainCutoff( budget: DrainBudget, steps: { readonly cancel: () => void; readonly handBack: () => Promise<void> }, + /** How far before the deadline the drain's in-flight wait ends: `deadlineAt − inflightUntil`. */ + reserveMs = 0, ): DrainCutoff { const timers: ReturnType<typeof setTimeout>[] = []; let cancelled = false; @@ -58,7 +70,7 @@ export function armDrainCutoff( }; const unwatch = budget.watch((deadlineAt) => { clear(); - const times = cutoffTimes(deadlineAt, systemClock.monotonic()); + const times = cutoffTimes(deadlineAt, systemClock.monotonic(), deadlineAt - reserveMs); if (!cancelled) { at(times.cancelAt, () => { cancelled = true; @@ -96,16 +108,23 @@ export function armWorkerCutoff(input: { readonly signal: string; readonly drain: AbortController; readonly held: HeldRuns; + /** `deadlineAt − inflightUntil` of the shutdown that armed it (`cutoffTimes`). */ + readonly reserveMs: number; }): DrainCutoff { const { workerId, held } = input; - return armDrainCutoff(input.budget, { - cancel: () => { - if (held.size > 0) logger.warn('jobs.worker.drain-cancelling', { workerId, held: held.size }); - input.drain.abort(new JobDrainedError({ workerId, signal: input.signal })); + return armDrainCutoff( + input.budget, + { + cancel: () => { + if (held.size > 0) + logger.warn('jobs.worker.drain-cancelling', { workerId, held: held.size }); + input.drain.abort(new JobDrainedError({ workerId, signal: input.signal })); + }, + handBack: async () => { + const handed = await held.handBackAll(); + if (handed > 0) logger.warn('jobs.worker.drain-handed-back', { workerId, handed }); + }, }, - handBack: async () => { - const handed = await held.handBackAll(); - if (handed > 0) logger.warn('jobs.worker.drain-handed-back', { workerId, handed }); - }, - }); + input.reserveMs, + ); } diff --git a/packages/jobs/src/worker-drain-finish.test.ts b/packages/jobs/src/worker-drain-finish.test.ts index a9c759a30..6a4bd39db 100644 --- a/packages/jobs/src/worker-drain-finish.test.ts +++ b/packages/jobs/src/worker-drain-finish.test.ts @@ -12,6 +12,8 @@ import { configureLifecycle, ctxOf, drain, + drainExitCode, + installLogSink, isUltimateError, resetLifecycle, systemClock, @@ -256,6 +258,54 @@ describe('SIGTERM stops claiming and lets running jobs finish', () => { expect(rec.queueAtClose()?.dead).toBe(0); expect((await worker.stats()).interrupted).toBe(1); }); + + test('a job cut at the drain cut-off with a driver that takes a round trip drains with exit code 0 and no X_SHUTDOWN_TIMEOUT', async () => { + // 10 s: core keeps its full 2 s reserve, the size at which the in-flight wait used to end at + // the very instant the cut-off fired, and a nack that needs one round trip lost the race. + configureLifecycle({ deadlineMs: 10_000 }); + const lines: string[] = []; + const release = installLogSink((line) => { + lines.push(line); + }); + const base = memoryJobDriver(); + let atClose: QueueStats | undefined; + const driver: JobDriver = { + ...base, + async nack(jobId: string, options: NackOptions): Promise<boolean> { + await time.sleep(5); + return base.nack(jobId, options); + }, + async close(): Promise<void> { + [atClose] = await base.stats(); + }, + }; + const started = latch(); + job<{ n: number }>({ + tenant: 'none', + name: 'roundTrip', + input: passthrough<{ n: number }>(), + idempotencyKey: ({ n }) => `roundTrip:${n}`, + retry: { attempts: 1, jitter: 'none' }, + run: async ({ ctx }) => { + started.arrive(); + await sleepUnless(60_000, ctx.signal); + }, + }); + await enqueueOne(driver, 'roundTrip'); + const worker = jobWorker({ driver, context, pollIntervalMs: 1 }); + worker.start(); + try { + await time.settles(started.reached, 100); + await time.settles(drain('SIGTERM'), 12_000, 50); + } finally { + release(); + } + + expect(lines.filter((line) => line.includes('X_SHUTDOWN_TIMEOUT'))).toEqual([]); + expect(drainExitCode()).toBe(0); + expect((await worker.stats()).interrupted).toBe(1); + expect(atClose?.ready).toBe(1); + }); }); describe('a claim still held at the cut-off goes back to the queue before the driver closes', () => { diff --git a/packages/jobs/src/worker-drain-signal.test.ts b/packages/jobs/src/worker-drain-signal.test.ts index ccf6779e1..7a276e1a0 100644 --- a/packages/jobs/src/worker-drain-signal.test.ts +++ b/packages/jobs/src/worker-drain-signal.test.ts @@ -111,6 +111,11 @@ async function rig(after: (ctx: Ctx) => void | Promise<void>): Promise<Rig> { /** Small, so the cut-off — half of it, for a budget this size — lands inside a test's patience. */ const DEADLINE_MS = 300; +/** + * Where core's in-flight wait ends: a fifth of the budget is its hooks' reserve, and the cut-off + * measures back from that instant (`ShutdownReason.inflightUntil`), not from the deadline. + */ +const INFLIGHT_UNTIL_MS = DEADLINE_MS - DEADLINE_MS / 5; beforeEach(() => { resetLifecycle(); @@ -136,7 +141,7 @@ describe('the cut-off aborts the signal of every job the worker still holds', () // the wall clock — a loaded CI runner measured 325.8 ms against the 300 ms budget (#663) — and // none is needed: "finished, not abandoned at the deadline" is `processed: 1` below, since an // abandoned run is handed back and never counted. - expect(tookMs).toBeGreaterThanOrEqual(DEADLINE_MS / 2 - 5); + expect(tookMs).toBeGreaterThanOrEqual(INFLIGHT_UNTIL_MS / 2 - 5); const stats = await app.worker.stats(); expect(stats.state).toBe('stopped'); expect(stats.processed).toBe(1); diff --git a/packages/jobs/src/worker.ts b/packages/jobs/src/worker.ts index 125172602..4c75256dd 100644 --- a/packages/jobs/src/worker.ts +++ b/packages/jobs/src/worker.ts @@ -70,6 +70,7 @@ export function jobWorker(options: WorkerOptions): Worker { fleetSlots, workerId, pollIntervalMs, + visibilityTimeoutMs, context: options.context, ...(options.clock === undefined ? {} : { clock: options.clock }), }); @@ -171,7 +172,7 @@ export function jobWorker(options: WorkerOptions): Worker { for (const [index, job] of claimed.entries()) { const queue = job.queue; // Both caps, and what becomes of a job that passes neither — `worker-admit.ts`. - const admission = await admit(job, queue, () => claimed.slice(index + 1)); + const admission = await admit(job, queue, () => claimed.slice(index + 1), askedAt); if (admission.kind === 'waiting') continue; if (admission.kind === 'refused') { // Settled without a body: counted and returned with the pass, the one job this loop @@ -343,6 +344,8 @@ export function jobWorker(options: WorkerOptions): Worker { signal: shutdown.signal, drain: drainSignal, held: inFlight, + // Core owns the instant its in-flight wait ends; the cut-off lands a margin before it. + reserveMs: Math.max(0, shutdown.deadlineAt - (shutdown.inflightUntil ?? shutdown.deadlineAt)), }); }; diff --git a/packages/mcp/src/readonly-sql-forbidden-calls.test.ts b/packages/mcp/src/readonly-sql-forbidden-calls.test.ts index a50793329..93b23015b 100644 --- a/packages/mcp/src/readonly-sql-forbidden-calls.test.ts +++ b/packages/mcp/src/readonly-sql-forbidden-calls.test.ts @@ -89,6 +89,10 @@ describe('a call that mutates the server, the queue or the replication stream is // Postgres' own synonym: the plan is executed under either spelling. 'explain analyse select 1', 'explain (analyse) select 1', + // A quoted option name is the same option: Postgres folds nothing inside quotes, and + // `analyze` is already lower case. + 'explain ("analyze") select 1', + 'explain (verbose, "analyse" true) select 1', "select pg_copy_logical_replication_slot('a', 'b')", "select pg_copy_physical_replication_slot('a', 'b')", 'select pg_sync_replication_slots()', diff --git a/packages/mcp/src/readonly-sql.ts b/packages/mcp/src/readonly-sql.ts index dd4ee5723..b190f6638 100644 --- a/packages/mcp/src/readonly-sql.ts +++ b/packages/mcp/src/readonly-sql.ts @@ -123,6 +123,18 @@ export function assertReadOnlyQuery(sql: string): string { ); } } + // `explain ("analyze")` is `explain (analyze)`: the option list names options, and a quoted + // name is the same option — so it is read in the form that keeps identifier content. Only the + // option list: a column quoted as `"analyze"` elsewhere is a column. + if ( + leader === 'explain' && + explainOptions(stripLiteralsAndComments(sql, 'keep')).some(ANALYZES) + ) { + throw rejected( + 'the statement contains the mutating keyword "analyze" as a quoted EXPLAIN option', + 'SELECT * FROM <table> LIMIT 10 -- or EXPLAIN with no ANALYZE: db.query never executes the plan it describes', + ); + } // A family refuses a CALL, never a bare word: scanning every word rejected a column named // `pg_sleep_for_seconds`, and scanning the blanked form missed `"pg_advisory_lock"(1)`, which // is the same call wearing quotes. So this pass reads the form that keeps identifier content. @@ -149,6 +161,14 @@ export function assertReadOnlyQuery(sql: string): string { return verbatim(sql); } +const ANALYZES = (word: string): boolean => word === 'analyze' || word === 'analyse'; + +/** The words of `explain ( … )`'s option list, lower-cased; none when it has no list. */ +function explainOptions(kept: string): readonly string[] { + const list = /^\s*explain\s*\(([^)]*)\)/i.exec(kept)?.[1] ?? ''; + return list.toLowerCase().match(WORD) ?? []; +} + /** * The caller's bytes, minus surrounding whitespace and one trailing `;`. Anything past that * semicolon is whitespace or a comment — the single-statement check above already proved the diff --git a/packages/query/src/record-answer.test.ts b/packages/query/src/record-answer.test.ts index 8dbfc9c62..7bc03e72c 100644 --- a/packages/query/src/record-answer.test.ts +++ b/packages/query/src/record-answer.test.ts @@ -4,20 +4,23 @@ import { afterAll, describe, expect, test } from 'bun:test'; import { + DATES_HEADER, decodeRecordEnvelope, + installLogSink, RECORDS_HEADER, RECORDS_OPENAPI_HEADER, recordEnvelopeSchema, + wireDatePaths, } from '@ultimat3/core'; import { clearRegistry, entity, integer, text, uuid } from '@ultimat3/entity'; -import { defineHttpConfig, httpServer } from '@ultimat3/http'; +import { defineHttpConfig, httpServer, WIRE_DATES_MAX_BYTES } from '@ultimat3/http'; import { allow } from '@ultimat3/policy'; import { t, toWireOutputSchema } from '@ultimat3/schema'; import { toQueryRoute } from './http'; import { toQueryOpenApiOperation } from './openapi'; import type { AnyQuery } from './query'; import { query } from './query'; -import { recordAnswerFor } from './record-answer'; +import { recordAnswerFor, recordRowAnswerFor } from './record-answer'; import { from } from './source'; const ORG = '00000000-0000-4000-8000-000000000001'; @@ -187,3 +190,69 @@ describe('the record envelope in the OpenAPI document', () => { } }); }); + +// A `string | Date` column shares one pattern between text and an instant, so no path folds: one +// exact path per instant made the header as long as the answer, and a default nginx refuses a +// response whose headers outgrow its buffer. Past the cap there is no header at all. +describe('x-ultimate-dates stays under the header cap', () => { + const AT = new Date('2026-03-04T05:06:07.089Z'); + type Mixed = { readonly orgId: string; readonly id: string; readonly value: string | Date }; + const mixed = (instants: number): readonly Mixed[] => + Array.from({ length: instants * 2 }, (_, index) => ({ + orgId: ORG, + id: String(index).padStart(6, '0'), + value: index % 2 === 0 ? `label-${index}` : AT, + })); + const series = (rows: readonly Mixed[]): AnyQuery => + query({ + input: Input, + policy: allow('public'), + sql: ({ orgId }) => from<Mixed>('points', rows).where({ orgId }).orderBy('id'), + }).named('recordFeed'); + const logged = async (run: () => Promise<void>): Promise<readonly string[]> => { + const lines: string[] = []; + const release = installLogSink((line) => void lines.push(line)); + try { + await run(); + } finally { + release(); + } + return lines.filter((line) => line.includes('http.wire_dates_dropped')); + }; + + test('past the cap a read carries no header, the body unchanged, one warn per query', async () => { + const rows = mixed(2_000); + expect(wireDatePaths(rows)?.length).toBeGreaterThan(WIRE_DATES_MAX_BYTES); + const lines = await logged(async () => { + for (let call = 0; call < 2; call += 1) { + const response = await read(series(rows)); + expect(response.status).toBe(200); + expect(response.headers.get(DATES_HEADER)).toBeNull(); + expect(await response.text()).toBe(JSON.stringify(rows)); + } + }); + expect(lines).toHaveLength(1); + expect(JSON.parse(lines[0] ?? '{}')).toMatchObject({ operation: 'recordFeed', paths: 2_000 }); + }); + + test('under the cap the same shape names every instant', async () => { + const rows = mixed(10); + const header = (await read(series(rows))).headers.get(DATES_HEADER); + expect(header).toBe(wireDatePaths(rows) ?? null); + expect(header?.length).toBeLessThanOrEqual(WIRE_DATES_MAX_BYTES); + }); + + test('the envelope and the single row follow the same cap', () => { + const wide = { ...ROW_A, points: mixed(2_000) }; + for (const response of [ + recordAnswerFor(Post.$schema)([wide]), + recordRowAnswerFor(Post.$schema)(wide), + recordRowAnswerFor(undefined)(wide), + ]) { + expect(response.headers.get(DATES_HEADER)).toBeNull(); + } + expect(recordAnswerFor(Post.$schema)([wide]).headers.get(RECORDS_HEADER)).toBe('1'); + const small = { ...ROW_A, at: AT }; + expect(recordRowAnswerFor(Post.$schema)(small).headers.get(DATES_HEADER)).not.toBeNull(); + }); +}); diff --git a/packages/query/src/record-answer.ts b/packages/query/src/record-answer.ts index 8894d0f37..30e2fbfd7 100644 --- a/packages/query/src/record-answer.ts +++ b/packages/query/src/record-answer.ts @@ -9,9 +9,9 @@ */ import type { RecordRows, Row } from '@ultimat3/core'; -import { DATES_HEADER, encodeRecordEnvelope, RECORDS_HEADER, wireDatePaths } from '@ultimat3/core'; +import { DATES_HEADER, encodeRecordEnvelope, RECORDS_HEADER } from '@ultimat3/core'; import { hasEntityRows, rowsOf } from '@ultimat3/entity'; -import { jsonResponse } from '@ultimat3/http'; +import { cappedWireDates, jsonResponse } from '@ultimat3/http'; import type { StandardSchemaV1 } from '@ultimat3/schema'; import type { Page } from './pagination'; @@ -37,9 +37,11 @@ export function recordAnswerFor(rows: StandardSchemaV1 | undefined): RecordAnswe * The instants of a read's DATA — the rows, the `Page` or the one row — by path * (`@ultimat3/core`'s `wire-dates.ts`), so the typed client hands back the `Date` the row type * promises. A header, never the body: the body and the OpenAPI document stay what they were. + * Capped (`cappedWireDates`, 4 KB — `@ultimat3/action`'s `record-wire.ts` follows the same rule): + * an answer needing one path per instant past that sends NO header and is logged once per query. */ function datesOf(data: unknown): { readonly headers: Record<string, string> } { - const dates = wireDatePaths(data); + const dates = cappedWireDates(data); return { headers: dates === undefined ? {} : { [DATES_HEADER]: dates } }; } diff --git a/packages/realtime/src/channel-logs.ts b/packages/realtime/src/channel-logs.ts index 1ca027d02..e6e31931a 100644 --- a/packages/realtime/src/channel-logs.ts +++ b/packages/realtime/src/channel-logs.ts @@ -10,7 +10,7 @@ import { renderRecords } from './channel-render'; import { ChannelRing, type RecordsEntry } from './channel-ring'; import { type Audience, admitsTenant, rowTenant } from './channel-tenant'; import type { ChannelSince, ReplayGapFrame } from './channel-wire'; -import { deliverRecordsTo, type SocketRegistry, type SyncSocket } from './socket'; +import type { SocketRegistry, SyncSocket } from './socket'; import { PROTOCOL_VERSION } from './sync-protocol'; /** What a joined topic resolves to. A topic is `name.params…`, so it names both exactly. */ @@ -92,10 +92,7 @@ export class ChannelLogs { admits: (actor) => admitsTenant(actor, tenant), withheld: renderRecords(update.topic, epoch, withheld(entry)), }; - frames += - audience === undefined - ? this.#sockets.deliverRecords(update.topic, epoch, frame) - : deliverRecordsTo(this.#sockets, update.topic, epoch, frame, audience); + frames += this.#sockets.deliverRecords(update.topic, epoch, frame, audience); } return frames; } diff --git a/packages/realtime/src/channel-tenant.ts b/packages/realtime/src/channel-tenant.ts index a4efebdb0..9c082794b 100644 --- a/packages/realtime/src/channel-tenant.ts +++ b/packages/realtime/src/channel-tenant.ts @@ -8,7 +8,6 @@ import { tenantColumnOfTable, tenantIn } from './change-tenant'; import type { Channel } from './channel-decl'; import type { ChannelRecordsFrame } from './channel-wire'; import { isTenancyDenial, TopicForbiddenError } from './errors'; -import type { SocketRegistry } from './socket'; /** * A row is routed to the topic its own params name (`channel-records.ts`), so a topic keyed by the @@ -93,12 +92,3 @@ export interface Audience { readonly admits: (actor: Actor | null) => boolean; readonly withheld: ChannelRecordsFrame; } - -/** `socket.ts`'s `deliverRecordsTo`: one records frame to a topic's members, scoped by `to`. */ -export type DeliverRecordsTo = ( - registry: SocketRegistry, - topic: string, - epoch: string, - frame: ChannelRecordsFrame, - to: Audience, -) => number; diff --git a/packages/realtime/src/fanout.ts b/packages/realtime/src/fanout.ts index 163845630..9e5025da8 100644 --- a/packages/realtime/src/fanout.ts +++ b/packages/realtime/src/fanout.ts @@ -184,11 +184,6 @@ export class InProcessTransport implements Transport { return this.#handlers.size; } - /** Keys `shared` holds, emptied ones included: the in-process read a leak test needs. */ - get sharedKeys(): number { - return this.#set.size; - } - #assertOpen(): void { if (this.#closed) { throw new TransportUnavailableError({ transport: this.name, reason: 'transport is closed' }); @@ -196,5 +191,12 @@ export class InProcessTransport implements Transport { } } +/** + * Keys `transport.shared` holds, emptied ones included: the in-process read a leak test needs. A + * module function, never a member — no caller of the public class has a use for it. + */ +export const inProcessKeyCount = (transport: InProcessTransport): number => + transport.shared instanceof InProcessSet ? transport.shared.size : 0; + // The production bus lives in `nats-transport.ts`: it needs a socket, a codec and a JetStream // client, none of which belong in the file that defines what a transport *is*. diff --git a/packages/realtime/src/presence.test.ts b/packages/realtime/src/presence.test.ts index 079bc8c89..f97dd1bda 100644 --- a/packages/realtime/src/presence.test.ts +++ b/packages/realtime/src/presence.test.ts @@ -2,7 +2,7 @@ import { describe, expect, test } from 'bun:test'; import { frozenClock } from '@ultimat3/core'; import { topic } from './channel'; import { readPresence } from './channel-presence'; -import { InProcessTransport, type Transport } from './fanout'; +import { InProcessTransport, inProcessKeyCount, type Transport } from './fanout'; import { PRESENCE_KEY_PREFIX, PRESENCE_SWEEP_PREFIX, PresenceRegistry } from './presence'; const room = topic('org', 'o1', 'cursors'); @@ -50,14 +50,14 @@ describe('presence', () => { await presence.join(topic('org', 'o1', `room-${i}`), { id: `m${i}`, actorId: 'alice' }); } await presence.sweepAll(); - expect(transport.sharedKeys).toBeGreaterThan(0); + expect(inProcessKeyCount(transport)).toBeGreaterThan(0); clock.advance(31_000); // The pass that announces the leaves forgets each room. Its sweep lease outlives the room by // one TTL — a follower reads the last roster off it — and is then gone with nobody reading it. expect(await presence.sweepAll()).toHaveLength(3); clock.advance(31_000); await presence.join(topic('org', 'o1', 'next'), { id: 'm9', actorId: 'bob' }); - expect(transport.sharedKeys).toBe(1); + expect(inProcessKeyCount(transport)).toBe(1); }); test('a sweep turns silent expiry into explicit leave events', async () => { diff --git a/packages/realtime/src/socket.ts b/packages/realtime/src/socket.ts index 65c61c67b..e362bf966 100644 --- a/packages/realtime/src/socket.ts +++ b/packages/realtime/src/socket.ts @@ -17,7 +17,7 @@ import { uuidV7, } from '@ultimat3/core'; import { channelFramesDropped, GapRepairs } from './channel-gaps'; -import type { Audience, DeliverRecordsTo } from './channel-tenant'; +import type { Audience } from './channel-tenant'; import type { ChannelRecordsFrame } from './channel-wire'; import { CLOSE } from './close-codes'; import { DropWindow } from './socket-drops'; @@ -78,12 +78,6 @@ import { DEFAULT_MAX_FRAMES_PER_SECOND, } from './socket-defaults'; -/** - * `deliverRecords` to an `Audience`. A function rather than a parameter: `SocketRegistry` is public - * API, and a changed member signature is a break (`scripts/public-api.ts`). Set by the class below. - */ -export let deliverRecordsTo: DeliverRecordsTo; - export function actorIdOf(actor: Actor | null): string | null { return actor === null ? null : actor.id; } @@ -416,19 +410,10 @@ export class SocketRegistry { /** * A `records` delivery. An owed `replay-gap` goes out first; a socket that then drops the frame is - * marked for the next one. `deliver`'s twin, because only a records stream can be repaired. + * marked for the next one. `deliver`'s twin, because only a records stream can be repaired. A + * member `to` does not admit is sent `to.withheld` instead (`channel-tenant.ts`). */ - deliverRecords(topic: string, epoch: string, frame: ChannelRecordsFrame): number { - return this.#records(topic, epoch, frame, undefined); - } - - static { - deliverRecordsTo = (registry, topic, epoch, frame, to) => - registry.#records(topic, epoch, frame, to); - } - - /** A member `to` does not admit is sent `to.withheld` instead (`channel-tenant.ts`). */ - #records(topic: string, epoch: string, frame: ChannelRecordsFrame, to?: Audience): number { + deliverRecords(topic: string, epoch: string, frame: ChannelRecordsFrame, to?: Audience): number { const members = this.#byTopic.get(topic); if (!members) return 0; const text = encode(frame); diff --git a/packages/ui/src/hotkeys-view.test.ts b/packages/ui/src/hotkeys-view.test.ts index 58903990a..d4223022e 100644 --- a/packages/ui/src/hotkeys-view.test.ts +++ b/packages/ui/src/hotkeys-view.test.ts @@ -60,7 +60,10 @@ describe('hotkeyAction', () => { expect(label(hotkeyAction(key('?', { isComposing: true }), other, table))).toBeUndefined(); expect( label(hotkeyAction(key('k', { ctrlKey: true, isComposing: true }), other, table)), - ).toBeUndefined(); + ).toBeUndefined(); // Safari's confirming Enter arrives after `compositionend`: only keyCode 229 says so. + expect(label(hotkeyAction(key('?', { keyCode: 229 }), other, table))).toBeUndefined(); + expect(label(hotkeyAction(key('Process'), other, table))).toBeUndefined(); + expect(label(hotkeyAction(key('?', { keyCode: 191 }), other, table))).toBe('sheet'); }); test('mod+k needs the platform modifier, and fires while typing', () => { diff --git a/packages/ui/src/hotkeys-view.ts b/packages/ui/src/hotkeys-view.ts index 6ec2869cd..def7379af 100644 --- a/packages/ui/src/hotkeys-view.ts +++ b/packages/ui/src/hotkeys-view.ts @@ -2,6 +2,7 @@ // never with a modifier, a two-key chord inside one window, and `mod+` that fires anywhere. Pure, // so `useHotkeys` and `ShortcutSheet` read ONE table and the binding and its legend cannot drift. +import { isComposingKey } from './composing-key'; import { invalidValueError } from './errors'; /** One shortcut: the bindings that run it, its already-translated legend line, and the work. */ @@ -27,6 +28,8 @@ export interface HotkeyKeyEvent { readonly metaKey: boolean; readonly altKey: boolean; readonly isComposing: boolean; + /** Legacy `keyCode`: Safari's IME-confirming Enter says 229 and nothing else (`composing-key.ts`). */ + readonly keyCode?: number; readonly editable: boolean; /** `event.timeStamp` — monotonic, which is all the chord window compares. */ readonly at: number; @@ -108,7 +111,7 @@ export function hotkeyAction( table: CompiledHotkeys, ): HotkeyAnswer { // An IME is mid-word: every key belongs to the composition, not the page. - if (event.isComposing || event.key === 'Process') return { row: undefined, state }; + if (isComposingKey(event)) return { row: undefined, state }; const mod = state.mac ? event.metaKey : event.ctrlKey; const otherMod = state.mac ? event.ctrlKey : event.metaKey; if (mod && !otherMod && !event.altKey) { diff --git a/packages/ui/src/use-hotkeys.ts b/packages/ui/src/use-hotkeys.ts index 50197d846..9c116ce0b 100644 --- a/packages/ui/src/use-hotkeys.ts +++ b/packages/ui/src/use-hotkeys.ts @@ -61,6 +61,7 @@ function slotOf(host: HotkeyHost, mac: boolean): HotkeySlot { metaKey: event.metaKey, altKey: event.altKey, isComposing: event.isComposing === true, + keyCode: event.keyCode, editable: editableTarget(event.target), at: event.timeStamp, }, diff --git a/scripts/lib/public-api-compat.test.ts b/scripts/lib/public-api-compat.test.ts index 6f6d80b34..13b130b45 100644 --- a/scripts/lib/public-api-compat.test.ts +++ b/scripts/lib/public-api-compat.test.ts @@ -226,6 +226,28 @@ describe('public-api-compat · values and classes, read by callers', () => { 'break: member `a` was removed', ); }); + + const REG = 'class R { send ( topic : string , frame : F ) : number ; }'; + const sent = (params: string, returns = 'number'): string => + `class R { send ( ${params} ) : ${returns} ; }`; + + test('a method that gained optional trailing parameters is compatible, as a function is', () => { + expect(verdict(REG, sent('topic : string , frame : F , to ? : A'))).toBe( + 'compatible: optional trailing parameter(s) added to `send`', + ); + expect(verdict(REG, sent('topic : string , frame : F , to ? : A , at ? : number'))).toBe( + 'compatible: optional trailing parameter(s) added to `send`', + ); + }); + + test('a method that needs more, takes less, narrows a parameter or answers otherwise breaks', () => { + const changed = 'break: member `send` changed its type'; + expect(verdict(REG, sent('topic : string , frame : F , to : A'))).toBe(changed); + expect(verdict(REG, sent('topic : string , frame : F , to : A , at ? : number'))).toBe(changed); + expect(verdict(REG, sent('topic : string'))).toBe(changed); + expect(verdict(REG, sent('topic : "a" , frame : F , to ? : A'))).toBe(changed); + expect(verdict(REG, sent('topic : string , frame : F , to ? : A', 'string'))).toBe(changed); + }); }); describe('public-api-compat · object-literal parameters', () => { diff --git a/scripts/lib/public-api-compat.ts b/scripts/lib/public-api-compat.ts index 0538270a5..8692b42ea 100644 --- a/scripts/lib/public-api-compat.ts +++ b/scripts/lib/public-api-compat.ts @@ -31,24 +31,32 @@ function literals(was: readonly string[], now: readonly string[]): ApiChange { /** * Members of something callers only READ — a `const`'s object type, a class instance: any new - * member is compatible, required or not. Removed, retyped, or made optional is a break. + * member is compatible, required or not. Removed, retyped, or made optional is a break — except a + * method whose recorded code is its current one minus optional trailing parameters (`shorter`): + * every call it took still compiles, the rule `params()` gives a function. */ function readOnly( was: Readonly<Record<string, MemberCode>>, now: Readonly<Record<string, MemberCode>>, + shorter: Readonly<Record<string, readonly MemberCode[]>> = {}, ): ApiChange { + const grown: string[] = []; for (const [name, code] of Object.entries(was)) { const next = own(now, name); if (next === undefined) return breaks(`member \`${name}\` was removed`); - if (bare(code) !== bare(next)) return breaks(`member \`${name}\` changed its type`); + if (bare(code) !== bare(next)) { + if (!own(shorter, name)?.includes(code)) return breaks(`member \`${name}\` changed its type`); + grown.push(`optional trailing parameter(s) added to \`${name}\``); + } if (!optional(code) && optional(next)) return breaks(`member \`${name}\` became optional`); } const added = Object.keys(now).filter((name) => own(was, name) === undefined); - return compatible( - added.length === 0 - ? 'members reordered or re-spelt only' - : `${added.map((name) => `\`${name}\``).join(', ')} added to a value callers only read`, - ); + if (added.length > 0) { + grown.push( + `${added.map((name) => `\`${name}\``).join(', ')} added to a value callers only read`, + ); + } + return compatible(grown.length === 0 ? 'members reordered or re-spelt only' : grown.join('; ')); } /** A class: its instance read-only, its constructor an input. `implements` of one is not expected. */ @@ -56,7 +64,7 @@ function classChange( was: Extract<ApiShape, { kind: 'class' }>, now: Extract<ApiShape, { kind: 'class' }>, ): ApiChange { - const read = readOnly(was.members, now.members); + const read = readOnly(was.members, now.members, now.shorter); if (read.kind === 'break') return read; if (was.ctor === undefined && now.ctor === undefined) return read; if (was.ctor === undefined || now.ctor === undefined) { diff --git a/scripts/lib/public-api-shape-kinds.ts b/scripts/lib/public-api-shape-kinds.ts index b0813eb0f..7478b0c60 100644 --- a/scripts/lib/public-api-shape-kinds.ts +++ b/scripts/lib/public-api-shape-kinds.ts @@ -76,6 +76,11 @@ export type ApiShape = readonly members: Readonly<Record<string, MemberCode>>; /** The one declared constructor's parameters; absent when it declares none or several. */ readonly ctor?: readonly ParamCode[]; + /** + * A single-signature method's codes with its trailing optional parameters dropped, one by one: + * what it was if those were added since. The tree's side only — `shapeBody` never writes it. + */ + readonly shorter?: Readonly<Record<string, readonly MemberCode[]>>; } | { /** Anything else: judged by its own text, and by the shapes of the locals it names. */ @@ -161,6 +166,22 @@ export function constObjectOf(words: readonly string[], locals: string): ApiShap const ACCESS = new Set(['static', 'protected', 'abstract']); +/** `name ( … ) : R` / `name ? < T > ( … ) : R` → the codes it has without each optional tail. */ +function withoutOptionalTail(rest: readonly string[]): MemberCode[] { + let open = rest[1] === '?' ? 2 : 1; + if (rest[open] === '<') open = closing(rest, open) + 1; + const close = rest[open] === '(' ? closing(rest, open) : -1; + if (close === -1) return []; + const params = splitAt(rest.slice(open + 1, close), ','); + const codes: MemberCode[] = []; + for (let keep = params.length - 1; keep >= 0; keep -= 1) { + if (!paramOf(params[keep] ?? []).startsWith('?')) break; + const kept = params.slice(0, keep).flatMap((param, at) => (at === 0 ? param : [',', ...param])); + codes.push(memberOf([...rest.slice(0, open + 1), ...kept, ...rest.slice(close)])[1]); + } + return codes; +} + /** `class X … { … }`: members keyed `static x` / `x`, private dropped, the constructor apart. */ export function classOf(words: readonly string[], locals: string): ApiShape | undefined { const at = words[0] === 'abstract' ? 1 : 0; @@ -169,6 +190,7 @@ export function classOf(words: readonly string[], locals: string): ApiShape | un if (open === -1 || closing(words, open) !== words.length - 1) return undefined; const members: (readonly [string, MemberCode])[] = []; const ctors: ParamCode[][] = []; + const shorter = new Map<string, MemberCode[]>(); for (const member of splitAt(words.slice(open + 1, -1), ';')) { const prefix = member.filter((word, index) => index < 3 && ACCESS.has(word)); const rest = member.slice(prefix.length); @@ -178,13 +200,18 @@ export function classOf(words: readonly string[], locals: string): ApiShape | un continue; } const [key, code] = memberOf(rest); - members.push([prefix.includes('static') ? `static ${key}` : key, code]); + const name = prefix.includes('static') ? `static ${key}` : key; + // An overload set's code is all of its signatures: no one shorter form is what it was. + shorter.set(name, members.some(([one]) => one === name) ? [] : withoutOptionalTail(rest)); + members.push([name, code]); } const [ctor] = ctors; + const methods = [...shorter].filter(([, codes]) => codes.length > 0); return { kind: 'class', head: shortDigest([words.slice(0, open).join(' '), locals].join('\n')), members: groupMembers(members), ...(ctors.length === 1 && ctor !== undefined ? { ctor } : {}), + ...(methods.length === 0 ? {} : { shorter: Object.fromEntries(methods) }), }; } From 47129f474254b5546d7ac26300bfb370bbeaa84d Mon Sep 17 00:00:00 2001 From: sebi <gore.sebyx@yahoo.com> Date: Thu, 19 Nov 2026 13:58:22 -0500 Subject: [PATCH 7/9] wip: r9 final integration --- CHANGELOG.md | 53 ++++++++++--- docs/history/cli-file-map.md | 12 +++ docs/history/core-rules.md | 4 + docs/history/http.md | 2 +- docs/history/jobs-rules.md | 7 ++ framework.manifest.json | 7 +- packages/cache/CLAUDE.md | 3 +- packages/cache/src/index.ts | 8 +- packages/cache/src/lru.ts | 9 +-- packages/cache/src/purge-cloudflare.ts | 2 +- packages/cache/src/purge-fastly.ts | 2 +- packages/cache/src/redis.ts | 9 +-- packages/cache/src/semantic.ts | 5 +- packages/cache/src/tier-bounds.ts | 70 +++++++++++++++++ packages/cache/src/tiers.ts | 67 +---------------- packages/cli/CLAUDE.md | 15 ++-- packages/cli/README.md | 1 + packages/cli/src/cmd-tasks-run.test.ts | 22 +++++- packages/cli/src/cmd-tasks-run.ts | 36 ++++++--- packages/cli/src/cmd-tasks-spec.ts | 3 +- packages/cli/src/db-rollback-pass.test.ts | 50 +++++++++++++ packages/cli/src/db-rollback-pass.ts | 4 +- packages/cli/src/error-codes.ts | 2 + packages/cli/src/job-budget.test.ts | 16 ++-- packages/cli/src/job-budget.ts | 6 +- packages/cli/src/mcp-errors.ts | 4 + .../cli/src/serve-graph-ceilings-fixture.ts | 11 ++- .../serve-graph-serving-ceiling-fixture.ts | 11 ++- .../src/serve-graph-web-ceiling-fixture.ts | 6 +- packages/core/CLAUDE.md | 6 +- packages/core/README.md | 5 +- packages/core/package.json | 1 + packages/core/src/client-stream.test.ts | 3 +- packages/core/src/client-stream.ts | 32 +------- packages/core/src/config-defaults.ts | 7 +- packages/core/src/config-jobs.ts | 7 ++ packages/core/src/drain-deadline.test.ts | 9 +++ packages/core/src/drain-deadline.ts | 9 +++ packages/core/src/framework-env.ts | 1 + packages/core/src/index.ts | 2 + packages/core/src/lifecycle.ts | 4 +- packages/core/src/sse-frames.ts | 42 +++++++++++ packages/http/CLAUDE.md | 5 +- packages/jobs/CLAUDE.md | 5 +- packages/jobs/src/retry-core-parity.test.ts | 14 +++- packages/jobs/src/retry-default.ts | 4 +- packages/jobs/src/retry.ts | 4 +- packages/jobs/src/worker-drain-cutoff.ts | 18 +++-- packages/jobs/src/worker.ts | 7 +- packages/mcp/src/remote-wire.test.ts | 49 ++++++++++++ packages/mcp/src/remote-wire.ts | 21 ++---- packages/notify/src/notifier.ts | 1 + packages/scraping/src/scrape.ts | 1 + scripts/lib/finite-screens.ts | 10 ++- scripts/lib/public-api.lock.json | 34 ++++++--- scripts/primitive-factories.test.ts | 75 ++++++++++++++++++- scripts/template-codemods-rows.ts | 7 +- tsconfig.base.json | 2 + wiki/Actions.md | 2 +- wiki/Agents.md | 2 +- wiki/Auth.md | 4 +- wiki/CLI-Reference.md | 6 +- wiki/Caching-And-Invalidation.md | 2 +- wiki/Configuration.md | 2 +- wiki/Deployment.md | 2 +- wiki/Error-Codes-cli.md | 1 + wiki/Error-Codes.md | 3 +- wiki/Queries-And-Live-Queries.md | 2 +- wiki/Scheduled-Tasks.md | 2 +- wiki/Upgrading.md | 8 +- 70 files changed, 626 insertions(+), 242 deletions(-) create mode 100644 packages/cache/src/tier-bounds.ts create mode 100644 packages/cli/src/db-rollback-pass.test.ts create mode 100644 packages/core/src/sse-frames.ts create mode 100644 packages/mcp/src/remote-wire.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 0d3c0db5d..40631d28c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,21 +22,27 @@ Semver applies from 1.0.0. A breaking change to a documented API needs a major - auth: `oauthLogin(auth, { mfaPath })` and `identityProviderRoutes(auth, { providers, mfaPath })` let an MFA-enrolled user finish SSO through the built-in routes: the callback answers 303 to the app's second-factor page with the sealed challenge in an `HttpOnly` `__Host-x_mfa` cookie. On that page, `completeMfa(auth, readMfaChallenge(request) ?? '', code)`, then send `clearMfaChallengeCookie()` — both new exports of `@ultimat3/auth`. An `mfaPath` that is not one absolute path on this origin is `X_CONFIG_INVALID` at the call. Without `mfaPath` the callback is the same 401 `X_MFA_REQUIRED`, and its logged fix now names the option. - jobs: `startQueueWake({ reproveEveryMs })` (default 10 s) re-proves a proven cross-process wake; `installDefaultRetry` / `resetDefaultRetry` / `DefaultRetry` on `@ultimat3/jobs/adapter` install the retry of a job that declares none (the boot does it from `jobs.maxAttempts` / `jobs.backoff`). -- http: `isCallerAbort` and `reportLateFault(error, ctx?)` are exported from `@ultimat3/http`: the second runs the `error-map` stage's monitor, `onError` and log line for a fault after the response started, once per request. -- entity: `memoryTxOpen(tx)` — whether a memory transaction's root is still open. +- http: `reportLateFault(error, ctx?)` is exported from `@ultimat3/http`: it runs the `error-map` stage's monitor, `onError` and log line for a fault after the response started, once per request; a caller's hang-up records nothing and leaves the one report unspent. +- http: `cappedWireDates` and `WIRE_DATES_MAX_BYTES` (4,096): the `x-ultimate-dates` value an answer carries, or none past the cap. - ai: `GenerateRequest.toolChoice?: 'auto'` (optional) leaves a request's single tool unforced; compaction's summary call sets it. - auth: `AuthServerClient.host` — a metadata-document client's `client_id` host, beside the `name` its document chose; show it on the consent page. - jobs/redis: `redisJobDriver({ deadTtlMs })` — how long failed, dead and expired rows are kept (default 90 days, pg's `jobs.deadRetentionMs`; `0` keeps them forever). - testing: `authServerStoreConformance` checks that `purge` deletes a self-registered client past the idle window that nothing names, and only it. - `x db rollback [--steps n]` reverses the most recently applied migration(s), most recently applied first, by running each file's `-- down` half; the files stay, so each is pending again (`x db migrate` re-applies). Beside an `x dev` on the embedded database it is run by that dev server (`POST /_x/db/rollback`). A file with no `-- down` marker is `X_MIGRATION_IRREVERSIBLE`; outside development and test it is refused `X_MIGRATION_ROLLBACK_DESTRUCTIVE` until `ROLLBACK_ALLOW_DESTRUCTIVE` names every migration it would reverse. `--json`: `{ reverted, steps, files }`. - db: `rollback({ confirm })` is called once, under the migrate lock and before the first `down`, with the exact ledger rows about to be reversed; a throw reverses nothing. -- `x tasks run <name>` fires a scheduled task now — its jobs onto the app's queue through `TaskHandle.enqueue()`, the scheduler's watermark untouched — with `--json`; refused where the environment resolves `production` without `--production`, and beside an `x dev` holding the embedded database. `x g cron-job` names it as its next step. +- `x tasks run <name>` fires a scheduled task now — its jobs onto the app's queue through `TaskHandle.enqueue()`, the scheduler's watermark untouched — with `--json`; where the environment resolves `production` it fires only when asked by name, `--production` or (a container whose command line is fixed) `ULTIMATE_TASK_RUN=<name>`, else `X_TASK_RUN_PRODUCTION` with nothing queued — `x db seed`'s gate and refusal form; beside an `x dev` holding the embedded database it is refused. `x g cron-job` names it as its next step. - `x policy explain <subject> --input '<json>'` evaluates the policy on a request's input, for a rule whose predicate reads one; the value is never echoed. - `x docs <topic-id>` — the id every search line starts with — prints that topic's body: a package guide's whole section, or a module's header comment and exports. A search ends with that command for its first hit. - `x new` declares `@ultimat3/realtime` at the exact framework pin, so `useQuery` / `channel()` resolve on a fresh app and `x doctor` stays green; an older app adds it with `bun add --exact` at its `@ultimat3/core` pin ([Realtime](wiki/Realtime.md)). -- `x errors explain <CODE>` answers an app's own `defineError()` codes inside the app: title, cause, fix, status and the declaring `file:line`. +- `x errors explain <CODE>` answers an app's own `defineError()` codes inside the app, from the error registry: title, HTTP status and the declaring `file:line` (`--json`: `{ code, title, docs, status, site }`). - `x doctor` warns (`X_ACTION_UNREGISTERED` / `X_QUERY_UNREGISTERED`, never a failure) on an action or query left off an app's `defineApi()` that lists others, with the import line that lists it; an app registering by the module scan alone is told nothing. - jobs README: "One job per org, from a schedule" — a `tenant: 'none'` `cronJob()` listing orgs inside `crossTenant()` and enqueueing one tenant-scoped job per org, its fence run by a test. +- auth: `mfaChallengeOf`, `mfaChallengeCookie` and `MFA_CHALLENGE_COOKIE` — the write half of the MFA challenge cookie, beside `readMfaChallenge` / `clearMfaChallengeCookie`. +- action: `acceptedIdOf(record)` on `@ultimat3/action/adapter` — the id `batchedAuditSink` minted for a record, for a custom sink's idempotent insert. +- core: `JOBS_MAX_ATTEMPTS_DEFAULT` (3), the one statement of the default retry attempts: `jobs.maxAttempts`' default and `DEFAULT_RETRY.attempts` both read it; `laterHooksReserveMs(deadlineMs)`, the drain's reserve for the hooks behind the in-flight wait; `ShutdownReason.inflightUntil`, the instant that wait ends. +- cache: `CacheTier.scope?` names which entries a tier's bust clears (`redisTier` sets its `x:<APP_VERSION>` namespace); `InvalidationBroadcast` receives the sender's scopes as an optional second argument (type `SharedTierScopes`). +- ui: `HotkeyKeyEvent.keyCode?` (optional). +- realtime: `SocketRegistry.deliverRecords(topic, epoch, frame, to?)` takes the tenant audience as an optional trailing parameter. ### Changed - `cache.defaultTtlMs` now sets the lease of a value cached with no `ttlMs` on the `lru` and `redis` rungs the boot builds. It was validated and documented and read by nothing; a boot-built Redis rung held such values 300 s, now the configured 60 s by default. A rung supplied through `cacheTiers` keeps its own default (#1260). @@ -49,7 +55,7 @@ Semver applies from 1.0.0. A breaking change to a documented API needs a major - `x db gen` runs one at a time per checkout; its success line names the tables, and "no migration needed" names the migration that already records them. - The test step line reads `ran 2 at once (peak), planned 3`, or `1 worker, one per file (plan: …)`, in place of `2 of 4 of 6 workers`. - A doctor probe that throws is an `X_DOCTOR_PROBE_FAILED` finding, never a crash whose fix is the doctor itself. -- `jobs.maxAttempts` and `jobs.backoff` are read: the attempts of a job that declares no `retry` (a factory's whose `retry` was omitted: `purge()`, `backfill()`, `rollup()`, …), and the curve of any `retry` naming no `backoff`. Installed by the boot in every role, so the enqueuing process stamps the same `max_attempts` the worker retries by. `jobs.maxAttempts` now defaults to `3`, not the documented `5`: the key was read by nothing, and 3 is the retry such a job always had. With neither key set nothing moves. **Upgrading:** an app that set either key gets it applied now — `grep -n 'maxAttempts\|backoff' app.config.ts` and keep the value only if it is the retry you want for every job declaring none. +- `jobs.maxAttempts` and `jobs.backoff` are read: the attempts of a job that declares no `retry` (a factory's whose `retry` was omitted: `purge()`, `backfill()`, `rollup()`, …), and the curve of any `retry` naming no `backoff`. Installed by `startQueue`, the boot every entry point shares — every role, `x tasks run`, `x jobs` and `x db backfill` — so the enqueuing process stamps the same `max_attempts` the worker retries by. `jobs.maxAttempts` now defaults to `3`, not the documented `5`: the key was read by nothing, and 3 is the retry such a job always had. With neither key set nothing moves. **Upgrading:** an app that set either key gets it applied now — `grep -n 'maxAttempts\|backoff' app.config.ts` and keep the value only if it is the retry you want for every job declaring none. - `cache.defaultTtlMs: 0` is refused by `defineConfig` (`X_CONFIG_INVALID`) instead of crashing the boot; the minimum is 1, and a value that is not a whole number ≥ 1 refuses the boot naming `cache.defaultTtlMs`. **Upgrading:** an app writing `0` sets a positive lease. - core: `directionOf` / `isRtl` read an explicit script subtag first (`az-Arab` is `rtl`, `ks-Deva` `ltr`), and bare `ku` is now `ltr` (Kurmanji, Latin script). **Upgrading:** an app serving Kurdish in Arabic script under `ku` renames the locale `ku-Arab` or `ckb`, or its pages render `dir="ltr"`. - `database.ssl: true` now requires TLS (`sslmode=require`) on the pool every boot opens — serving roles, `x dev`, the migrate step, `x db status`/`recount`/`diagnostics`, primary and replica — unless the URL (`sslmode` or `ssl`) or `PGSSLMODE` states a mode — and on every other pool the framework opens: the replicator's `DATABASE_URL` and `REPLICATION_URL` sessions, `x doctor`'s database probes, `x db branch` and `x deploy verify`'s queue read. It was validated and read by nothing. `PGSSLMODE` is a declared framework env name. **Upgrading:** an app with `ssl: true` whose `DATABASE_URL` states no mode, against a Postgres without TLS, no longer connects: set `database: { ssl: false }`, or put `?sslmode=disable` in that URL. @@ -60,16 +66,16 @@ Semver applies from 1.0.0. A breaking change to a documented API needs a major - http: outside dev, an unclassified 5xx whose `code` is not framework-shaped (`X_…`) and not declared — a driver's SQLSTATE (`23505`), `ENOENT`, an app's own `E_UPSTREAM` — is served as `X_INTERNAL` in `code`, `type`, the hidden `fix` and the HTML error page. **Upgrading:** a client that switches on a non-`X_` code from a 5xx needs that code declared — `defineError` or `registerErrorStatus({ E_UPSTREAM: 502 })` — `grep -rn "code: '[A-Z]" apps packages | grep -v "'X_"` lists the candidates. A declared code, and dev, are unchanged. - http: a caller that hangs up mid-request is answered `499 X_ABORTED`, logged at `info`, not sent to the monitor and not counted as a 5xx; `hooks.onError` receives the coded `X_ABORTED`, not the raw `AbortError`. A library's own wrapped abort stays a reported 500. **Upgrading:** a dashboard or alert on `http.server.request` 5xx volume drops by the hang-ups; an `onError` that matched `name === 'AbortError'` matches `code === 'X_ABORTED'`. -- http: `ctx.peer` is `null` for an `x-forwarded-client-cert` with an unbalanced quote (it was one merged element), and a `\` outside quotes no longer hides a separator. +- http: `ctx.peer` reads `x-forwarded-client-cert` from the right, parsing only the elements the trusted hops appended: a client prefix with an unbalanced quote no longer nulls the peer, and a trusted element holding a `"` that is not a whole-value quote (`URI=spiffe://a/b"c`) is no peer. **Upgrading:** an Envoy front quotes whole values, so nothing moves; a proxy that writes bare quotes inside a value shows `ctx.peer === null` — check it in staging. - http: the request deadline bounds time-to-headers; once a streamed answer has started only the caller going away fires `ctx.signal`. **Upgrading:** a streamed agent answer that relied on `requestTimeoutMs` to end it bounds itself: `withChildContext({ signal: AbortSignal.timeout(ms) }, …)`. - action: SSE `chunk` frames carry an optional `dates:` line (a reader that does not know it ignores it); `hooks.onError` and the `error-map` log line now fire for a streamed action's fault after the first chunk, 4xx included (4xx: sink and log only). - core: `defineConfig` refuses a non-boolean `pwa.enabled`, `pwa.backgroundSync` or `pwa.push` (`'false'` turned the PWA **on**), checked even when `enabled` is false; a non-list `pwa.categories`, a non-string `pwa.offline.neverCache` entry, a non-list `pwa.shortcuts` / `pwa.screenshots` and a non-string `site.favicon` are `X_CONFIG_INVALID` too. **Upgrading:** `grep -n "enabled\|backgroundSync\|push" app.config.ts` in the `pwa` block: each is `true` or `false`, never a string or a number. - core: `clientTransport` sends a write with no idempotency key **once**, whatever the flight's retry policy (a gateway 5xx re-sent it). `rpc`, the outbox and storage are already keyed or single-shot. **Upgrading:** a direct `clientTransport({ method: 'POST', flight, retry })` that relied on a retry passes an `idempotencyKey`. -- core: `drain()` keeps min(2 s, `deadlineMs` / 5) of its budget for the `inflight` / `close` hooks when in-flight work overruns, so the in-flight wait ends that much earlier; the total stays within `deadlineMs`. -- core: the Sentry transport drops reports during a 429's `Retry-After` pause (60 s when unstated) and warns once per refused status; `X_ERROR_REPORTER_DSN_INVALID`'s `meta.dsn` holds the DSN without its userinfo. +- core: `drain()` keeps min(2 s, `deadlineMs` / 5) of its budget for the `inflight` / `close` hooks when in-flight work overruns, so the in-flight wait ends that much earlier; the total stays within `deadlineMs`. The instant is handed to every hook as `ShutdownReason.inflightUntil`, and the jobs worker's drain cut-off measures back from it, so a job cut at the cut-off drains with exit 0 (it raced the wait's end to `X_SHUTDOWN_TIMEOUT`, exit 70). **Upgrading:** `x verify`'s `X_JOB_OUTLASTS_DRAIN` (retire off) grades against that earlier cancel — 21 s of a 25 s `drain.deadlineMs`, was 23 s; a job whose `timeout` sits between them now reds `manifest`: raise `drain.workerRetireMs` or lower the `timeout`. +- core: the Sentry transport drops reports during a 429's `Retry-After` pause (60 s when unstated) and warns once per refused status; `X_ERROR_REPORTER_DSN_INVALID`'s `meta.dsn` holds the DSN without its userinfo, and a DSN that is not an http(s) URL (a legacy `key:secret@host/1`) is described, never echoed. - jobs/redis: failed, dead and expired rows, their steps and debounce fences **expire after 90 days by default**; `stats()` no longer counts `failed`/`dead` members past the window. **Upgrading:** an app on `redisJobDriver()` that reads old dead rows for audit passes `redisJobDriver({ deadTtlMs: 0 })` to keep them forever, or exports them first. - jobs/redis: with no `clock` injected, leases, retries, settle debts and gauges are measured on the **Redis server's clock** (`TIME`); `claimedAt`, `visibleAt` and `updatedAt` are server times and a nack's `runAt` is server now plus the delay, as on pg. **Upgrading:** a test that freezes time (`installClock`, the preload's `Date`) against a real Redis driver passes `redisJobDriver({ clock })` to keep the frozen clock in charge. -- jobs: a claimed job whose admission took the whole visibility window is handed back without running its body (`X_JOB_LEASE_LOST`, `jobs.lease.lost`); one admitted an interval or more late heartbeats at once. +- jobs: a claimed job whose admission took the whole visibility window is handed back uncounted as a debug shed (`jobs.worker.shed`, `reason: 'admitted-late'`) without running its body — no `jobs.lease.lost`, no `job_leases_lost_total`, no `jobs.worker.settle-failed`; one admitted an interval or more late heartbeats at once. **Upgrading:** an alert on `job_leases_lost_total` no longer fires for a slow admission. - ai: `postgresVectorStore()`'s lexical leg (`searchText`, `hybrid`) matches **any** word of the query, as `memoryVectorStore()` does, and reads no query syntax: `"quoted phrase"`, `-word` and `or` are plain text. **Upgrading:** a caller that passed websearch syntax to exclude or quote drops it; expect more lexical candidates per query. - ai: `anthropicProvider()` sends `strict: true` only for a schema inside the Messages API's strict subset and under its per-request caps — nearly every tool with a string loses the flag on that wire (those requests were 400s). The output schema still validates. - ai: `defineEval` refuses a `tolerance` that is not finite or is negative (`X_INVARIANT`). **Upgrading:** `grep -rn 'tolerance' apps packages` — each a number ≥ 0. @@ -106,6 +112,18 @@ Semver applies from 1.0.0. A breaking change to a documented API needs a major - `X_ENV_MISSING`'s `fix:` is the line to add, in the file the environment loads (`echo 'STRIPE_KEY=<value>' >> .env.development.local`; `.env.test.local` under test, `.env.production` for a deploy), and a malformed key's is `grep -n -e '^KEY=' .env*` — no longer `x env check`, which printed the same error. **Upgrading:** anything matching the old fix text exactly matches the new. - `x docs <query>` prints one extra closing line naming the first hit's topic command, and a query that is exactly a topic id answers that topic alone instead of a ranked search. - An unknown subcommand with no near match answers `x help <command>` (that command's own subcommands), not `x help`; a mistyped generator keeps the name and slice you typed (`x g acton foo` → `x g action foo`). +- cache: during a rolling deploy, a write on one build also clears the other build's shared Redis tier: the invalidation broadcast names the namespace its own bust cleared, and a receiver skips its shared tier only when that namespace is its own. Old and new pods read each other's frames (an older frame names no scope and busts every tier). **Upgrading:** a custom `InvalidationBroadcast` callback still type-checks; nothing to change. +- cache: a refused delete's re-join is `ZADD … GT`, so it never lowers a later fill's bucket score. **Upgrading:** Redis ≥ 6.2 (Valkey, Dragonfly included); an older server refuses it only on the already-partial refused-`UNLINK` path, reported in the bust's failures. +- action, query, http: `x-ultimate-dates` (and a streamed frame's `dates:` line) is capped at 4,096 bytes (`WIRE_DATES_MAX_BYTES`); an answer needing more carries none, the client reads those instants as ISO strings, and the operation is logged once at `warn` (`http.wire_dates_dropped`). A proxy with a default header buffer no longer answers 502. **Upgrading:** an answer with ~100+ instants that cannot fold (a `[label, instant]` tuple, a `string | Date` column) reaches the client as strings: `grep` the logs for `http.wire_dates_dropped`. +- `x db rollback` needs `ROLLBACK_ALLOW_DESTRUCTIVE` naming each id against an external database that is not on this machine, whatever `ULTIMATE_ENV` says, and on any named deploy (`staging`, `production`, `NODE_ENV=production`). **Upgrading:** a script rolling back a remote database from a shell that names no environment (a compose service host like `db` included) sets `ROLLBACK_ALLOW_DESTRUCTIVE=<id,…>`. +- `x dev` runs only the roles `app.config.ts`'s `roles` declares, when set, and logs the ones it left out; `x dev --role` naming only undeclared roles is `X_CONFIG_INVALID`. **Upgrading:** an app declaring `roles` lists every role it wants `x dev` to run. +- `startQueue` loads `app.config.ts` on every boot, embedded included. **Upgrading:** a command that boots the queue against an invalid config now refuses `X_CONFIG_INVALID`; `x verify --only manifest` shows the same. +- A scheduled occurrence that one fan-out entry cannot queue (its `tenant()` throws or answers empty) queues nothing, logs `jobs.scheduler.entry-refused` naming the task, job and entry, and is retried each tick until repaired, then queued whole. **Upgrading:** alert on `jobs.scheduler.entry-refused`. +- `database.ssl: true` requires TLS on a URL carrying an empty `?sslmode=` / `?ssl=` (it fell back to plaintext), and an upper-case `?SSLMODE=disable` is the operator's and no longer overridden. **Upgrading:** a deployment that relied on the empty value against a non-TLS server states `?sslmode=disable`. +- `x g sign-in --password` holds its second-factor challenge in auth's `__Host-x_mfa` cookie (`mfaChallengeCookie`), as the OIDC shape does, in place of its own `x_mfa_challenge`. **Upgrading:** an app generated before keeps its own `sign-in-challenge.ts` and cookie unchanged; the new shape's `__Host-` cookie needs HTTPS or `localhost`. +- entity: `gt`/`gte`/`lt`/`lte` on a `uuid()` column with an operand that is not a uuid is `X_INVARIANT_VIOLATED` on both drivers (Postgres answered `22P02`, memory compared the text). **Upgrading:** a memory-driver test relying on text order for such a bound passes a uuid. +- ai: compaction's carried user text is one `KEPT_USER_CHARS` (8,000) budget across ALL compactions, newest kept first; the summary note says how many blocks it carried. **Upgrading:** nothing; a long `.continue()` chat no longer grows its head until `X_AGENT_CONTEXT_EXHAUSTED`. +- `X_FORBIDDEN`'s fix names `--input '<the request input as JSON>'` at all four throw sites, so the command it gives can decide a predicate that reads the request; the request's own input is never printed. **Upgrading:** a test asserting the old `fix:` text updates it. ### Fixed - `bun run preflight` and `bun run coverage` stopped by a signal kill the suites they started, so no orphan keeps its ledger reservation. @@ -147,7 +165,7 @@ Semver applies from 1.0.0. A breaking change to a documented API needs a major - query: a deprecated download query's mint is counted in `deprecated_calls_total`. - db: `rollback()` reverses the most recently applied migration (`applied_at`), not the highest id; a branch merged late is undone first instead of the previous release's migration. - cache: Redis tier: a fill landing mid-bust could be left in no tag bucket and serve stale for its whole TTL; a bust now sweeps buckets before deleting values, and re-joins any member whose `UNLINK` was refused. -- cache: an inbound invalidation broadcast no longer re-busts the shared Redis tier on every replica, which deleted freshly refilled values and cost an extra load per mutation. +- cache: an inbound invalidation broadcast from the same build no longer re-busts the shared Redis tier on every replica, which deleted freshly refilled values and cost an extra load per mutation. - cache: `memorySemanticCache` hits are no longer the writer's live object. - cache: the `X_CACHE_LIMIT_INVALID` fix for `defaultTtlMs` names `cache.defaultTtlMs` in `app.config.ts`. - entity: a malformed uuid in `eq`/`neq`/`in`, `findById`, `update` or `delete` is "no such row" on Postgres as on memory, never `22P02`; every uuid spelling Postgres parses is one value in both drivers. An app test that asserts the Postgres driver's SQL text through a fake client with non-uuid ids on uuid columns now sees `1 = 0`. @@ -167,7 +185,7 @@ Semver applies from 1.0.0. A breaking change to a documented API needs a major - ci: `release-tag`'s queue moved onto the cut job, so a non-release CI completion can no longer cancel a pending release. - scripts: `config-readers` counts only a qualified read, not a bare property name. - http: a handler that settles just after the request deadline can no longer replace the 504: the answer is the deadline race's winner only, so a late fallback never leaves without security headers, request id or cookies; a stream the orphan built is cancelled. -- http: `x-forwarded-client-cert` — a backslash escapes only inside quotes and an unterminated quote yields no peer, so client-written text cannot move the trusted hop index onto its own element. +- http (security): `ctx.peer` reads `x-forwarded-client-cert` from the right, only the elements the trusted hops appended — a quote or backslash the client wrote before them can no longer merge elements and name the peer (`URI=…;X="` ahead of a proxy element whose Subject escapes a quote). - action: a streamed action's `chunk` frames carry a `dates:` line, so instants in a chunk revive as `Date` like the `done` frame's. - action: a group-commit audit batch that commits but loses its reply no longer stores every record twice: each accepted write keeps one row id through the single retry, and both `x_audit` inserts skip a row already stored with identical facts. A different row under the same id still fails with `unique_violation`. `memoryAuditSink` behind `batchedAuditSink` keeps such a record once. - core: `outbound()` — a call cancelled by its own `signal` neither retries nor spends the breaker key's retry budget (six cancels emptied it); a 3xx whose `Location` does not parse is `X_OUTBOUND_REDIRECTED` after one attempt (was `X_OUTBOUND_UNREACHABLE`, retried 3×). @@ -181,7 +199,7 @@ Semver applies from 1.0.0. A breaking change to a documented API needs a major - ai: `openAiProvider()` no longer claims `strict` for a schema with an optional key inside an `anyOf` branch. - ai: a whitespace-only assistant text is no longer replayed by `agent()` or `llm()`'s repair turn. - ai: an agent offering no tools of its own can compact on the chat-completions wire: the summary call is no longer forced through `respond`. -- ai: compaction keeps what the user said in the summarised turns (a `.continue()` instruction) verbatim in the first message, up to 8,000 characters, newest first, and no longer deletes a prompt block that merely starts with `[compacted:`. +- ai: compaction keeps what the user said in the summarised turns (a `.continue()` instruction) verbatim in the first message, up to 8,000 characters in total across every compaction, newest first, and no longer deletes a prompt block that merely starts with `[compacted:`. - ai: non-finite or negative usage from an app-written `Provider` no longer poisons the budget counter; the reservation's estimate stands and `ai.budget.usage_invalid` is logged. - ai: `chunkDocument` never returns a chunk over `size`. - db: a read carrying a `minPosition` no longer waits on a parked replica: it goes straight to the primary, with no statement sent to the standby. @@ -204,6 +222,17 @@ Semver applies from 1.0.0. A breaking change to a documented API needs a major - `X_BOUNDARY_SITE_TO_APP` is one finding per crossing import, at the file that crosses: a `site/` page importing an `app/` query no longer also reports that query's own `app/ → app/` imports (its policy, its repo) as edges to delete, in `x verify` and in `x fix boundary`. - `x errors explain X_TENANCY_UNSCOPED` prints the fix for the code's general cause (run inside a context whose actor carries the org) instead of the upsert's `onConflict` fix. - `X_CATALOG_MISSING_KEYS`'s fix comment, from the CLI, says what `x i18n sync <locale>` writes for that locale: `⟦key⟧` in the default locale, `⟦the default locale's string⟧` in any other, and the generated label for a mounted admin's keys. +- A deploy that cuts a running job at the drain cut-off exits 0 again, not 70 with `X_SHUTDOWN_TIMEOUT`. +- `x tasks run`, `x jobs` and `x db backfill` stamp the app's `jobs.maxAttempts` / `jobs.backoff` on what they enqueue (they stamped the framework's 3). +- `x db gen`: dropping a column that a partial index's predicate, an expression index or an `include` list reads restores that index in the drop's own `down` and emits no follow-up step (the follow-up's `down` failed 42703 on rollback). +- action: when the single retry after a lost batch reply draws `unique_violation`, `postgresAuditSink` re-sends it once. +- entity: a batched point read whose bisected half fails for its own reason (a pool timeout, a failover) reports that reason, not the other id's "invalid input syntax". +- i18n: `catalogSubset` lists a translator's keys once; a subset no longer scans the whole catalog per call. +- ui: hotkeys ignore Safari's IME-confirming Enter (`keyCode 229`), like every other field that owns Enter. +- mcp: `db.query` refuses `explain ("analyze") …`, the quoted option form, as it already refused `explain (analyze)`. +- The `/_x` policy panel no longer shows a deny, or calls a permission unreachable, for a rule whose predicate reads request input: the cell says `needs input`, as `x policy explain` does. +- `x upgrade` recognises an unedited `undeclared-env` guard copy from an earlier release again; its released-form hash had been overwritten by a later refresh. +- scripts: the public-API lock judges an optional trailing parameter added to a class method as compatible, as it does for a function. - test(action, query): browser client bundle pins raised by measured growth — rpc 25,281 B (≤ 25,303), query client 16,182 B (< 16,186): `clientStream`'s chunk `dates:` revival and coded mid-body cut (+272 B), and the unkeyed-write-once rule (+31 B). ## Releases diff --git a/docs/history/cli-file-map.md b/docs/history/cli-file-map.md index 57e352073..d6c0a503f 100644 --- a/docs/history/cli-file-map.md +++ b/docs/history/cli-file-map.md @@ -350,3 +350,15 @@ which bus carries cache/ISR invalidations: transport if it crosses processes, el ## `page-speculation.ts` (moved 2026-11-15) Speculation Rules for documents WITHOUT the router (`navigation.speculation`): an allow-list of pure-read pages + +## `dev-lock-live.ts` / `db-{migrate,rollback}-pass.ts` / `dev-db-*.ts` (moved 2026-11-19) + +a live `x dev` on the embedded database runs `x db migrate|rollback` itself (`POST /_x/db/…`), then rebuilds; `x db reset|status|diagnostics|recount|seed`, `backfill --write`, `x jobs` writes, `x tasks run` and `x auth seal-mfa` refuse, the fix stopping it first + +## `codemods/` / `cmd-upgrade-codemods.ts` / `upgrade-gate-codemods.ts` (moved 2026-11-19) + +a template change an app keeps, carried by a codemod (`codemod.ts`, the ONE list `codemods/index.ts`); the hop's installed CLI applies them before its gate; `scripts/template-codemods.ts` refuses one with none + +## `framework-schema-verify.ts` / `-wait.ts` / `app-migrations-verdict.ts` / `serve-boot-probe.ts` (moved 2026-11-19) + +a serving role behind its schema (stamp or app ledger) WAITS, `ULTIMATE_SCHEMA_WAIT_MS`, probe port up; a newer major refuses at once diff --git a/docs/history/core-rules.md b/docs/history/core-rules.md index ba34a0526..5fa478aa4 100644 --- a/docs/history/core-rules.md +++ b/docs/history/core-rules.md @@ -101,3 +101,7 @@ never `throw new Error`. A FRAMEWORK code: `bun run new-error-code` (a class, `C ## where a visitor's light/dark choice is stored `theme-storage.ts` (`THEME_STORAGE_KEY`, also on `./page`) | render's boot script reads it, ui's toggle writes it — both tier 4, so the one literal lives here. Persisted in browsers: never respelled + +## `error-reporter.ts`'s Sentry transport (moved 2026-11-19) + +`error-reporter-sentry.ts`, an optional export, reads the answer: one warn per non-2xx status, a 429 pauses for its `Retry-After` (60 s unstated), bodies cancelled. A DSN refusal never echoes its userinfo; a DSN that is not an http(s) URL (a legacy scheme-less `key:secret@host/1`) is described, never echoed, in the cause and in `meta.dsn`. Full rule: `docs/history/core.md`. diff --git a/docs/history/http.md b/docs/history/http.md index 51500c16d..114d3cdb9 100644 --- a/docs/history/http.md +++ b/docs/history/http.md @@ -913,4 +913,4 @@ pod for those decisions — logged, and a weaker limit rather than none. Proof: ## `compress`, in full (moved 2026-11-12, sweep 11) -- **`compress` is the last stage and has no option** (`compress.ts`, `compress-read.ts`): `zstd` then `gzip` by RFC 9110 weight; a 304's validator form is its 200's (`etag-form.ts`); a public strong-ETag body is coded once per process (`compress-cache.ts`, LRU 512 / 16 MiB). Signed-in: coded only when `immutable`. ≤256 KiB declared is coded whole; past it, or undeclared once 1 KiB is read, streamed with no length. An undeclared NDJSON feed never is. A refused response is the SAME object. `private`, `no-store`, `no-cache` or `no-transform` is identity (BREACH); `vary: accept-encoding` goes on every answer past the type and cache conditions. A counted read that overruns, fails or passes `ctx.signal`, or a `gzipSync` throw, logs `http.compress_failed`: identity, whole. +- **`compress` is the last stage and has no option** (`compress.ts`, `compress-read.ts`): `zstd` then `gzip` by RFC 9110 weight; a 304's validator form is its 200's (`etag-form.ts`); a public strong-ETag body is coded once per process (`compress-cache.ts`, LRU 512 / 16 MiB). Signed-in: coded only when `immutable`. ≤256 KiB declared is coded whole; past it, or undeclared once 1 KiB is read, streamed with no length. An undeclared NDJSON feed never is. A refused response is the SAME object. `private`, `no-store`, `no-cache` or `no-transform` is identity (BREACH); `vary: accept-encoding` goes on every answer past the type and cache conditions. A counted read that overruns, fails or passes `ctx.signal`, or a `gzipSync` throw, logs `http.compress_failed`: identity, whole. An `immutable` asset is coded ONCE in the background at br 11 / zstd 19 / gzip 9 (`compress-precode.ts`, 2 keys at a time; a coder that throws is logged, never unhandled), and later hits are lookups (moved here 2026-11-19). diff --git a/docs/history/jobs-rules.md b/docs/history/jobs-rules.md index 5171e6a2b..e781dcfa4 100644 --- a/docs/history/jobs-rules.md +++ b/docs/history/jobs-rules.md @@ -152,3 +152,10 @@ as it stood, verbatim; the package file keeps a one-line rule marked `†`. Wher | `driver-pg-operator-sql.ts` / `driver-pg-settle-sql.ts` | their statements; `SQL_ACK` / `SQL_NACK` (no counter since 31.13.0) and `SQL_COUNTER_FLUSH`, the batch `counter-batch.ts` writes | | `driver-pg-outbox-sql.ts` | the `x_outbox` statements | | `driver-pg-demand-sql.ts` | `QUEUE_DEMAND_ROWS` and `SQL_QUEUE_DEMAND`; the scaler fixture's `SQL_SCALER_DEMAND` reads the same predicate | + +## Files rows merged: `onSettled` (2026-11-19) + +| File | Owns | +|---|---| +| `settled-types.ts` / `driver-settle.ts` / `settle-redrive.ts` / `scheduler-upkeep.ts` | what `onSettled` is handed; the settle fence and the `onSettled` debt contract; the leader's re-drive of lost debts; the leader's cadence (counter fold, re-drive) | +| `driver-memory-settle.ts` / `driver-pg-settle-debt.ts` / `driver-redis-settle.ts` | the `onSettled` debt per driver: a map, `x_jobs.settle_owed`, the `owed` ZSET — held equal by `@ultimat3/testing`'s `SETTLE_DEBT_CHECKS` | diff --git a/framework.manifest.json b/framework.manifest.json index 1445beac1..22ea42360 100644 --- a/framework.manifest.json +++ b/framework.manifest.json @@ -1,6 +1,6 @@ { "version": 1, - "buildId": "93058c71c6f55c6e741a0ae67486ab19331d2b5c440e61062f9694a10d07fc75", + "buildId": "0194ad3a677f4631040ceba425489ab9a58d64ed5f4aecbf784d9f48714ca212", "tiers": { "0": [ "core", @@ -6184,6 +6184,11 @@ "owner": "realtime", "at": "packages/realtime/src/error-titles.ts" }, + { + "code": "X_TASK_RUN_PRODUCTION", + "owner": "cli", + "at": "packages/cli/src/error-codes.ts" + }, { "code": "X_TELEMETRY_SAMPLER_ARG_INVALID", "owner": "core", diff --git a/packages/cache/CLAUDE.md b/packages/cache/CLAUDE.md index 848fd1788..b88f2730c 100644 --- a/packages/cache/CLAUDE.md +++ b/packages/cache/CLAUDE.md @@ -11,7 +11,7 @@ Tier 1. Tagged caching + THE invalidation graph. ## Rules - **A tier's own LIMIT is screened where `app.config.ts` names it** — `assertFiniteCapacity`, - `assertFiniteDurationMs`, `assertFiniteSimilarityFloor`, beside `assertTtl` in `tiers.ts`, all + `assertFiniteDurationMs`, `assertFiniteSimilarityFloor` (`tier-bounds.ts`; `assertTtl` is in `tiers.ts`), all raising `X_CACHE_LIMIT_INVALID`. A `NaN` limit makes every comparison false, so the guard switches itself off (no eviction, no similarity floor). Never `Math.max(1, x)` in front: a clamp is not a validator. **The `Finite` in the names is load-bearing** — `bun run finite-bounds` recognises a @@ -205,6 +205,7 @@ Tier 1. Tagged caching + THE invalidation graph. | `tags.ts` | `tag` factory, wire form, match semantics, `tagKeys`, declared-tag registry | | `graph.ts` | tag → dependents (cache keys, ISR routes, CDN paths, live queries) | | `tiers.ts` | `CacheTier`, `TierLabel`, `assertTtl`, read-through stack | +| `tier-bounds.ts` | `assertFiniteCapacity` / `assertFiniteDurationMs` / `assertFiniteSimilarityFloor`: a tier's other screened knobs | | `fence.ts` | the invalidation fence a fill (here or in `query`) checks before it publishes | | `tier-leading.ts` | which fence each in-flight load holds, and whether a reader may join it | | `tier-fence.ts` | `TierFence`/`FenceVerdict`, and how a fill samples and asks a shared tier's fence | diff --git a/packages/cache/src/index.ts b/packages/cache/src/index.ts index 494c7b993..ee8f68e62 100644 --- a/packages/cache/src/index.ts +++ b/packages/cache/src/index.ts @@ -102,6 +102,11 @@ export { tagMatches, tagsIntersect, } from './tags'; +export { + assertFiniteCapacity, + assertFiniteDurationMs, + assertFiniteSimilarityFloor, +} from './tier-bounds'; export type { TierOperation } from './tier-failures'; export { bestEffort } from './tier-failures'; export type { FenceVerdict, TierFence } from './tier-fence'; @@ -119,9 +124,6 @@ export type { TtlScope, } from './tiers'; export { - assertFiniteCapacity, - assertFiniteDurationMs, - assertFiniteSimilarityFloor, assertTtl, cacheStack, DEFAULT_LOAD_DEADLINE_MS, diff --git a/packages/cache/src/lru.ts b/packages/cache/src/lru.ts index 87f35bb39..cfdf9c5ce 100644 --- a/packages/cache/src/lru.ts +++ b/packages/cache/src/lru.ts @@ -9,6 +9,7 @@ import { utf8ByteLength } from './byte-length'; import { CacheTooLargeError } from './errors'; import type { CacheTag } from './tags'; import { serializeTag } from './tags'; +import { assertFiniteCapacity, assertFiniteDurationMs } from './tier-bounds'; import type { CacheEntry, CacheSetOptions, @@ -17,13 +18,7 @@ import type { TierInvalidation, TtlJitter, } from './tiers'; -import { - assertFiniteCapacity, - assertFiniteDurationMs, - assertJitterFraction, - assertTtl, - nowMs, -} from './tiers'; +import { assertJitterFraction, assertTtl, nowMs } from './tiers'; import { decodeCacheValue, encodeCacheValue } from './value-codec'; export interface LruOptions { diff --git a/packages/cache/src/purge-cloudflare.ts b/packages/cache/src/purge-cloudflare.ts index fa1bc1450..238ac3596 100644 --- a/packages/cache/src/purge-cloudflare.ts +++ b/packages/cache/src/purge-cloudflare.ts @@ -17,7 +17,7 @@ import { purgePost, requireCredential, } from './purge-http'; -import { assertFiniteDurationMs } from './tiers'; +import { assertFiniteDurationMs } from './tier-bounds'; export const CLOUDFLARE_API_URL = 'https://api.cloudflare.com/client/v4'; diff --git a/packages/cache/src/purge-fastly.ts b/packages/cache/src/purge-fastly.ts index 9bd21c32e..8458f89a4 100644 --- a/packages/cache/src/purge-fastly.ts +++ b/packages/cache/src/purge-fastly.ts @@ -18,7 +18,7 @@ import { purgePost, requireCredential, } from './purge-http'; -import { assertFiniteDurationMs } from './tiers'; +import { assertFiniteDurationMs } from './tier-bounds'; export const FASTLY_API_URL = 'https://api.fastly.com'; diff --git a/packages/cache/src/redis.ts b/packages/cache/src/redis.ts index f65ae1337..ca23c035d 100644 --- a/packages/cache/src/redis.ts +++ b/packages/cache/src/redis.ts @@ -23,6 +23,7 @@ import { DEFAULT_REDIS_COMMAND_TIMEOUT_MS, withinDeadline } from './redis-deadli import { bumpGenerations, sampleGenerations } from './redis-fence'; import type { CacheTag } from './tags'; import { parseTag, serializeTag } from './tags'; +import { assertFiniteCapacity, assertFiniteDurationMs } from './tier-bounds'; import type { CacheEntry, CacheSetOptions, @@ -31,13 +32,7 @@ import type { TierInvalidation, TtlJitter, } from './tiers'; -import { - assertFiniteCapacity, - assertFiniteDurationMs, - assertJitterFraction, - assertTtl, - nowMs, -} from './tiers'; +import { assertJitterFraction, assertTtl, nowMs } from './tiers'; import { decodeCacheValue, encodeCacheValue } from './value-codec'; /** The slice of Bun's Redis client this tier uses. Narrow on purpose: easy to fake in tests. */ diff --git a/packages/cache/src/semantic.ts b/packages/cache/src/semantic.ts index 0d15e45f2..25e570741 100644 --- a/packages/cache/src/semantic.ts +++ b/packages/cache/src/semantic.ts @@ -13,9 +13,8 @@ import { assertFiniteCapacity, assertFiniteDurationMs, assertFiniteSimilarityFloor, - assertTtl, - nowMs, -} from './tiers'; +} from './tier-bounds'; +import { assertTtl, nowMs } from './tiers'; import { decodeCacheValue, encodeCacheValue } from './value-codec'; export type Embedding = readonly number[]; diff --git a/packages/cache/src/tier-bounds.ts b/packages/cache/src/tier-bounds.ts new file mode 100644 index 000000000..6887df887 --- /dev/null +++ b/packages/cache/src/tier-bounds.ts @@ -0,0 +1,70 @@ +// The bounds a tier's constructor screens besides its TTL: a ceiling (bytes or entries), a +// millisecond duration, the semantic tier's similarity floor. Split from `tiers.ts` (its 500-line +// ceiling); `assertTtl` and the jitter screen stay there, beside the lease they apply. + +import { CacheLimitInvalidError } from './errors'; +import type { TtlScope } from './tiers'; + +/** + * A tier's ceiling — bytes or entries — screened where it is still nameable. The same rule as + * `assertTtl` in `tiers.ts`, over the other knob a tier's constructor takes. A SEPARATE refusal + * from `X_CACHE_TOO_LARGE`, which is one entry against a valid ceiling: this one is the ceiling + * itself, and it needs a screen because a bad ceiling refuses nothing and evicts nothing rather + * than refusing everything. `NaN > x` and `x > NaN` are both false. + */ +export function assertFiniteCapacity(tier: TtlScope, option: string, value: number): number { + if (Number.isSafeInteger(value) && value > 0) return value; + throw new CacheLimitInvalidError({ + tier, + option, + value, + expected: 'a whole number greater than zero', + example: '10_000', + }); +} + +/** + * A millisecond duration: a driver's request budget (handed to `AbortSignal.timeout`, which THROWS + * on a non-finite one — inside `purgePost`'s try, so the config typo came back as a retryable + * transport failure that never happened) and a tier's own `defaultTtlMs`, which is otherwise only + * screened by `assertTtl` at the first `set`, one write into the process's life. + * + * The `Finite` in all three names here is NOT load-bearing, `As of 2026-08-26`. It was: a name + * regex meant `assertCapacity` and `assertTimeoutMs` left all nine of this package's options + * reading as unchecked while every one of them was screened. `bun run finite-bounds` now reads + * `SCREENING_CALLEES` in `scripts/lib/finite-screens.ts` — rename freely, move the rows. + */ +export function assertFiniteDurationMs(tier: string, option: string, value: number): number { + if (Number.isSafeInteger(value) && value > 0) return value; + throw new CacheLimitInvalidError({ + tier, + option, + value, + expected: 'a whole number of milliseconds greater than zero', + example: '60_000', + }); +} + +/** + * The similarity floor the semantic tier decides "same question" with — a correctness boundary, + * not a tuning knob, so `NaN` here does not loosen it, it removes it: `similarity < NaN` is false + * for every record. Cosine similarity is in [-1, 1] and a floor of 0 already admits an orthogonal + * vector, so anything outside [0, 1] is a number nobody can have meant. + */ +export function assertFiniteSimilarityFloor( + tier: TtlScope, + option: string, + value: number, + /** Passed only where the value is a CALL argument rather than a factory option. */ + source?: string | undefined, +): number { + if (Number.isFinite(value) && value >= 0 && value <= 1) return value; + throw new CacheLimitInvalidError({ + tier, + option, + value, + expected: 'a number from 0 to 1', + example: '0.92', + source, + }); +} diff --git a/packages/cache/src/tiers.ts b/packages/cache/src/tiers.ts index 6a4baab15..b1c3650b4 100644 --- a/packages/cache/src/tiers.ts +++ b/packages/cache/src/tiers.ts @@ -5,11 +5,12 @@ import type { CacheTierName, Clock, Scheduler } from '@ultimat3/core'; import { CACHE_TIERS, instrument, singleFlight, systemClock, tryUseContext } from '@ultimat3/core'; -import { CacheJitterInvalidError, CacheLimitInvalidError, CacheTtlInvalidError } from './errors'; +import { CacheJitterInvalidError, CacheTtlInvalidError } from './errors'; import type { CacheFence, FenceScope } from './fence'; import { markInvalidated, sampleFence } from './fence'; import { mergeSetOptions, tagsAddedSince, ttlOptionsFor } from './set-options'; import type { CacheTag } from './tags'; +import { assertFiniteDurationMs } from './tier-bounds'; import { bestEffort } from './tier-failures'; import type { TierFence, TierFences } from './tier-fence'; import { sampleTierFences, verdictOf } from './tier-fence'; @@ -101,70 +102,6 @@ export interface CacheSetOptions { */ export type TtlScope = TierName | 'semantic'; -/** - * A tier's ceiling — bytes or entries — screened where it is still nameable. The same rule as - * `assertTtl` beside it, over the other knob a tier's constructor takes. A SEPARATE refusal from - * `X_CACHE_TOO_LARGE`, which is one entry against a valid ceiling: this one is the ceiling itself, - * and it needs a screen because a bad ceiling refuses nothing and evicts nothing rather than - * refusing everything. `NaN > x` and `x > NaN` are both false. - */ -export function assertFiniteCapacity(tier: TtlScope, option: string, value: number): number { - if (Number.isSafeInteger(value) && value > 0) return value; - throw new CacheLimitInvalidError({ - tier, - option, - value, - expected: 'a whole number greater than zero', - example: '10_000', - }); -} - -/** - * A millisecond duration: a driver's request budget (handed to `AbortSignal.timeout`, which THROWS - * on a non-finite one — inside `purgePost`'s try, so the config typo came back as a retryable - * transport failure that never happened) and a tier's own `defaultTtlMs`, which is otherwise only - * screened by `assertTtl` at the first `set`, one write into the process's life. - * - * The `Finite` in all three names here is NOT load-bearing, `As of 2026-08-26`. It was: a name - * regex meant `assertCapacity` and `assertTimeoutMs` left all nine of this package's options - * reading as unchecked while every one of them was screened. `bun run finite-bounds` now reads - * `SCREENING_CALLEES` in `scripts/lib/finite-screens.ts` — rename freely, move the rows. - */ -export function assertFiniteDurationMs(tier: string, option: string, value: number): number { - if (Number.isSafeInteger(value) && value > 0) return value; - throw new CacheLimitInvalidError({ - tier, - option, - value, - expected: 'a whole number of milliseconds greater than zero', - example: '60_000', - }); -} - -/** - * The similarity floor the semantic tier decides "same question" with — a correctness boundary, - * not a tuning knob, so `NaN` here does not loosen it, it removes it: `similarity < NaN` is false - * for every record. Cosine similarity is in [-1, 1] and a floor of 0 already admits an orthogonal - * vector, so anything outside [0, 1] is a number nobody can have meant. - */ -export function assertFiniteSimilarityFloor( - tier: TtlScope, - option: string, - value: number, - /** Passed only where the value is a CALL argument rather than a factory option. */ - source?: string | undefined, -): number { - if (Number.isFinite(value) && value >= 0 && value <= 1) return value; - throw new CacheLimitInvalidError({ - tier, - option, - value, - expected: 'a number from 0 to 1', - example: '0.92', - source, - }); -} - /** * A tier's TTL spread, screened when the tier is BUILT as well as at each write: found only at the * first `set`, a bad fraction refused every write of a tier that had booted healthy. diff --git a/packages/cli/CLAUDE.md b/packages/cli/CLAUDE.md index cdd16e1a5..2a3d1c6ae 100644 --- a/packages/cli/CLAUDE.md +++ b/packages/cli/CLAUDE.md @@ -61,7 +61,7 @@ Commands: `bun test ./packages/cli/` (repo root: the preload), | `verify-seeds.ts` / `verify-seeds-probe.ts` | `unit` runs the seeds in a child on `x exercise`'s scratch database; an uncoded throw is `X_SEED_FAILED` † | | `boundary-findings.ts` / `app-boundaries.ts` / `boundary-cuts.ts` / `package-boundaries.ts` | surface + layer rules, `X_BOUNDARY_PACKAGE_TO_APP`; a `fix:` is the concrete cut † | | `app-boundaries.ts` (workspaces) | `@<scope>/<app>/<rest>` resolves onto `apps/<app>/<rest>` when that is an app source, so the surface rules hold across app workspaces | -| `app-transport.ts` / `browser-{transport,import-chain,barrel-cut}.ts` / `transport-{calls,values}.ts` / `binding-names.ts` / `import-closure.ts` / `server-barrels.ts` | `boundaries`, built in: one browser transport; a server barrel below an island is cut at its first hop † | +| `app-transport.ts` / `browser-{transport,import-chain,barrel-cut}.ts` / `transport-*.ts` / `binding-names.ts` / `import-closure.ts` / `server-barrels.ts` | `boundaries`: one browser transport; a server barrel below an island is cut at its first hop † | | `guards.ts` / `guard-sources.ts` | an app's `guards/*.ts`, run on `boundaries`; ONE shared walk (`GuardSources`) † | | `guards-built-in.ts` / `guards-built-in-refusal.ts` | shipped guards run from the installed CLI, never a copy; `guards/shipped.json` is the opt-in and the severities; `x g guard <shipped>` is `X_GUARD_BUILT_IN` | | `templates/scaffold-guards.ts` | `SHIPPED`, the one list of shipped guards (`guards-built-in.ts`, `doctor-guards.ts`, `codemods/vendored-guards.ts`) † | @@ -135,16 +135,17 @@ Commands: `bun test ./packages/cli/` (repo root: the preload), | `runtime-bindings.ts` | which service each binding points at (embedded or external); events follow `NATS_URL` | | `runtime-queue.ts` / `runtime-services.ts` / `runtime-bus.ts` | db + queue; every other accessor; the bus | | `framework-schema-apply.ts` / `framework-schema-stamp.ts` | the framework tables, applied in one locked transaction † | -| `framework-schema-verify.ts` / `-wait.ts` / `app-migrations-verdict.ts` / `serve-boot-probe.ts` | a serving role behind its schema (stamp or app ledger) WAITS, `ULTIMATE_SCHEMA_WAIT_MS`, probe port up; a newer major refuses at once | +| `framework-schema-verify.ts` / `-wait.ts` / `app-migrations-verdict.ts` / `serve-boot-probe.ts` | a serving role behind its schema WAITS (`ULTIMATE_SCHEMA_WAIT_MS`); a newer major refuses at once † | | `runtime-isr.ts` | the ISR controller both boots serve through, attached to `invalidateTags` (`attachedIsr`) † | | `runtime-mfa-warning.ts` / `runtime-idempotency-scope.ts` | boot warnings: unsealed MFA secrets, a per-process idempotency store † | | `app-config-load.ts` | the ONE reader of `app.config.ts` (`loadAppConfig`) † | | `theme-brand.ts` | the ONE reader of an app's theme (`brand` in `apps/web/shared/theme.ts`) † | | `runtime-{jobs,realtime,notify-retention,cache,purge,replica,database-ssl}.ts` | the `app.config.ts` sections the boot obeys (`*Of(config)`); `database.ssl` adds `sslmode=require` where neither the URL nor `PGSSLMODE` sets one, on every pool (`withAppTls`) † | | `runtime-cache-bus.ts` | which bus carries cache/ISR invalidations across replicas; one `cache.broadcast` boot line † | +| `runtime-cache-frame.ts` | the bust frame on `x.cache.invalidate`: tags + optional `{scopes}`; older receivers keep the strings | | `runtime-jobs.ts` (queues) | `WORKER_QUEUES` = the EXACT set, else `X_WORKER_QUEUE_UNKNOWN`; `-unserved.ts`: what no worker serves † | | `serve-retire.ts` / `dev-restart-retire.ts` | the worker retire (SIGUSR2, before an `x dev` restart's drain) † | -| `role-start*.ts` / `role-realtime.ts` | `--role` selection, start/stop per role, device mounts † | +| `role-start*.ts` / `role-select.ts` / `role-realtime.ts` | `--role` selection (`x dev` runs only `config.roles`: `rolesDeclaredForDev`), start/stop per role, device mounts † | | `role-wake.ts` | the worker's LISTEN session (`@ultimat3/jobs`' `startQueueWake`) — worker role only, only over a client that `canListen` — and `queue_wake_live` | | `role-sync.ts` / `role-replicator.ts` / `runtime-live-feed.ts` | the sync node, the change feed | | `runtime-render*.ts` / `runtime-{isr-outcome,assets,storage,hooks}.ts` / `route-islands.ts` / `api-routes.ts` | the HTTP surface both boots mount † | @@ -163,7 +164,7 @@ Commands: `bun test ./packages/cli/` (repo root: the preload), | `serve-prebuilt.ts` / `serve-prebuilt-paths.ts` | the image's prebuilt store; a boot that built anything logs `X_IMAGE_NOT_PREBUILT` † | | `dev-*.ts` | `x dev` only: dashboard sources, traces, the N+1 ledger, watcher, reload, lock, port | | `cmd-stop.ts` / `cmd-stop-spec.ts` | `x stop`: the lock's pid only, SIGTERM, wait; a reused pid's lock is cleared, unsignalled; `X_DEV_STOP_TIMEOUT` † | -| `dev-lock-live.ts` / `db-{migrate,rollback}-pass.ts` / `dev-db-*.ts` | a live `x dev` on the embedded database runs `x db migrate\|rollback` itself (`POST /_x/db/…`), then rebuilds; `x db reset\|status\|diagnostics\|recount\|seed`, `backfill --write`, `x jobs` writes and `x auth seal-mfa` refuse, the fix stopping it first | +| `dev-lock-live.ts` / `db-{migrate,rollback}-pass.ts` / `dev-db-*.ts` | beside a live `x dev` on the embedded database, `x db migrate\|rollback` run in it (`POST /_x/db/…`); other writes refuse † | | `dev-dashboard-guard.ts` / `loopback-host.ts` | `/_x`: loopback `Host` (`X_DEV_HOST_REFUSED`) and peer (`X_DEV_PEER_REFUSED`) † | | `dev-host.ts` / `dev-tls*.ts` | `x dev --host` (loopback default) and `--tls`: a cached self-signed cert in `.x/tls/`, WebCrypto + hand-written DER | | `doctor-pooler.ts` / `runtime-statement-bound.ts` | the statement bound and a pooler's refusal, one finding, one boot line † | @@ -176,7 +177,7 @@ Commands: `bun test ./packages/cli/` (repo root: the preload), | `prerender.ts` / `measure-scope.ts` / `static-report.ts` / `static-*.ts` | the static export; weigh-only renders as `measurementActor()` † | | `sw-artifacts.ts` / `pwa-artifacts.ts` / `favicon.ts` | the service worker, the web manifest, `/favicon.ico` | | `cmd-db.ts` / `migrations.ts` / `db-*.ts` (generate, branch, seed, backfill, subscribes, accept-created) | one migration engine for `x db` and `ROLE=migrate` † | -| `cmd-db-rollback.ts` / `db-rollback-consent.ts` / `db-applied-edits.ts` | `x db rollback`: off dev/test every id named in `ROLLBACK_ALLOW_DESTRUCTIVE`; `gen` refuses an edited applied migration | +| `cmd-db-rollback.ts` / `db-rollback-consent.ts` / `db-applied-edits.ts` | `x db rollback`: on a named deploy, or an external non-loopback database, every id named in `ROLLBACK_ALLOW_DESTRUCTIVE`; `gen` refuses an edited applied migration | | `db-diagnostics.ts` | `x db diagnostics`: `startDb`, never `startQueue`; exit 0 whatever it says † | | `db-schema-dump.ts` / `db-schema-refresh.ts` / `db-replay-engine.ts` / `migration-extensions.ts` / `db-object-drift.ts` | the schema dump, replayed on a scratch database † | @@ -185,7 +186,7 @@ Commands: `bun test ./packages/cli/` (repo root: the preload), | File | Job | |---|---| | `cmd-registries.ts` / `cmd-jobs.ts` / `cmd-tasks.ts` / `cmd-policy.ts` / `cmd-i18n.ts` | project a framework registry; each pairs CLI wiring with a facts module | -| `cmd-tasks-run.ts` | `x tasks run`: `TaskHandle.enqueue()`; `--production` in production | +| `cmd-tasks-run.ts` | `x tasks run`: `TaskHandle.enqueue()`; production needs `--production` or `ULTIMATE_TASK_RUN=<name>` (`X_TASK_RUN_PRODUCTION`) | | `doctor-api-listing.ts` | `x doctor` warns: action/query off a `defineApi()` listing others | | `cmd-auth.ts` / `cmd-auth-spec.ts` / `doctor-auth.ts` | `x auth seal-mfa`: seals plaintext `x_users.mfa_secret` through auth's `sealMfaSecrets` | | `cmd-mcp.ts` / `mcp-host*.ts` / `mcp-errors.ts` / `mcp-db-target.ts` / `mcp-test-{output,run}.ts` | `x mcp serve`: 23 tools, two transports; `tests.run`/`verify.run` ARE `x test`/`x verify` † | @@ -201,7 +202,7 @@ Commands: `bun test ./packages/cli/` (repo root: the preload), | `cmd-docs.ts` / `docs-sources.ts` / `docs-section.ts` | `x docs`: the app's and the CLI's `@ultimat3` docs; `Page#anchor` prints a section † | | `cmd-env-init.ts` / `env-production.ts` / `cmd-deploy-preflight.ts` | the one writer of `.env.production`; compose pre-flight (`X_DEPLOY_ENV_MISSING`) † | | `cmd-upgrade.ts` / `upgrade-*.ts` | `x upgrade`: one major per run; no `requiresApp` † | -| `codemods/` / `cmd-upgrade-codemods.ts` / `upgrade-gate-codemods.ts` | a template change an app keeps, carried by a codemod (`codemod.ts`, the ONE list `codemods/index.ts`); the hop's installed CLI applies them before its gate; `scripts/template-codemods.ts` refuses one with none | +| `codemods/` / `cmd-upgrade-codemods.ts` / `upgrade-gate-codemods.ts` | a kept template change, carried by a codemod (ONE list: `codemods/index.ts`) † | | `cmd-deploy-verify.ts` / `deploy-verify-*.ts` / `cmd-status*.ts` | `x deploy verify`: the wait, the verdict, lazy sources † · `x status` | ## Adding a command diff --git a/packages/cli/README.md b/packages/cli/README.md index d1daa80d7..f717e5e6d 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -34,6 +34,7 @@ Commands and the `x verify` step count, `As of 2026-08`: | `x manifest` / `x routes` | generated facts | `x.manifest.json`, `openapi.json`, route table | | `x actions` / `x queries` / `x entities` | the declaration registries | `list` and `show <name>`, straight off the registries | | `x tasks list\|show` | cron tasks | timezone and next run, off `registeredTasks()` | +| `x tasks run <name>` | fire a task now | its jobs onto the app's queue (`TaskHandle.enqueue()`); under `ULTIMATE_ENV=production` only with `--production` or `ULTIMATE_TASK_RUN=<name>`, else `X_TASK_RUN_PRODUCTION` | | `x jobs list\|show\|retry\|cancel\|delete\|promote\|pause\|resume` | the queue | depth, dead letters, step traces, `retry --from-step`, `cancel --reason`; `list --json` pages as `rows`/`nextCursor`/`hasMore`; `drain` is planned (`X_NOT_IMPLEMENTED`) | | `x test [type]` | one of the six test types, or all | same type rule as the gate; `--filter`, `--sample N` | | `x env check\|example\|init` | the typed environment `envSchema` declares; `init --production` writes `.env.production` for a compose deploy, secrets generated, never printed | and the `.env.example` rendered from it, plus the framework's deploy-required secrets (`ULTIMATE_CURSOR_SECRET`, `STORAGE_SIGNING_SECRET` unless `S3_ENDPOINT` is set), which `check` asks for wherever the boot refuses them — outside `development`/`test`, or with no environment named | diff --git a/packages/cli/src/cmd-tasks-run.test.ts b/packages/cli/src/cmd-tasks-run.test.ts index a88d72bbe..df696d23a 100644 --- a/packages/cli/src/cmd-tasks-run.test.ts +++ b/packages/cli/src/cmd-tasks-run.test.ts @@ -1,6 +1,6 @@ // `x tasks run <name>`: a scheduled task fired now, through the task's own manual-run path — the // jobs its occurrence would enqueue land on the app's queue, the result names each one, and a -// production environment asks for it by flag. Driven against `@ultimat3/jobs`' real registries. +// production environment asks for it by flag (or, in a container, by `ULTIMATE_TASK_RUN`). Driven against `@ultimat3/jobs`' real registries. import { afterAll, afterEach, beforeEach, describe, expect, test } from 'bun:test'; // why: Bun ships no temp-directory API; `requireAppRoot` needs an app root on disk. @@ -159,8 +159,11 @@ describe('unit · x tasks run', () => { const thrown = await rejectedBy(() => tasksCommand.run(contextFor(appRoot(), ['nightlyDigest'], { env })), ); - expect(thrown.code).toBe('X_CLI_BAD_FLAG'); + // `x db seed`'s refusal form: its own code (the argv was well formed, the answer is still no), + // the container's env-var half named in the cause, the explicit flag line as the fix. + expect(thrown.code).toBe('X_TASK_RUN_PRODUCTION'); expect(thrown.cause).toContain('production'); + expect(thrown.cause).toContain('ULTIMATE_TASK_RUN=nightlyDigest'); expect(thrown.fix).toBe('x tasks run nightlyDigest --production --json'); expect(await driver.introspect?.list({})).toEqual([]); const asked = await tasksCommand.run( @@ -170,6 +173,21 @@ describe('unit · x tasks run', () => { expect(await driver.introspect?.list({})).toHaveLength(2); }); + test('a container whose command line is fixed names the task in ULTIMATE_TASK_RUN', async () => { + registerDigest(); + const other = { ULTIMATE_ENV: 'production', ULTIMATE_TASK_RUN: 'weeklyReport' }; + const thrown = await rejectedBy(() => + tasksCommand.run(contextFor(appRoot(), ['nightlyDigest'], { env: other })), + ); + // Naming another task consents to nothing: the variable says which task this deploy fires. + expect(thrown.code).toBe('X_TASK_RUN_PRODUCTION'); + expect(await driver.introspect?.list({})).toEqual([]); + const named = { ULTIMATE_ENV: 'production', ULTIMATE_TASK_RUN: 'nightlyDigest' }; + const asked = await tasksCommand.run(contextFor(appRoot(), ['nightlyDigest'], { env: named })); + expect(asked.ok).toBe(true); + expect(await driver.introspect?.list({})).toHaveLength(2); + }); + test("asks exactly where x db seed's production gate asks: one predicate, no second answer", () => { for (const env of [ {}, diff --git a/packages/cli/src/cmd-tasks-run.ts b/packages/cli/src/cmd-tasks-run.ts index e5a5645e8..e7d0c1ca8 100644 --- a/packages/cli/src/cmd-tasks-run.ts +++ b/packages/cli/src/cmd-tasks-run.ts @@ -2,39 +2,51 @@ // app's queue — so a cron job is exercised in dev without waiting for its cron or editing it. // Through the task's own manual-run path (`TaskHandle.enqueue`), the one the admin's run-now uses. -import { isProduction } from '@ultimat3/core'; +import { isProduction, UltimateError } from '@ultimat3/core'; import type { TaskHandle } from '@ultimat3/jobs'; import type { CommandContext } from './command'; import { refuseEmbeddedWriteBesideDev } from './dev-lock-live'; -import { BadFlagError } from './errors'; import { withJobDriver } from './jobs-driver'; import { msg } from './messages'; import type { CommandResult, Finding, JsonValue } from './output'; import { flagBool } from './parse'; import { quoteArg } from './shell-quote'; +/** The container's half of the consent: the task this deploy fires, named, as a fixed argv can. */ +export const TASK_RUN_ENV = 'ULTIMATE_TASK_RUN'; + /** * Does this environment fire only when asked by name? `x db seed`'s production gate, mirrored: the * same predicate (`ULTIMATE_ENV` resolved `production`; staging runs unasked, as a `dev` seed does; - * an `ULTIMATE_ENV` that is no environment refuses with `X_ENVIRONMENT_INVALID`), and consent is a - * flag naming what is asked for. Pinned against `seedTiersFor` by `cmd-tasks-run.test.ts`. + * an `ULTIMATE_ENV` that is no environment refuses with `X_ENVIRONMENT_INVALID`), and consent is + * named — `--production` on the command line, or `ULTIMATE_TASK_RUN=<name>` for a container whose + * command line is fixed, as `--tier` and `ULTIMATE_SEED_TIER` are. Pinned against `seedTiersFor`. */ export const tasksRunNeedsFlag = (env: Readonly<Record<string, string | undefined>>): boolean => isProduction({ env }); /** - * Production fires only by flag. Not a scheduled occurrence: the scheduler's watermark is never + * `X_SEED_ENVIRONMENT`'s form: its own code, not `X_CLI_BAD_FLAG` — the argv was well formed and + * the answer is still no. The env var is in the cause, the one pasteable flag line is the fix. + */ +export class TaskRunProductionError extends UltimateError { + constructor(name: string) { + super({ + code: 'X_TASK_RUN_PRODUCTION', + cause: `ULTIMATE_ENV resolved production, where firing ${name} enqueues real work beside its next scheduled occurrence — x tasks run fires there only when asked by name; ${TASK_RUN_ENV}=${name} says this deploy takes it`, + fix: `x tasks run ${quoteArg(name)} --production --json`, + }); + } +} + +/** + * Production fires only when asked. Not a scheduled occurrence: the scheduler's watermark is never * moved, so the next real tick still fires — a manual run in production is real work twice. */ function refuseUnaskedProduction(ctx: CommandContext, name: string): void { - if (flagBool(ctx.args, 'production')) return; + if (flagBool(ctx.args, 'production') || ctx.env[TASK_RUN_ENV] === name) return; if (!tasksRunNeedsFlag(ctx.env)) return; - throw new BadFlagError({ - flag: 'production', - command: 'tasks run', - reason: `ULTIMATE_ENV resolved production, where firing ${name} enqueues real work beside its next scheduled occurrence — x tasks run fires there only when --production asks by name`, - fix: `x tasks run ${quoteArg(name)} --production --json`, - }); + throw new TaskRunProductionError(name); } /** One job a fire enqueued, as `TaskHandle.enqueue` answers it (`@ultimat3/jobs` exports no name). */ diff --git a/packages/cli/src/cmd-tasks-spec.ts b/packages/cli/src/cmd-tasks-spec.ts index 5df70f9a5..86d0e4a37 100644 --- a/packages/cli/src/cmd-tasks-spec.ts +++ b/packages/cli/src/cmd-tasks-spec.ts @@ -20,7 +20,8 @@ export const tasksSpec: CommandSpec = { { name: 'production', type: 'boolean', - summary: 'run: fire it where ULTIMATE_ENV resolves production — real work, asked for by name', + summary: + 'run: fire it where ULTIMATE_ENV resolves production — real work, asked for by name; also ULTIMATE_TASK_RUN=<name>', subcommands: ['run'], }, ], diff --git a/packages/cli/src/db-rollback-pass.test.ts b/packages/cli/src/db-rollback-pass.test.ts new file mode 100644 index 000000000..e6ca91776 --- /dev/null +++ b/packages/cli/src/db-rollback-pass.test.ts @@ -0,0 +1,50 @@ +// The pass hands `rollback()` the database it runs against, so the consent rule for a database on +// another machine is asked of the real binding: `DATABASE_URL=<remote>` with no environment named +// is refused until `ROLLBACK_ALLOW_DESTRUCTIVE` names the id. + +import { afterAll, beforeAll, describe, expect, test } from 'bun:test'; +// why: `node:fs` — Bun has no temp-directory API. +import { mkdtempSync, rmSync } from 'node:fs'; +// why: Bun exposes no tmpdir(), so only node:os answers the platform temp root. +import { tmpdir } from 'node:os'; +// why: Bun exposes no path-join primitive. +import { join } from 'node:path'; +import { isUltimateError } from '@ultimat3/core'; +import { migrate, pgliteClient, ROLLBACK_ALLOW_DESTRUCTIVE_ENV, setDbClient } from '@ultimat3/db'; +import { reverseApplied } from './db-rollback-pass'; +import { MIGRATIONS_DIR, readMigrations } from './migrations'; + +const PGLITE_BOOT_MS = 30_000; +const ID = '0001_gizmos'; +const REMOTE = 'postgres://app@db.prod.example.com:5432/app'; +const root = mkdtempSync(join(tmpdir(), 'x-rollback-pass-')); +const client = pgliteClient(); + +beforeAll(async () => { + await Bun.write( + join(root, MIGRATIONS_DIR, `${ID}.sql`), + 'create table gizmos (id uuid primary key);\n-- down\ndrop table gizmos;\n', + ); + await migrate({ migrations: await readMigrations(root), client }); + setDbClient(client); +}, PGLITE_BOOT_MS); + +afterAll(() => { + setDbClient(undefined); + rmSync(root, { recursive: true, force: true }); +}); + +describe('reverseApplied', () => { + test('a remote DATABASE_URL needs the names even when no environment is set', async () => { + const refused = await reverseApplied(root, { DATABASE_URL: REMOTE }, 1).then( + () => undefined, + (error: unknown) => error, + ); + expect(isUltimateError(refused) ? refused.code : refused).toBe( + 'X_MIGRATION_ROLLBACK_DESTRUCTIVE', + ); + + const named = { DATABASE_URL: REMOTE, [ROLLBACK_ALLOW_DESTRUCTIVE_ENV]: ID }; + expect(await reverseApplied(root, named, 1)).toEqual([ID]); + }); +}); diff --git a/packages/cli/src/db-rollback-pass.ts b/packages/cli/src/db-rollback-pass.ts index 25761af8c..5aba579f8 100644 --- a/packages/cli/src/db-rollback-pass.ts +++ b/packages/cli/src/db-rollback-pass.ts @@ -26,7 +26,9 @@ export async function reverseApplied( steps: number, ): Promise<readonly string[]> { const migrations = await readMigrations(root); - const confirm = rollbackConfirm(await withoutDown(root, migrations), env, steps); + // The binding, so a database on another machine needs the names whatever the environment says. + const database = resolveServices(root, env).db; + const confirm = rollbackConfirm(await withoutDown(root, migrations), env, steps, database); return rollback({ migrations, steps, confirm }); } diff --git a/packages/cli/src/error-codes.ts b/packages/cli/src/error-codes.ts index 95ca3b486..72219b54f 100644 --- a/packages/cli/src/error-codes.ts +++ b/packages/cli/src/error-codes.ts @@ -236,6 +236,7 @@ export const CLI_OWNED_ERROR_CODES = [ 'X_GUARD_BUILT_IN', 'X_REPRO_BUNDLE_INVALID', 'X_APP_MIGRATIONS_UNAPPLIED', + 'X_TASK_RUN_PRODUCTION', ] as const; /** @@ -464,6 +465,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliListedErrorCode, string>> = { X_REPRO_BUNDLE_INVALID: 'the file is not a repro bundle this version can open', X_APP_MIGRATIONS_UNAPPLIED: 'a serving role booted over a database missing migrations this build ships', + X_TASK_RUN_PRODUCTION: 'x tasks run refused to fire a task in production unasked', }; // One unconditional call, so a second package claiming one of the CLI's codes throws diff --git a/packages/cli/src/job-budget.test.ts b/packages/cli/src/job-budget.test.ts index 350e2f5f3..8b1df0e5c 100644 --- a/packages/cli/src/job-budget.test.ts +++ b/packages/cli/src/job-budget.test.ts @@ -22,11 +22,14 @@ describe('the worker budget', () => { }); test('retire off: the worker budget, else the one every role drains on', () => { - // Less the cut-off's margin: the drain cancels a held job 2 s before its deadline. - expect(workerBudgetMs({ ...on, workerRetireMs: 0 })).toBe(23_000); + // Less core's reserve for the later hooks (a fifth, at most 2 s: the in-flight wait ends + // there, `ShutdownReason.inflightUntil`) and the cut-off's 2 s margin before that instant. + expect(workerBudgetMs({ ...on, workerRetireMs: 0 })).toBe(21_000); expect(workerBudgetMs({ ...on, workerRetireMs: 0, workerDeadlineMs: 2 * HOUR })).toBe( - 2 * HOUR - 2_000, + 2 * HOUR - 4_000, ); + // A short budget: the reserve is a fifth (1 s of 5 s), the margin half of what is left. + expect(workerBudgetMs({ ...on, workerRetireMs: 0, workerDeadlineMs: 5_000 })).toBe(2_000); }); test('nothing declared is core’s defaults, the retire on', () => { @@ -68,9 +71,10 @@ describe('X_JOB_OUTLASTS_DRAIN', () => { test('retire off grades against the drain budget', () => { const off = { ...on, workerRetireMs: 0 }; - expect(jobBudgetFindings([job('a', 23_000)], off)).toEqual([]); - // '24s' under a 25 s budget: every deploy cancels it at 23 s. - expect(jobBudgetFindings([job('b', 24_000)], off).map((one) => one.code)).toEqual([ + expect(jobBudgetFindings([job('a', 21_000)], off)).toEqual([]); + // '22s' under a 25 s budget: every deploy cancels it at 21 s, 2 s before the in-flight wait + // ends at 23 s. + expect(jobBudgetFindings([job('b', 22_000)], off).map((one) => one.code)).toEqual([ 'X_JOB_OUTLASTS_DRAIN', ]); }); diff --git a/packages/cli/src/job-budget.ts b/packages/cli/src/job-budget.ts index b56905e0b..5794f33c4 100644 --- a/packages/cli/src/job-budget.ts +++ b/packages/cli/src/job-budget.ts @@ -8,6 +8,7 @@ import { DRAIN_DEADLINE_DEFAULT_MS, finiteCount, isUltimateError, + laterHooksReserveMs, WORKER_DRAIN_DEADLINE_MAX_MS, WORKER_RETIRE_DEFAULT_MS, } from '@ultimat3/core'; @@ -27,7 +28,8 @@ type WorkerDrain = Pick<Partial<DrainConfig>, 'deadlineMs' | 'workerDeadlineMs' /** * The retire when on, for it aborts nothing; else when a SIGTERM drain CANCELS a held job, which is - * the cut-off's `cancelAt` (`worker-drain-cutoff.ts`), a margin before the deadline itself. + * the cut-off's `cancelAt` (`worker-drain-cutoff.ts`): a margin before core's in-flight wait ends, + * which is itself the later hooks' reserve before the deadline (`ShutdownReason.inflightUntil`). */ export function workerBudgetMs(drain: WorkerDrain | undefined): number { // Screened here, not trusted: `defineConfig` screens an app's config, but this is exported, and a @@ -44,7 +46,7 @@ export function workerBudgetMs(drain: WorkerDrain | undefined): number { drain?.workerDeadlineMs ?? drain?.deadlineMs ?? DRAIN_DEADLINE_DEFAULT_MS, 1, ); - return cutoffTimes(deadline, 0).cancelAt; + return cutoffTimes(deadline, 0, deadline - laterHooksReserveMs(deadline)).cancelAt; } function outlastsFinding(job: BudgetedJob, limitMs: number, budgetMs: number): Finding { diff --git a/packages/cli/src/mcp-errors.ts b/packages/cli/src/mcp-errors.ts index f419c3754..384a6cbd0 100644 --- a/packages/cli/src/mcp-errors.ts +++ b/packages/cli/src/mcp-errors.ts @@ -402,6 +402,10 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = { X_HEAVY_LEDGER_UNAVAILABLE: 'x heavy status --json', X_HEAVY_MEMORY_INVALID: 'export ULTIMATE_HEAVY_MEMORY=8g', X_HEAVY_COMMAND_NOT_FOUND: 'x heavy run --json -- bun test', + // `X_SEED_ENVIRONMENT`'s form: which task to consent to is what this table cannot know, and the + // raised error's own `fix:` carries the named invocation; `ULTIMATE_TASK_RUN` stays in the cause. + X_TASK_RUN_PRODUCTION: + 'x tasks list --json # then name the task: x tasks run <name> --production --json', }; const isCliCode = (code: string): code is CliErrorCode => diff --git a/packages/cli/src/serve-graph-ceilings-fixture.ts b/packages/cli/src/serve-graph-ceilings-fixture.ts index 65e5f00a5..e8d17907d 100644 --- a/packages/cli/src/serve-graph-ceilings-fixture.ts +++ b/packages/cli/src/serve-graph-ceilings-fixture.ts @@ -360,8 +360,17 @@ * (`define-driver`, `driver-{counters,delete,kit-types,repo-reads,repo-writes,scope, * versioned-write,write-scope}.ts`) — `action/src/tx-scope.ts` now reads `memoryTxOpen` off * `@ultimat3/entity/adapter`, which evaluates the whole subpath barrel. + * lowered 1011 → 1003, measured 1003 (2026-11-19, r9 final integration, metafile walk against + * origin/main's 989): `memoryTxOpen` moved to the one-export leaf `@ultimat3/entity/internal/ + * memory-tx` (`entity/src/memory-tx-entry.ts`), so the driver kit left this graph (−10, +1), and + * `cache/src/tier-bounds.ts` (+1) is `tiers.ts` split at its 500-line ceiling (the three + * `assertFinite*` screens). The 14 modules on this graph since origin/main, every one named: + * `cache/src/{shared-scopes,tier-bounds}.ts`, `cli/src/{app-config-load,runtime-database-ssl, + * runtime-jobs}.ts`, `db/src/{column-drop,migrate-dev-fix}.ts`, `entity/src/{instant-range, + * memory-tx-entry,pg-sql-in,uuid-text}.ts`, `http/src/{fault-report,wire-dates-cap}.ts`, + * `jobs/src/retry-default.ts`. */ -export const MIGRATE_CEILING = 1011; +export const MIGRATE_CEILING = 1003; // One import site for the test, which reads both pins from here. export { SERVING_ROLE_CEILING } from './serve-graph-serving-ceiling-fixture'; diff --git a/packages/cli/src/serve-graph-serving-ceiling-fixture.ts b/packages/cli/src/serve-graph-serving-ceiling-fixture.ts index 4421e2084..abc079c8e 100644 --- a/packages/cli/src/serve-graph-serving-ceiling-fixture.ts +++ b/packages/cli/src/serve-graph-serving-ceiling-fixture.ts @@ -350,5 +350,14 @@ * `db/src/migrate-dev-fix.ts`, `cache/src/shared-scopes.ts` and `http/src/wire-dates-cap.ts` (the * three on `MIGRATE_CEILING`) and `cli/src/runtime-cache-frame.ts` (the bust frame's codec, split * from `runtime-cache.ts`). `runtime-jobs.ts` and the entity driver kit were already on this graph. + * raised 1562 → 1564, measured 1564 (2026-11-19, r9 final integration, metafile walk against + * origin/main's 1548): `entity/src/memory-tx-entry.ts` (`memoryTxOpen`'s one-export leaf, v-arch + * F13: off the barrel, and off `/adapter`, whose driver kit is ten modules) and + * `cache/src/tier-bounds.ts` (`tiers.ts` split at its 500-line ceiling). The 16 modules on this + * graph since origin/main, every one named: `auth/src/mfa-handoff.ts`, `cache/src/{shared-scopes, + * tier-bounds}.ts`, `cli/src/{role-select,runtime-cache-frame,runtime-cache-ttl, + * runtime-database-ssl}.ts`, `db/src/{column-drop,migrate-dev-fix}.ts`, `entity/src/{instant-range, + * memory-tx-entry,pg-sql-in,uuid-text}.ts`, `http/src/{fault-report,wire-dates-cap}.ts`, + * `jobs/src/retry-default.ts`. */ -export const SERVING_ROLE_CEILING = 1562; +export const SERVING_ROLE_CEILING = 1564; diff --git a/packages/cli/src/serve-graph-web-ceiling-fixture.ts b/packages/cli/src/serve-graph-web-ceiling-fixture.ts index 572218334..7ec20d1ff 100644 --- a/packages/cli/src/serve-graph-web-ceiling-fixture.ts +++ b/packages/cli/src/serve-graph-web-ceiling-fixture.ts @@ -305,5 +305,9 @@ * Nothing web-only. * raised 1758 → 1762, measured 1762 (2026-11-19, r9 verification fixes): the four on * `SERVING_ROLE_CEILING`. Nothing web-only. + * raised 1762 → 1764, measured 1764 (2026-11-19, r9 final integration, metafile walk against + * origin/main's 1748): the two on `SERVING_ROLE_CEILING`, `entity/src/memory-tx-entry.ts` and + * `cache/src/tier-bounds.ts`. Since origin/main: exactly the 16 that `SERVING_ROLE_CEILING` names. + * Nothing web-only. */ -export const WEB_ROLE_CEILING = 1762; +export const WEB_ROLE_CEILING = 1764; diff --git a/packages/core/CLAUDE.md b/packages/core/CLAUDE.md index e51b170d2..b84dc084e 100644 --- a/packages/core/CLAUDE.md +++ b/packages/core/CLAUDE.md @@ -20,7 +20,7 @@ change to every package. A row or rule marked `†` has its full text in | Time | take a `Clock` (a `SleepClock` to wait); `Date.now()` / `new Date()` only in `clock.ts`; a waiting timer only in `sleep-clock.ts` | | Context | never thread `ctx` as a parameter — `useContext()` | | A value ambient across an `await` | `asyncContext<T>(subject)` from `async-context.ts`, in **every** package — never `new AsyncLocalStorage` | -| Exports | explicit in `src/index.ts`; no `export *`. Six public subpaths (`./adapter`, `./page`, `./outbound`, `./redis`, `./render-node`, `./render-nodes`), one internal (`./internal/error-status`); nothing that loads a titles table joins `./page` (`page-bundle.test.ts`); an app imports `defineError` there (`define-error-bytes.test.ts`) † | +| Exports | explicit in `src/index.ts`; no `export *`. Six public subpaths (`./adapter`, `./page`, `./outbound`, `./redis`, `./render-node`, `./render-nodes`), two internal (`./internal/error-status`, `./internal/sse-frames`: the one SSE frame reader); nothing that loads a titles table joins `./page` (`page-bundle.test.ts`); an app imports `defineError` there (`define-error-bytes.test.ts`) † | | Files | < 200 LOC, 500 hard ceiling, one responsibility, `kebab-case.ts`, test beside source | | Type claims | `type-pins.ts`, never a `.test.ts` — `tsconfig.json` excludes tests | @@ -174,7 +174,7 @@ server-only, never on `page.ts`. One call site per recorder; a second is the bug - **Three OTLP variables, three codes** — `X_OTLP_ENDPOINT_INVALID`, `X_OTLP_HEADERS_INVALID`, `X_OTLP_PROTOCOL_UNSUPPORTED`. A header KEY is in the cause/fix/meta; its VALUE never is. - **A cause is cut at 4 KiB in the constructor** (`boundedCause`); schema's copy is pinned by `single-line-pin.test.ts`. -- `error-reporter.ts`: `ErrorReporter`, an `adapterSlot` (`installErrorReporter` on `./adapter`; `configureErrorReporting` keeps clock/release/environment/enabled only), no-op default, memory reporter for tests, Sentry transport (`error-reporter-sentry.ts`, optional export; it reads the answer: one warn per non-2xx status, a 429 pauses for its `Retry-After` (60 s unstated), bodies cancelled; a DSN refusal never echoes its userinfo). Full rule: `docs/history/core.md`. `'browser'`: only cli's `client-errors-routes.ts`, one `X_CLIENT_ERROR` per report. +- `error-reporter.ts`: `ErrorReporter`, an `adapterSlot` (`installErrorReporter` on `./adapter`; `configureErrorReporting` keeps clock/release/environment/enabled only), no-op default, memory reporter for tests, Sentry transport (`error-reporter-sentry.ts`, optional export; one warn per non-2xx, a 429 pauses; a DSN refusal never echoes its secret) †. `'browser'`: only cli's `client-errors-routes.ts`, one `X_CLIENT_ERROR` per report. - `METRICS_PATH` is served by `@ultimat3/cli`'s `metrics-endpoint.ts` on `METRICS_PORT` (9090), never the role's HTTP port; every role opens it. @@ -184,7 +184,7 @@ server-only, never on `page.ts`. One call site per recorder; a second is the bug - **`drain()`'s memo is published BEFORE the first hook runs** — a hook may re-enter `drain()` (`@ultimat3/http`'s `handle.stop()`), and `settleWithin` invokes hooks synchronously. - **The drain deadline is enforced** (`lifecycle-deadline.ts`): a hook overrunning the whole drain's budget is abandoned and logged (`X_SHUTDOWN_TIMEOUT`); real monotonic time, never the injected `clock`. Full rule: `docs/history/core.md`. -- **The in-flight wait leaves the hooks behind it a slice**: with an `inflight`/`close` hook, `waitForIdle` stops `min(2s, deadlineMs / 5)` early (`laterHooksReserveMs`): a stuck request never starves the OTLP flush or pool close. Total unchanged. +- **The in-flight wait leaves the hooks behind it a slice**: with an `inflight`/`close` hook, `waitForIdle` stops `min(2s, deadlineMs / 5)` early (`laterHooksReserveMs`, `drain-deadline.ts`): a stuck request never starves the OTLP flush or pool close. Total unchanged. Handed to every hook as `ShutdownReason.inflightUntil`; a role that cuts its own work measures back from it. - **An exit after a drain is `drainExitCode()`** — 70 when work was abandoned (`X_SHUTDOWN_TIMEOUT`), else 0. Never a literal `process.exit(0)`. - **`close` hooks run last-registered first; the other phases as registered** (`runPhase`). No fourth phase. - **Who a health endpoint tells what is ONE rule, here** (`health-disclosure.ts`): `healthBody` + diff --git a/packages/core/README.md b/packages/core/README.md index c44b45a4f..f49a381c1 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -21,6 +21,7 @@ JSON.stringify({ dsn }); // the value never prints: a Secret redacts by value, a | an APP code's one declaration — title, HTTP status, retry and class — `defineError()` | `define-error.ts` | | an action's or a query's `errors:` — `checkDeclaredErrors` (the list), `judgeThrown` / `enforceDeclared` / `withDeclaredErrors` (a throw out of a handler; `X_ERROR_UNDECLARED` in test and dev, `undeclared_errors_total` in production), `describeDeclaredErrors` (a tool's description); the OpenAPI half `withDeclaredResponses`; the contract's source scan `scanHandlerSource` + `definedErrorClassCodes` (test-time). The status is passed in: `@ultimat3/http` is above this package | `declared-errors.ts`, `declared-errors-openapi.ts`, `declared-errors-scan.ts` | | the app's half of the HTTP status table, written by `defineError` and `@ultimat3/http`'s `registerErrorStatus` — internal, on `@ultimat3/core/internal/error-status` only | `error-status-declared.ts` | +| the one SSE frame reader (`takeFrames`), read by `clientStream` and `@ultimat3/mcp`'s remote client — internal, on `@ultimat3/core/internal/sse-frames` only | `sse-frames.ts` | | the one lazy `AsyncLocalStorage`, every ambient scope in the framework | `async-context.ts` | | request context on that seam | `context.ts` | | `Actor` (`user \| service \| agent \| anonymous`) | `actor.ts` | @@ -107,8 +108,8 @@ JSON.stringify({ dsn }); // the value never prints: a Secret redacts by value, a | graceful drain, `/healthz`, `/readyz` | `lifecycle.ts` | | what a health endpoint tells whom — `healthBody(report, role, detailed)`, `healthPeerListed(peers, address)`, `DEFAULT_HEALTH_DETAIL_PEERS`; the one rule `@ultimat3/http` and the sync node's own listener both call | `health-disclosure.ts` | | the readiness grace between `/readyz` → 503 and the listener closing (`drain.readinessGraceMs`) | `lifecycle-grace.ts` | -| the drain budget's default and domain (`drain.deadlineMs`, 25 s, 1–3600000 ms; the worker's optional `drain.workerDeadlineMs`, 1–86400000 ms; its `drain.workerRetireMs`, an hour, 0–86400000 ms) — `DRAIN_DEADLINE_DEFAULT_MS`, `DRAIN_DEADLINE_MAX_MS`, `WORKER_DRAIN_DEADLINE_MAX_MS`, `WORKER_RETIRE_DEFAULT_MS` | `drain-deadline.ts` | -| `jobs.concurrency`'s default and domain — one slot count for every queue a worker serves, or a table per queue (`{ banks: 4, 'banks-long': 2 }`; a queue the table does not name runs at the default). `JOBS_CONCURRENCY_DEFAULT` (8), `type JobsConcurrency` | `config-jobs.ts` | +| the drain budget's default and domain (`drain.deadlineMs`, 25 s, 1–3600000 ms; the worker's optional `drain.workerDeadlineMs`, 1–86400000 ms; its `drain.workerRetireMs`, an hour, 0–86400000 ms) — `DRAIN_DEADLINE_DEFAULT_MS`, `DRAIN_DEADLINE_MAX_MS`, `WORKER_DRAIN_DEADLINE_MAX_MS`, `WORKER_RETIRE_DEFAULT_MS`; `laterHooksReserveMs(deadlineMs)`, the slice the in-flight wait leaves the hooks behind it (a fifth, at most 2 s; its end is `ShutdownReason.inflightUntil`) | `drain-deadline.ts` | +| `jobs.concurrency`'s default and domain — one slot count for every queue a worker serves, or a table per queue (`{ banks: 4, 'banks-long': 2 }`; a queue the table does not name runs at the default). `JOBS_CONCURRENCY_DEFAULT` (8), `type JobsConcurrency`; `JOBS_MAX_ATTEMPTS_DEFAULT` (3), `jobs.maxAttempts`' default and `@ultimat3/jobs`' `DEFAULT_RETRY.attempts` | `config-jobs.ts` | | SIGTERM/SIGINT → the one drain; on Windows also SIGHUP (console close) and SIGBREAK (Ctrl-Break) — `drainSignals(platform)`. With `exit: true` the process exits `drainExitCode()`: `0`, or `DRAIN_TIMEOUT_EXIT_CODE` (70, `EX_SOFTWARE`) when work was abandoned at the deadline (`X_SHUTDOWN_TIMEOUT`) | `lifecycle-signals.ts` | | is this directory inside a `bun build --compile` binary? `isCompiledBundle(import.meta.dir)` — `/$bunfs/` and Windows' `B:\~BUN\` | `bunfs.ts` | | which network an IP literal belongs to — `classifyAddress`, for SSRF screens; `peerAddressClass`, for a check that trusts a caller or a local name | `address-class.ts` | diff --git a/packages/core/package.json b/packages/core/package.json index 4db1630b5..ea5124f3a 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -33,6 +33,7 @@ "./adapter": "./src/adapter.ts", "./page": "./src/page.ts", "./internal/error-status": "./src/error-status-declared.ts", + "./internal/sse-frames": "./src/sse-frames.ts", "./outbound": "./src/outbound-subpath.ts", "./redis": "./src/redis-client.ts", "./render-node": "./src/render-node.ts", diff --git a/packages/core/src/client-stream.test.ts b/packages/core/src/client-stream.test.ts index 34c31e76e..deedf4b53 100644 --- a/packages/core/src/client-stream.test.ts +++ b/packages/core/src/client-stream.test.ts @@ -5,11 +5,12 @@ import { afterEach, describe, expect, test } from 'bun:test'; import { IDEMPOTENCY_HEADER } from './client-dispatch'; import { rescope } from './client-scope'; -import { clientStream, takeFrames } from './client-stream'; +import { clientStream } from './client-stream'; import { failure, fakeFetch, heldFetch, json, recordingSink } from './client-transport-fixture'; import { isUltimateError } from './errors'; import { RECORDS_HEADER } from './record-envelope'; import { sessionIsLost } from './session-lost'; +import { takeFrames } from './sse-frames'; import { DATES_HEADER, wireDatePaths } from './wire-dates'; afterEach(() => { diff --git a/packages/core/src/client-stream.ts b/packages/core/src/client-stream.ts index d3168a1d7..bd5d1f766 100644 --- a/packages/core/src/client-stream.ts +++ b/packages/core/src/client-stream.ts @@ -11,42 +11,12 @@ import { settleAnswer } from './client-transport'; import { notifyClientWrite } from './client-writes'; import { RECORDS_HEADER } from './record-envelope'; import { pageClient } from './record-sink'; +import { takeFrames } from './sse-frames'; import { DATES_HEADER, reviveWireDates } from './wire-dates'; /** What `clientStream` reads: a write's request, never a raw body or a flight. */ export type StreamRequest = StreamDispatch; -interface Frame { - readonly event: string; - readonly data: string; - /** The `x-ultimate-dates` value for this frame's data, when the server named any. */ - readonly dates?: string; -} - -/** Splits a growing buffer into complete frames; the incomplete tail is handed back. */ -export function takeFrames(buffer: string): { readonly frames: Frame[]; readonly rest: string } { - const frames: Frame[] = []; - const blocks = buffer.split(/\r?\n\r?\n/); - const rest = blocks.pop() ?? ''; - for (const block of blocks) { - let event = 'message'; - let dates: string | undefined; - const data: string[] = []; - for (const line of block.split(/\r?\n/)) { - // A `:` line is a comment — the server's keep-alive. - if (line.startsWith(':')) continue; - if (line.startsWith('event:')) event = line.slice(6).trim(); - else if (line.startsWith('dates:')) dates = line.slice(6).trim(); - else if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, '')); - } - if (data.length > 0) { - const text = data.join('\n'); - frames.push(dates === undefined ? { event, data: text } : { event, data: text, dates }); - } - } - return { frames, rest }; -} - export async function* clientStream<TChunk = unknown, TOutput = unknown>( req: StreamRequest, ): AsyncGenerator<TChunk, TOutput, undefined> { diff --git a/packages/core/src/config-defaults.ts b/packages/core/src/config-defaults.ts index 2b3016558..0238caf11 100644 --- a/packages/core/src/config-defaults.ts +++ b/packages/core/src/config-defaults.ts @@ -6,6 +6,7 @@ import { JOBS_CONCURRENCY_DEFAULT, JOBS_DEAD_RETENTION_MS_DEFAULT, JOBS_DONE_RETENTION_MS_DEFAULT, + JOBS_MAX_ATTEMPTS_DEFAULT, JOBS_OUTBOX_RETENTION_MS_DEFAULT, } from './config-jobs'; import { DRAIN_DEADLINE_DEFAULT_MS, WORKER_RETIRE_DEFAULT_MS } from './drain-deadline'; @@ -46,9 +47,9 @@ export function configDefaults(): Omit<AppConfig, Sectioned> { jobs: { queues: ['default'], concurrency: JOBS_CONCURRENCY_DEFAULT, - // 3 is `@ultimat3/jobs`' own default retry: the key is the worker's default for a job that - // declares none, so the default moves no app that never set it. - maxAttempts: 3, + // `@ultimat3/jobs`' own default retry reads the same constant: the key is the worker's default + // for a job that declares none, so the default moves no app that never set it. + maxAttempts: JOBS_MAX_ATTEMPTS_DEFAULT, backoff: 'exponential', visibilityTimeoutMs: 30_000, doneRetentionMs: JOBS_DONE_RETENTION_MS_DEFAULT, diff --git a/packages/core/src/config-jobs.ts b/packages/core/src/config-jobs.ts index 45efa8130..e7c526b1c 100644 --- a/packages/core/src/config-jobs.ts +++ b/packages/core/src/config-jobs.ts @@ -14,6 +14,13 @@ import { isJsonObject } from './json-object'; */ export const JOBS_CONCURRENCY_DEFAULT = 8; +/** + * `jobs.maxAttempts` when no layer says, and `@ultimat3/jobs`' `DEFAULT_RETRY.attempts`: the + * worker's default for a job that declares no retry. ONE constant, so the config default and the + * policy a factory's job falls back to cannot drift apart. + */ +export const JOBS_MAX_ATTEMPTS_DEFAULT = 3; + /** * `jobs.doneRetentionMs` when no layer says: how long a `done` row and its step records are kept * before the boot's hourly purge deletes them. Two weeks — every incident is read inside it, and diff --git a/packages/core/src/drain-deadline.test.ts b/packages/core/src/drain-deadline.test.ts index 0770fc7ef..c43560294 100644 --- a/packages/core/src/drain-deadline.test.ts +++ b/packages/core/src/drain-deadline.test.ts @@ -6,6 +6,7 @@ import { DRAIN_DEADLINE_DEFAULT_MS, DRAIN_DEADLINE_MAX_MS, drainDeadlineIssue, + laterHooksReserveMs, } from './drain-deadline'; import { drainDeadlineMs, resetLifecycle } from './lifecycle'; @@ -44,3 +45,11 @@ describe('the drain budget', () => { expect(drainDeadlineIssue(DRAIN_DEADLINE_MAX_MS + 1)).toContain('at most 3600000'); }); }); + +describe('laterHooksReserveMs', () => { + test('a fifth of the budget, at most 2 s, kept from the in-flight wait for the hooks behind it', () => { + expect(laterHooksReserveMs(25_000)).toBe(2_000); + expect(laterHooksReserveMs(5_000)).toBe(1_000); + expect(laterHooksReserveMs(7)).toBe(1); + }); +}); diff --git a/packages/core/src/drain-deadline.ts b/packages/core/src/drain-deadline.ts index 14e81cf89..937c59b78 100644 --- a/packages/core/src/drain-deadline.ts +++ b/packages/core/src/drain-deadline.ts @@ -33,6 +33,15 @@ export const WORKER_DRAIN_DEADLINE_MAX_MS = 86_400_000; */ export const WORKER_RETIRE_DEFAULT_MS = 3_600_000; +/** + * The slice of a `deadlineMs` drain the in-flight wait never spends, kept for the `inflight` and + * `close` hooks behind it: a fifth, at most 2 s. The lifecycle hands its end to every hook as + * `ShutdownReason.inflightUntil`; `x verify`'s `X_JOB_OUTLASTS_DRAIN` grades against the same one. + */ +export function laterHooksReserveMs(deadlineMs: number): number { + return Math.min(2_000, Math.floor(deadlineMs / 5)); +} + const DEADLINE_KEY = 'drain.deadlineMs'; const WORKER_DEADLINE_KEY = 'drain.workerDeadlineMs'; const WORKER_RETIRE_KEY = 'drain.workerRetireMs'; diff --git a/packages/core/src/framework-env.ts b/packages/core/src/framework-env.ts index 024221096..11430e4dd 100644 --- a/packages/core/src/framework-env.ts +++ b/packages/core/src/framework-env.ts @@ -59,6 +59,7 @@ export const FRAMEWORK_ENV: readonly FrameworkEnvName[] = [ ...contract('cli', 'PGSSLMODE'), ...toggles('cli', 'OTEL_SDK_DISABLED'), ...internal('cli', 'ULTIMATE_SEED_TIER', 'ULTIMATE_STATE_DIR', 'ULTIMATE_BUILD_CAPTURE'), + ...internal('cli', 'ULTIMATE_TASK_RUN'), ...internal('cli', 'ULTIMATE_DEV_CHILD', 'ULTIMATE_DEV_SUPERVISOR_PID', 'X_ENV'), ...internal('cli', 'ULTIMATE_KEEP_GLOBAL_CLI', 'ULTIMATE_VERIFY_STEP', 'CI_RUNNER'), ...host('cli', 'CI', 'GITHUB_SHA', 'GITHUB_BASE_REF', 'EDITOR', 'VISUAL', 'USERPROFILE'), diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 3a62be1b0..560f414d5 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -210,6 +210,7 @@ export { JOBS_CONCURRENCY_DEFAULT, JOBS_DEAD_RETENTION_MS_DEFAULT, JOBS_DONE_RETENTION_MS_DEFAULT, + JOBS_MAX_ATTEMPTS_DEFAULT, JOBS_OUTBOX_RETENTION_MS_DEFAULT, type JobsConcurrency, } from './config-jobs'; @@ -331,6 +332,7 @@ export { } from './dev-secrets'; export { DRAIN_DEADLINE_DEFAULT_MS, + laterHooksReserveMs, WORKER_DRAIN_DEADLINE_MAX_MS, WORKER_RETIRE_DEFAULT_MS, } from './drain-deadline'; diff --git a/packages/core/src/lifecycle.ts b/packages/core/src/lifecycle.ts index 97f6491f2..2ada5730b 100644 --- a/packages/core/src/lifecycle.ts +++ b/packages/core/src/lifecycle.ts @@ -6,7 +6,7 @@ import { installedBuildId } from './build-id'; import { type Clock, systemClock } from './clock'; import type { ReadinessMode } from './config-health'; import { assertReadinessMode } from './config-health'; -import { DRAIN_DEADLINE_DEFAULT_MS } from './drain-deadline'; +import { DRAIN_DEADLINE_DEFAULT_MS, laterHooksReserveMs as reserveOf } from './drain-deadline'; import { UltimateError } from './errors'; import { finiteCount } from './finite-option'; import { settleWithin } from './lifecycle-deadline'; @@ -288,7 +288,7 @@ function remainingBudget(reason: ShutdownReason): number { /** The slice of the budget kept for `inflight` and `close` hooks: a fifth, at most 2s; none without one. */ function laterHooksReserveMs(): number { if (!registrations.some((entry) => entry.phase !== 'accept')) return 0; - return Math.min(2_000, Math.floor(deadlineMs / 5)); + return reserveOf(deadlineMs); } async function runPhase(phase: ShutdownPhase, reason: ShutdownReason): Promise<void> { diff --git a/packages/core/src/sse-frames.ts b/packages/core/src/sse-frames.ts new file mode 100644 index 000000000..5bf1d474a --- /dev/null +++ b/packages/core/src/sse-frames.ts @@ -0,0 +1,42 @@ +// `@ultimat3/core/internal/sse-frames` — the ONE reader of a `text/event-stream` body's frames: the +// browser's `clientStream` and `@ultimat3/mcp`'s remote client both split SSE here. INTERNAL and a +// leaf: a package's wire reader, never an app's, and it imports nothing. + +/** One complete frame: its `event` (`message` when unnamed) and its `data:` lines joined. */ +export interface SseFrame { + readonly event: string; + readonly data: string; + /** The `x-ultimate-dates` value for this frame's data, when the server named any. */ + readonly dates?: string; +} + +/** + * Splits a growing buffer into complete frames; the incomplete tail is handed back. A frame with + * no `data:` line (a keep-alive comment, a bare `event:`) is no frame. A whole body read at once + * is `takeFrames(`${text}\n\n`)`: its last frame needs no blank line after it. + */ +export function takeFrames(buffer: string): { + readonly frames: SseFrame[]; + readonly rest: string; +} { + const frames: SseFrame[] = []; + const blocks = buffer.split(/\r?\n\r?\n/); + const rest = blocks.pop() ?? ''; + for (const block of blocks) { + let event = 'message'; + let dates: string | undefined; + const data: string[] = []; + for (const line of block.split(/\r?\n/)) { + // A `:` line is a comment — the server's keep-alive. + if (line.startsWith(':')) continue; + if (line.startsWith('event:')) event = line.slice(6).trim(); + else if (line.startsWith('dates:')) dates = line.slice(6).trim(); + else if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, '')); + } + if (data.length > 0) { + const text = data.join('\n'); + frames.push(dates === undefined ? { event, data: text } : { event, data: text, dates }); + } + } + return { frames, rest }; +} diff --git a/packages/http/CLAUDE.md b/packages/http/CLAUDE.md index c1fd48bf8..c6a9adcce 100644 --- a/packages/http/CLAUDE.md +++ b/packages/http/CLAUDE.md @@ -137,7 +137,7 @@ Owned request lifecycle over `Bun.serve`. Tier 2. `markReady()`, `drain()`, the payloads) — never a private state or in-flight counter. - **`stop()` hands its two hooks back ABOVE its early return** (`packages/http/e2e/server.e2e.test.ts` reads `shutdownHookCount()`). -- **`compress` is the last stage and has no option** (`compress.ts`, `compress-read.ts`): `zstd` then `gzip` by weight; a 304's validator is its 200's (`etag-form.ts`); `private`/`no-store`/`no-cache`/`no-transform` is identity (BREACH); a refused response is the SAME object. An `immutable` asset is coded ONCE in the background at br 11 / zstd 19 / gzip 9 (`compress-precode.ts`, 2 keys at a time; a coder that throws is logged, never unhandled), and later hits are lookups. ‡ +- **`compress` is the last stage and has no option** (`compress.ts`, `compress-read.ts`): `zstd` then `gzip` by weight; a 304's validator is its 200's (`etag-form.ts`); `private`/`no-store`/`no-cache`/`no-transform` is identity (BREACH); a refused response is the SAME object. An `immutable` asset is pre-coded once (`compress-precode.ts`). ‡ ## Rules — errors and the problem document @@ -237,7 +237,8 @@ Full rules and their reasons: [`docs/history/http-rate-limit.md`](../../docs/his | `error-titles.ts` | the owned codes, titles and `retry-after` classes, registered at import — the one `sideEffects` module. Server realm only: a browser reads title and delay off the body and `Retry-After` | | `correlation.ts` | the inbound request id and trace, read before the context and the span exist | | `forwarded.ts` | one hop-indexed reader for every header a trusted proxy writes | -| `peer-identity.ts` | Envoy XFCC -> `ctx.peer`, on that same trust rule | +| `peer-identity.ts` | Envoy XFCC -> `ctx.peer`, on that same trust rule, read from the right | +| `wire-dates-cap.ts` | `cappedWireDates`: `x-ultimate-dates` or none past 4 KB, one warn per route | | `deadline.ts` | the per-request `AbortController`, the timer and `X_TIMEOUT` | | `csrf.ts` | the origin proof an unsafe method from a browser must carry, signed in or not | | `webhook-verify.ts` | the INBOUND webhook: canonical string, constant-time mac, replay window. Outbound is `@ultimat3/jobs`' `webhook()` | diff --git a/packages/jobs/CLAUDE.md b/packages/jobs/CLAUDE.md index 65c581432..c34c1ec87 100644 --- a/packages/jobs/CLAUDE.md +++ b/packages/jobs/CLAUDE.md @@ -209,7 +209,7 @@ Long form: [`docs/history/jobs.md`](../../docs/history/jobs.md), "Moved 2026-10- | `driver-pg-ddl.ts` | `SQL_JOBS_TABLE` (the ONE install), `JOBS_TABLE_STORAGE` (fillfactor 80), the hot tables' autovacuum as `tableStorage()` in `JOBS_STORAGE`, drift-checked. Comments carry no `;` and no `'` | | `driver-pg-rows.ts` | a Postgres row → a wire record: `JobRow`/`StepRow`/`BackfillRow` and their mappings | | `driver-memory.ts` / `claim-exhausted.ts` | `x dev` / tests; a buried row's log line and `onSettled`, told beside the claim pass (`burialTeller`) and started only inside its debt's grace | -| `retry.ts` / `retry-default.ts` | the dead-letter decision over core's `backoffDelay`; the app's default (`jobs.maxAttempts`/`backoff`), resolved when `handle.retry` is READ | +| `retry.ts` / `retry-default.ts` | the dead-letter decision over core's `backoffDelay`; the app's default (`jobs.maxAttempts`/`backoff`), resolved when `handle.retry` is READ; `DEFAULT_RETRY.attempts` is core's `JOBS_MAX_ATTEMPTS_DEFAULT` | | `retry-classification.ts` | the other half: what the thrown error says, and the stop reason | | `retry-jitter.ts` | `retry.jitter` refused at `job()` unless a `JitterMode` (a v30 boolean names its mapping) | | `execute-unwind.ts` / `execute-ctx.ts` | a saga failed for good; caller ctx | @@ -241,8 +241,7 @@ Long form: [`docs/history/jobs.md`](../../docs/history/jobs.md), "Moved 2026-10- | `counters.ts` / `counter-batch.ts` | bucket arithmetic, `nackOutcome`, the memory counters; the pg driver's per-process batch, flushed every 10 s and on close | | `driver-memory-operator.ts` / `driver-pg-operator.ts` | each driver's operator members | | `progress.ts` / `settled.ts` / `redact-input.ts` | the progress throttle; the `onSettled` runner; a payload as an operator reads it | -| `settled-types.ts` / `driver-settle.ts` / `settle-redrive.ts` / `scheduler-upkeep.ts` | what `onSettled` is handed; the settle fence and the `onSettled` debt contract; the leader's re-drive of lost debts; the leader's cadence (counter fold, re-drive) | -| `driver-memory-settle.ts` / `driver-pg-settle-debt.ts` / `driver-redis-settle.ts` | the `onSettled` debt per driver: a map, `x_jobs.settle_owed`, the `owed` ZSET — held equal by `@ultimat3/testing`'s `SETTLE_DEBT_CHECKS` | +| `settled-types.ts` / `*settle*.ts` / `scheduler-upkeep.ts` | `onSettled`'s input, fence and debt (one per driver, held equal by `SETTLE_DEBT_CHECKS`); the leader's re-drive and cadence † | | `scheduler-state.ts` | `SchedulerState`, `fire`, `readWatermarks` (one read a round), the memory watermark | | `scheduler-leader.ts` / `scheduler-occurrences.ts` | `LeaderElection` + `soleLeader`; which occurrences fall in a window | | `idle-backoff.ts` / `enqueue-signal.ts` | the wait both polling loops share, and the rest (`restAfter`); the two wake signals and `wakeIsLive` | diff --git a/packages/jobs/src/retry-core-parity.test.ts b/packages/jobs/src/retry-core-parity.test.ts index 4ac6834fe..aa6963514 100644 --- a/packages/jobs/src/retry-core-parity.test.ts +++ b/packages/jobs/src/retry-core-parity.test.ts @@ -3,7 +3,12 @@ // a delegation is only equivalent if it is equivalent everywhere a caller can reach. import { describe, expect, test } from 'bun:test'; -import { backoffDelay, type JitterMode } from '@ultimat3/core'; +import { + backoffDelay, + defineConfig, + type JitterMode, + JOBS_MAX_ATTEMPTS_DEFAULT, +} from '@ultimat3/core'; import type { BackoffStrategy, RetryPolicy } from './retry'; import { backoffDelayMs, DEFAULT_RETRY, retrySchedule } from './retry'; @@ -146,3 +151,10 @@ describe('invalid inputs answer core’s number, not the old one', () => { expect(backoffDelayMs(policy, 0)).toBe(1_000); }); }); + +describe('the default attempt count is stated once, in core', () => { + test('DEFAULT_RETRY and an unset jobs.maxAttempts both read JOBS_MAX_ATTEMPTS_DEFAULT', () => { + expect(DEFAULT_RETRY.attempts).toBe(JOBS_MAX_ATTEMPTS_DEFAULT); + expect(defineConfig({ name: 'parity' }).jobs.maxAttempts).toBe(JOBS_MAX_ATTEMPTS_DEFAULT); + }); +}); diff --git a/packages/jobs/src/retry-default.ts b/packages/jobs/src/retry-default.ts index a4cbcab09..57517ae2b 100644 --- a/packages/jobs/src/retry-default.ts +++ b/packages/jobs/src/retry-default.ts @@ -41,7 +41,9 @@ export function resolvedRetry(declared: RetryPolicy | undefined): RetryPolicy { // `=== DEFAULT_RETRY` is the identity sentinel this replaces, kept ONLY so the factories outside // this package that still pass `definition.retry ?? DEFAULT_RETRY` (`@ultimat3/notify`'s // `notifier.ts`, `@ultimat3/scraping`'s `scrape.ts`) keep the app's default until they pass - // `undefined`. Delete it with the last of them; nothing in this package relies on it. + // `undefined`. They cannot yet: the public `job()` refuses `retry: undefined`, and widening + // `JobDefinition.retry` is a public-shape change that waits on `next`. Delete it with the last + // of them; nothing in this package relies on it. if (declared === undefined || declared === DEFAULT_RETRY) return { ...DEFAULT_RETRY, ...installed }; if (installed === undefined) return { ...DEFAULT_RETRY, ...declared }; diff --git a/packages/jobs/src/retry.ts b/packages/jobs/src/retry.ts index eff7cd538..9ecf7bb4d 100644 --- a/packages/jobs/src/retry.ts +++ b/packages/jobs/src/retry.ts @@ -4,7 +4,7 @@ // are `ls`, `show`, `retry`, `cancel`, `drain`. import type { BackoffCurve, JitterMode, Random } from '@ultimat3/core'; -import { backoffDelay } from '@ultimat3/core'; +import { backoffDelay, JOBS_MAX_ATTEMPTS_DEFAULT } from '@ultimat3/core'; import type { DurationInput } from './clock'; import { finiteDurationMs } from './clock'; @@ -44,7 +44,7 @@ export interface RetryPolicy { export type RetryReport = 'dead-letter' | 'every-attempt'; export const DEFAULT_RETRY = { - attempts: 3, + attempts: JOBS_MAX_ATTEMPTS_DEFAULT, backoff: 'exponential', delay: 1_000, maxDelay: 3_600_000, diff --git a/packages/jobs/src/worker-drain-cutoff.ts b/packages/jobs/src/worker-drain-cutoff.ts index 6f85fb2eb..a7e950c1a 100644 --- a/packages/jobs/src/worker-drain-cutoff.ts +++ b/packages/jobs/src/worker-drain-cutoff.ts @@ -3,6 +3,7 @@ // effect it interrupted. Only near the end of the drain budget is what is still running told to // stop (`cancel`), and a beat later what is still held goes back to the queue (`handBack`). +import type { ShutdownReason } from '@ultimat3/core'; import { logger, renderThrowable, systemClock } from '@ultimat3/core'; import type { DrainBudget } from './drain-wait'; import { JobDrainedError } from './errors'; @@ -104,27 +105,30 @@ export function armDrainCutoff( export function armWorkerCutoff(input: { readonly budget: DrainBudget; readonly workerId: string; - /** The shutdown's signal name, carried on the reason the bodies read. */ - readonly signal: string; + /** The shutdown that armed it: its signal name rides the reason the bodies read, and core's + * `inflightUntil` is where the cut-off measures back from (`cutoffTimes`). */ + readonly shutdown: ShutdownReason; readonly drain: AbortController; readonly held: HeldRuns; - /** `deadlineAt − inflightUntil` of the shutdown that armed it (`cutoffTimes`). */ - readonly reserveMs: number; }): DrainCutoff { - const { workerId, held } = input; + const { workerId, held, shutdown } = input; + const reserveMs = Math.max( + 0, + shutdown.deadlineAt - (shutdown.inflightUntil ?? shutdown.deadlineAt), + ); return armDrainCutoff( input.budget, { cancel: () => { if (held.size > 0) logger.warn('jobs.worker.drain-cancelling', { workerId, held: held.size }); - input.drain.abort(new JobDrainedError({ workerId, signal: input.signal })); + input.drain.abort(new JobDrainedError({ workerId, signal: shutdown.signal })); }, handBack: async () => { const handed = await held.handBackAll(); if (handed > 0) logger.warn('jobs.worker.drain-handed-back', { workerId, handed }); }, }, - input.reserveMs, + reserveMs, ); } diff --git a/packages/jobs/src/worker.ts b/packages/jobs/src/worker.ts index 4c75256dd..c274d992e 100644 --- a/packages/jobs/src/worker.ts +++ b/packages/jobs/src/worker.ts @@ -28,8 +28,7 @@ import { type ClaimAnswer, createClaimSweep } from './worker-claim-sweep'; import { armWorkerCutoff, type DrainCutoff } from './worker-drain-cutoff'; import { assertConcurrencyEnforceable, createFleetSlots } from './worker-fleet-slots'; import { createHeldRuns } from './worker-held'; -import type { ClaimLoop } from './worker-loop'; -import { createClaimLoop, fillsAsk } from './worker-loop'; +import { type ClaimLoop, createClaimLoop, fillsAsk } from './worker-loop'; import { resolveWorkerTimings } from './worker-options'; import { createProcessCap } from './worker-process-cap'; import { createQueueDepthPublisher } from './worker-queue-depth'; @@ -341,11 +340,9 @@ export function jobWorker(options: WorkerOptions): Worker { cutoff = armWorkerCutoff({ budget, workerId, - signal: shutdown.signal, + shutdown, // core owns the instant its in-flight wait ends; the cut-off lands a margin before drain: drainSignal, held: inFlight, - // Core owns the instant its in-flight wait ends; the cut-off lands a margin before it. - reserveMs: Math.max(0, shutdown.deadlineAt - (shutdown.inflightUntil ?? shutdown.deadlineAt)), }); }; diff --git a/packages/mcp/src/remote-wire.test.ts b/packages/mcp/src/remote-wire.test.ts new file mode 100644 index 000000000..9d414779c --- /dev/null +++ b/packages/mcp/src/remote-wire.test.ts @@ -0,0 +1,49 @@ +// The answer body of a remote MCP call, read as JSON or as SSE: only OUR id answers, notifications +// are listed by method, and the SSE reading is core's one frame reader (`takeFrames`), not a copy. + +import { describe, expect, test } from 'bun:test'; +import { readNotifications, readRpcAnswer } from './remote-wire'; + +const SSE = 'text/event-stream'; +const frame = (body: unknown): string => `event: message\ndata: ${JSON.stringify(body)}\n\n`; + +describe('readRpcAnswer', () => { + test('a JSON answer is the envelope; anything else is no answer', () => { + expect(readRpcAnswer('application/json', '{"id":1,"result":{}}', 1)).toEqual({ + id: 1, + result: {}, + }); + expect(readRpcAnswer('application/json', 'not json', 1)).toBeUndefined(); + }); + + test('an SSE answer skips interleaved requests and comments for the frame carrying our id', () => { + const body = `: keep-alive\n\n${frame({ method: 'ping', id: 9 })}${frame({ id: 1, result: { ok: true } })}`; + expect(readRpcAnswer(SSE, body, 1)).toEqual({ id: 1, result: { ok: true } }); + expect(readRpcAnswer(SSE, body, 2)).toBeUndefined(); + }); + + test('the last frame needs no blank line after it, and CRLF frames read the same', () => { + expect(readRpcAnswer(SSE, 'data: {"id":3,\r\ndata: "result":1}', 3)).toEqual({ + id: 3, + result: 1, + }); + expect(readRpcAnswer(`${SSE}; charset=utf-8`, 'data: {"id":4}\r\n\r\n', 4)).toEqual({ id: 4 }); + }); +}); + +describe('readNotifications', () => { + test('every notification method on an SSE answer, none on JSON', () => { + const body = `${frame({ method: 'notifications/progress' })}${frame({ id: 1, method: 'x' })}${frame({ method: 'notifications/message' })}`; + expect(readNotifications(SSE, body)).toEqual([ + 'notifications/progress', + 'notifications/message', + ]); + expect(readNotifications('application/json', body)).toEqual([]); + }); + + test('the module splits no SSE of its own', async () => { + const source = await Bun.file(new URL('./remote-wire.ts', import.meta.url)).text(); + expect(source).toContain("from '@ultimat3/core/internal/sse-frames'"); + expect(source).not.toContain("startsWith('data:')"); + }); +}); diff --git a/packages/mcp/src/remote-wire.ts b/packages/mcp/src/remote-wire.ts index 94d983aa9..4747241fd 100644 --- a/packages/mcp/src/remote-wire.ts +++ b/packages/mcp/src/remote-wire.ts @@ -3,8 +3,13 @@ // read out of it. No state lives here — `remote-client.ts` holds the era and the session. import { isJsonObject } from '@ultimat3/core'; +import { takeFrames } from '@ultimat3/core/internal/sse-frames'; import { META_PROTOCOL_VERSION } from './wire'; +/** Each frame's data of a whole SSE body, parsed: core's frame reader, the last frame unterminated. */ +const sseData = (text: string): readonly unknown[] => + takeFrames(`${text}\n\n`).frames.map((frame) => parseJson(frame.data)); + /** The answer body a streamable-HTTP server may send: a JSON-RPC response, or SSE carrying one. */ export function readRpcAnswer( contentType: string | null, @@ -12,13 +17,7 @@ export function readRpcAnswer( id: number, ): Record<string, unknown> | undefined { if (contentType?.toLowerCase().startsWith('text/event-stream') === true) { - for (const event of text.split(/\r?\n\r?\n/)) { - const data = event - .split(/\r?\n/) - .filter((line) => line.startsWith('data:')) - .map((line) => line.slice(5).replace(/^ /, '')) - .join('\n'); - const parsed = parseJson(data); + for (const parsed of sseData(text)) { // A server may interleave its own requests and notifications; only OUR answer counts. if (isJsonObject(parsed) && parsed['id'] === id) return parsed; } @@ -32,13 +31,7 @@ export function readRpcAnswer( export function readNotifications(contentType: string | null, text: string): readonly string[] { if (contentType?.toLowerCase().startsWith('text/event-stream') !== true) return []; const methods: string[] = []; - for (const event of text.split(/\r?\n\r?\n/)) { - const data = event - .split(/\r?\n/) - .filter((line) => line.startsWith('data:')) - .map((line) => line.slice(5).replace(/^ /, '')) - .join('\n'); - const parsed = parseJson(data); + for (const parsed of sseData(text)) { if ( isJsonObject(parsed) && parsed['id'] === undefined && diff --git a/packages/notify/src/notifier.ts b/packages/notify/src/notifier.ts index fc180608d..ac89e255f 100644 --- a/packages/notify/src/notifier.ts +++ b/packages/notify/src/notifier.ts @@ -171,6 +171,7 @@ export function notifier<Params>( ? (value: NotifyPayload<Params>) => (definition.tenant as (params: Params) => string)(value.params) : definition.tenant, + // The identity sentinel `@ultimat3/jobs`' `resolvedRetry` reads as "declares none". retry: definition.retry ?? DEFAULT_RETRY, ...(definition.queue === undefined ? {} : { queue: definition.queue }), ...(definition.timeout === undefined ? {} : { timeout: definition.timeout }), diff --git a/packages/scraping/src/scrape.ts b/packages/scraping/src/scrape.ts index 75f13e341..13d2c812a 100644 --- a/packages/scraping/src/scrape.ts +++ b/packages/scraping/src/scrape.ts @@ -216,6 +216,7 @@ export function scrape<I, Row>(definition: ScrapeDefinition<I, Row>): JobHandle< input: definition.input, idempotencyKey: definition.idempotencyKey, tenant: definition.tenant, + // The identity sentinel `@ultimat3/jobs`' `resolvedRetry` reads as "declares none". retry: definition.retry ?? DEFAULT_RETRY, ...(definition.queue === undefined ? {} : { queue: definition.queue }), ...(definition.timeout === undefined ? {} : { timeout: definition.timeout }), diff --git a/scripts/lib/finite-screens.ts b/scripts/lib/finite-screens.ts index f0fa1260e..321261521 100644 --- a/scripts/lib/finite-screens.ts +++ b/scripts/lib/finite-screens.ts @@ -14,7 +14,7 @@ // the `??` out of the call (the evasion this rule exists to refuse), or a rename. It renamed. // THREE SHIPPED FILES now carry a comment saying the spelling is load-bearing — // `packages/jobs/src/clock.ts`, `packages/auth/src/policy-numbers.ts` and -// `packages/cache/src/tiers.ts` ("the `Finite` in all three names here is load-bearing"). A gate +// `packages/cache/src/tier-bounds.ts` ("the `Finite` in all three names here is load-bearing"). A gate // that dictates identifiers in three packages is a gate designing the code. // // A NON-SCREEN READ AS A REPAIR. `InfiniteScroll(` matched `[\w$]*[Ff]inite[\w$]*` — a SolidJS @@ -77,7 +77,8 @@ export const SCREENING_CALLEES: readonly FiniteScreen[] = [ }, { callee: 'assertFiniteCapacity', - screens: 'cache/src/tiers.ts — a tier ceiling, where a bad one evicts nothing rather than all', + screens: + 'cache/src/tier-bounds.ts — a tier ceiling, where a bad one evicts nothing rather than all', }, { callee: 'assertFiniteCount', @@ -85,7 +86,8 @@ export const SCREENING_CALLEES: readonly FiniteScreen[] = [ }, { callee: 'assertFiniteDurationMs', - screens: "cache/src/tiers.ts — a driver's request budget, which AbortSignal.timeout throws on", + screens: + "cache/src/tier-bounds.ts — a driver's request budget, which AbortSignal.timeout throws on", }, { callee: 'assertFiniteImageQuality', @@ -110,7 +112,7 @@ export const SCREENING_CALLEES: readonly FiniteScreen[] = [ { callee: 'assertFiniteSimilarityFloor', screens: - 'cache/src/tiers.ts — the semantic floor, where NaN deletes the boundary rather than moves it', + 'cache/src/tier-bounds.ts — the semantic floor, where NaN deletes the boundary rather than moves it', }, { callee: 'assertFiniteToleranceMs', diff --git a/scripts/lib/public-api.lock.json b/scripts/lib/public-api.lock.json index 556ec60bc..6a4b2894c 100644 --- a/scripts/lib/public-api.lock.json +++ b/scripts/lib/public-api.lock.json @@ -235,6 +235,7 @@ "MeterDrawResult": {"hash":"48e84e938c7c6fb0","shape":{"kind":"members","head":"a975305b","members":{"allowed":"a001763a","used":"4e57c805","warned":"a001763a"}}}, "MeterKey": {"hash":"4d7d531b2af7e18c","shape":{"kind":"members","head":"529a0124","members":{"meter":"1fb0a448","period":"1fb0a448","subject":"1fb0a448"}}}, "MeterStore": {"hash":"24f4e6a0776ff009","shape":{"kind":"members","head":"76d13fdb","members":{"claimWarning":"7aafd3ad","draw":"9c7d9164","releaseWarning":"6cd8a3de","scope":"0504c359"}}}, + "acceptedIdOf": {"hash":"aa0f0159a55d642e","shape":{"kind":"function","head":"d4528921","params":["74a589dd"],"returns":"742bc7c4"}}, "batchedAuditSink": {"hash":"05a916addfb6f153","shape":{"kind":"function","head":"f32c76ed","params":["0c913164","?4804307f"],"returns":"4dce12fd"}}, "installIdempotencyStore": {"hash":"5bfc4ff2df64c259","shape":{"kind":"function","head":"86693e01","params":["5d360121"],"returns":"b1498fb1"}}, "installMeterStore": {"hash":"5ae7beb92d7555a5","shape":{"kind":"function","head":"12f05d48","params":["f219a337"],"returns":"b1498fb1"}}, @@ -1023,6 +1024,7 @@ "KdfLimits": {"hash":"725ec8e66c47e059","shape":{"kind":"members","head":"e56e79b0","members":{"maxConcurrent":"4e57c805","maxQueued":"4e57c805"}}}, "LoginInput": {"hash":"0b9818193ed5be50","shape":{"kind":"declaration","keyword":"type","head":"c04b6135","locals":{"LoginCredentials":{"hash":"182dbdc4","shape":{"kind":"members","head":"e0ce7ba2","members":{"ip":"?979e9397","password":"1fb0a448","userAgent":"?979e9397"}}}}}}, "LoginResult": {"hash":"ec622df13ee67c1c","shape":{"kind":"members","head":"7fb9668e","members":{"actor":"d4bb2179","cookie":"1fb0a448","session":"b35bd983","token":"1fb0a448"}}}, + "MFA_CHALLENGE_COOKIE": {"hash":"eb9547a30388a9bf","shape":{"kind":"declaration","keyword":"const","head":"eb9547a3"}}, "MFA_CHALLENGE_PURPOSE": {"hash":"be2e758d0039172b","shape":{"kind":"declaration","keyword":"const","head":"be2e758d"}}, "MFA_CHALLENGE_TTL_MS": {"hash":"3a0dbf5d9a52fcff","shape":{"kind":"declaration","keyword":"const","head":"3a0dbf5d"}}, "MFA_SECRET_PURPOSE": {"hash":"a17ec0e023992d2d","shape":{"kind":"declaration","keyword":"const","head":"a17ec0e0"}}, @@ -1216,6 +1218,8 @@ "memoryAuthLimiter": {"hash":"2a68c5150f20eef0","shape":{"kind":"function","head":"22ce851e","params":["93ff9273","?afedcca2"],"returns":"69a90c0c"}}, "memoryAuthServerStore": {"hash":"bc0e656db0e8a218","shape":{"kind":"function","head":"80436493","params":[],"returns":"da052ce8"}}, "memoryTotpReplayGuard": {"hash":"4987370c8408499d","shape":{"kind":"function","head":"45a5aebe","params":["?12886f9d","?12886f9d"],"returns":"a0566658"}}, + "mfaChallengeCookie": {"hash":"d8eabd2960ee010b","shape":{"kind":"function","head":"e89f3296","params":["473287f8"],"returns":"473287f8"}}, + "mfaChallengeOf": {"hash":"c1905aeaf22c8a0a","shape":{"kind":"function","head":"c9b8a862","params":["b23a6a84"],"returns":"5eeb3f06"}}, "mfaChallengeRequired": {"hash":"942a93e34c5e6470","shape":{"kind":"function","head":"d41b01c4","params":["8eb3ea9b","473287f8","?ff12e412"],"returns":"e291965a"}}, "needsRehash": {"hash":"30e0fbc2c3395f03","shape":{"kind":"function","head":"dd2980b2","params":["473287f8","?c943a2c3"],"returns":"bf84d3d6"}}, "normaliseEmail": {"hash":"60416b4d49d74d15","shape":{"kind":"function","head":"441d6637","params":["473287f8"],"returns":"473287f8"}}, @@ -1376,7 +1380,7 @@ "CacheStackOptions": {"hash":"b57a98b262badbb9","shape":{"kind":"members","head":"c2923f8c","members":{"clock":"?5a6c9eb0","loadDeadlineMs":"?4e57c805","schedule":"?f88b5158"}}}, "CacheTag": {"hash":"80d041657f275eb7","shape":{"kind":"members","head":"66ec4bf8","members":{"entity":"bf1532e4","id":"?1fb0a448"}}}, "CacheTagRegistry": {"hash":"2cc37e6aa77b5b22","shape":{"kind":"members","head":"9268a8f8","members":{}}}, - "CacheTier": {"hash":"d3421e660d0756d6","shape":{"kind":"members","head":"32ec488f","members":{"clear":"?bbe3bc3f","del":"b70c1c9d","fence":"?b815eaf5","get":"c3da7be5","invalidateTags":"de6cd42d","name":"1f6b4143","set":"e87b6b7e"}}}, + "CacheTier": {"hash":"ad04d7dc45b49ad9","shape":{"kind":"members","head":"32ec488f","members":{"clear":"?bbe3bc3f","del":"b70c1c9d","fence":"?b815eaf5","get":"c3da7be5","invalidateTags":"de6cd42d","name":"1f6b4143","scope":"?1fb0a448","set":"e87b6b7e"}}}, "CacheTierFailureEvent": {"hash":"7a40718c891bc50b","shape":{"kind":"members","head":"72a48ad6","members":{"code":"?6c665e22","key":"1fb0a448","message":"1fb0a448","op":"c0a33ad0","tier":"1fb0a448"}}}, "CacheTooLargeError": {"hash":"3d5ff2d5cb5e0955","shape":{"kind":"class","head":"f181c399","members":{},"ctor":["{bytes=f1117367,key=119ef915,maxBytes=f1117367,tier=119ef915}"]}}, "CacheValueUnencodableError": {"hash":"b307d8be18d981d0","shape":{"kind":"class","head":"94204cc8","members":{},"ctor":["{key=119ef915,reason=119ef915,tier=119ef915}"]}}, @@ -1391,7 +1395,7 @@ "FastlyPurgeOptions": {"hash":"a8da0c3c40cace87","shape":{"kind":"members","head":"9d14abde","members":{"apiToken":"1fb0a448","baseUrl":"?6c665e22","fetch":"?68543f6d","serviceId":"1fb0a448","timeoutMs":"?5d7469a7"}}}, "FenceScope": {"hash":"7fc4d779b365152c","shape":{"kind":"members","head":"5a88437a","members":{"key":"?1fb0a448","tags":"?d0965a24"}}}, "FenceVerdict": {"hash":"8c1cbb49a8284ae0","shape":{"kind":"literals","head":"516400f1","values":["0cc389ef","26cdba3b","ddd710f0"]}}, - "InvalidationBroadcast": {"hash":"360263e4b801c32d","shape":{"kind":"function","head":"bced66c0","params":["21c248b4"],"returns":"00249f2e"}}, + "InvalidationBroadcast": {"hash":"9acaad2f174d6365","shape":{"kind":"function","head":"bced66c0","params":["21c248b4","?92e7950f"],"returns":"00249f2e"}}, "InvalidationBus": {"hash":"e0e0d662ff954eef","shape":{"kind":"members","head":"0392d9b4","members":{"close":"6c20bfe0","name":"1fb0a448","onReconnect":"3a75fc67","publish":"ee7a4674","subscribe":"30c74bc5"}}}, "InvalidationReport": {"hash":"9ab024f282b3258f","shape":{"kind":"members","head":"9306f906","members":{"cdn":"f8639a23","durationMs":"4e57c805","errors":"e7a1d5c7","isr":"f8639a23","liveQueries":"f8639a23","tags":"f8639a23","tiers":"0565c7b3"}}}, "InvalidationSubscription": {"hash":"9733636c2c34181f","shape":{"kind":"members","head":"55dc50e0","members":{"unsubscribe":"1563397b"}}}, @@ -1416,6 +1420,7 @@ "SemanticCacheOptions": {"hash":"9f3a07ad72508e82","shape":{"kind":"members","head":"48fa8eab","members":{"clock":"?5a6c9eb0","defaultTtlMs":"?4e57c805","maxEntries":"?4e57c805","threshold":"?4e57c805"}}}, "SemanticHit": {"hash":"e03cfc5ee829a5c9","shape":{"kind":"members","head":"a3f86b90","members":{"key":"1fb0a448","similarity":"4e57c805","value":"0db2ca9f"}}}, "SemanticRememberOptions": {"hash":"1196a82224dd4f88","shape":{"kind":"members","head":"8e284e56","members":{"tags":"?d0965a24","ttlMs":"?4e57c805"}}}, + "SharedTierScopes": {"hash":"3e623e6e0191c4c5","shape":{"kind":"declaration","keyword":"type","head":"3e623e6e"}}, "TagFactory": {"hash":"fba87e196a2ecfd1","shape":{"kind":"declaration","keyword":"type","head":"f55a1e8c","locals":{"TagAccessors":{"hash":"58a71551","shape":{"kind":"members","head":"ddefdb30","members":{"#06d52d49":"06d52d49"}}}}}}, "TagRevalidator": {"hash":"2ce0a36f9dbd36bb","shape":{"kind":"function","head":"4ea47137","params":["0250a923|b022e537"],"returns":"c7add05b"}}, "TierFence": {"hash":"418e11ceb1ea87ff","shape":{"kind":"members","head":"8e95f44f","members":{"cover":"ce87b119","verdict":"e45809d7"}}}, @@ -1462,7 +1467,7 @@ "nowMs": {"hash":"971326f27c3e7a36","shape":{"kind":"function","head":"2d3205de","params":["93ff9273"],"returns":"12886f9d"}}, "parseTag": {"hash":"23d9e54ccf283424","shape":{"kind":"function","head":"32099c0f","params":["473287f8"],"returns":"253677c8"}}, "purgeEdgeAgain": {"hash":"4af80d41061a042a","shape":{"kind":"function","head":"03c56539","params":["21c248b4"],"returns":"44a35597"}}, - "receiveInvalidationBroadcast": {"hash":"7dd3163ae27029b0","shape":{"kind":"function","head":"bebaa2b4","params":["21c248b4"],"returns":"a51e2bef"}}, + "receiveInvalidationBroadcast": {"hash":"4de397d14c5bd221","shape":{"kind":"function","head":"bebaa2b4","params":["21c248b4","?92e7950f"],"returns":"a51e2bef"}}, "redisPubSub": {"hash":"b640b36fd5ad0d67","shape":{"kind":"function","head":"4922967e","params":["c4d2eb8e"],"returns":"2bc754c1"}}, "redisPubSubAt": {"hash":"5c2a7030c7266234","shape":{"kind":"function","head":"f03fbe27","params":["473287f8","?{connectionName=?1fb0a448}"],"returns":"2bc754c1"}}, "redisTier": {"hash":"7a57a605eef2938a","shape":{"kind":"function","head":"01fae8a7","params":["?e782a187"],"returns":"aef20e29"}}, @@ -1493,7 +1498,7 @@ "CachePurgeFailedError": {"hash":"a6ce98df37786d9b","shape":{"kind":"class","head":"86453ff2","members":{},"ctor":["{detail=119ef915,driver=119ef915,fix=119ef915,retryable=b9f83688,status=?294497c3}"]}}, "CacheSetOptions": {"hash":"e23568359601c123","shape":{"kind":"members","head":"d392997c","members":{"negativeTtlMs":"?4e57c805","tags":"?d0965a24","ttlMs":"?4e57c805"}}}, "CacheTag": {"hash":"80d041657f275eb7","shape":{"kind":"members","head":"66ec4bf8","members":{"entity":"bf1532e4","id":"?1fb0a448"}}}, - "CacheTier": {"hash":"d3421e660d0756d6","shape":{"kind":"members","head":"32ec488f","members":{"clear":"?bbe3bc3f","del":"b70c1c9d","fence":"?b815eaf5","get":"c3da7be5","invalidateTags":"de6cd42d","name":"1f6b4143","set":"e87b6b7e"}}}, + "CacheTier": {"hash":"ad04d7dc45b49ad9","shape":{"kind":"members","head":"32ec488f","members":{"clear":"?bbe3bc3f","del":"b70c1c9d","fence":"?b815eaf5","get":"c3da7be5","invalidateTags":"de6cd42d","name":"1f6b4143","scope":"?1fb0a448","set":"e87b6b7e"}}}, "FenceScope": {"hash":"7fc4d779b365152c","shape":{"kind":"members","head":"5a88437a","members":{"key":"?1fb0a448","tags":"?d0965a24"}}}, "FenceVerdict": {"hash":"8c1cbb49a8284ae0","shape":{"kind":"literals","head":"516400f1","values":["0cc389ef","26cdba3b","ddd710f0"]}}, "PurgeDriver": {"hash":"dc046433cc123864","shape":{"kind":"members","head":"4a40c494","members":{"name":"1fb0a448","purge":"49323b01","purgeAll":"6c20bfe0"}}}, @@ -2006,6 +2011,7 @@ "JOBS_CONCURRENCY_DEFAULT": {"hash":"07e6b5b53f0360a8","shape":{"kind":"declaration","keyword":"const","head":"07e6b5b5"}}, "JOBS_DEAD_RETENTION_MS_DEFAULT": {"hash":"b81066af5241b8d0","shape":{"kind":"declaration","keyword":"const","head":"b81066af"}}, "JOBS_DONE_RETENTION_MS_DEFAULT": {"hash":"c6e2fcbf66c273c8","shape":{"kind":"declaration","keyword":"const","head":"c6e2fcbf"}}, + "JOBS_MAX_ATTEMPTS_DEFAULT": {"hash":"80a766edbef381b8","shape":{"kind":"declaration","keyword":"const","head":"80a766ed"}}, "JOBS_OUTBOX_RETENTION_MS_DEFAULT": {"hash":"d963934350853ea9","shape":{"kind":"declaration","keyword":"const","head":"d9639343"}}, "JitterMode": {"hash":"583c9c4b50014271","shape":{"kind":"literals","head":"da0f5846","values":["1e594123","30a0924a","874ed18a"]}}, "JobEnqueueEvent": {"hash":"45b6de9fd56a5026","shape":{"kind":"members","head":"d7865a1f","members":{"id":"1fb0a448","job":"1fb0a448","queue":"1fb0a448"}}}, @@ -2222,7 +2228,7 @@ "SetCookieOptions": {"hash":"053e756eb6971c42","shape":{"kind":"members","head":"72e95ef3","members":{"domain":"?1fb0a448","expires":"?085a63b8","httpOnly":"?a001763a","maxAge":"?4e57c805","partitioned":"?a001763a","path":"?1fb0a448","priority":"?e90dbc8f","sameSite":"?b47c4d53","secure":"?a001763a"}}}, "ShutdownHook": {"hash":"0ff23c2a5802b1d6","shape":{"kind":"function","head":"7e2c4d14","params":["f7727cc8"],"returns":"54e48ac8"}}, "ShutdownPhase": {"hash":"5fd8be6fa58d852d","shape":{"kind":"literals","head":"3b5a1c79","values":["248c6687","2faed141","97959247"]}}, - "ShutdownReason": {"hash":"d1791f2d50cfe323","shape":{"kind":"members","head":"1f206d2b","members":{"deadlineAt":"4e57c805","signal":"1fb0a448"}}}, + "ShutdownReason": {"hash":"098a4a7bc3b5a8d1","shape":{"kind":"members","head":"1f206d2b","members":{"deadlineAt":"4e57c805","inflightUntil":"?5d7469a7","signal":"1fb0a448"}}}, "SignAwsRequestInput": {"hash":"e5a495516585eeab","shape":{"kind":"members","head":"7ccc73fd","members":{"clock":"?ec3d6144","contentSha256Header":"?f4af6dab","credentials":"d195744a","doubleEncodePath":"?f4af6dab","headers":"?730abe21","method":"1fb0a448","payload":"?fffbf59c","region":"1fb0a448","service":"1fb0a448","url":"2717996b"}}}, "SignalHandlerOptions": {"hash":"5d34b4984add95f1","shape":{"kind":"members","head":"a0bda6e4","members":{"exit":"?f4af6dab","platform":"?6c665e22","signals":"?38f37eb8"}}}, "SignedAwsRequest": {"hash":"2b64f923c7535746","shape":{"kind":"members","head":"ae363b43","members":{"canonicalRequest":"1fb0a448","headers":"a8610d8c","method":"1fb0a448","signature":"1fb0a448","stringToSign":"1fb0a448","url":"1fb0a448"}}}, @@ -2487,6 +2493,7 @@ "jsonbRefusal": {"hash":"6d926749ec29550e","shape":{"kind":"function","head":"62efec68","params":["473287f8"],"returns":"742bc7c4"}}, "judgeThrown": {"hash":"5a7b4dc1e80468ba","shape":{"kind":"function","head":"bf5b2328","params":["21c248b4|eb045d78","473287f8","12886f9d|eb045d78"],"returns":"4097c13e"}}, "keyedFingerprint": {"hash":"77c0005034e95e59","shape":{"kind":"function","head":"b63f7760","params":["b23a6a84","473287f8"],"returns":"473287f8"}}, + "laterHooksReserveMs": {"hash":"78653c61796d90e1","shape":{"kind":"function","head":"841b883f","params":["12886f9d"],"returns":"12886f9d"}}, "leasesLost": {"hash":"c36346f96a12ad9b","shape":{"kind":"declaration","keyword":"const","head":"c36346f9"}}, "lifecycleState": {"hash":"92d67c00ffc650f2","shape":{"kind":"function","head":"47b3148c","params":[],"returns":"dd938b75"}}, "listErrorCodes": {"hash":"2168b965f8f7772c","shape":{"kind":"function","head":"dfb3b8ed","params":[],"returns":"d76bbf0f"}}, @@ -2791,6 +2798,10 @@ "recordDefinedError": {"hash":"990f84b800241ee0","shape":{"kind":"function","head":"b933721f","params":["473287f8","12886f9d|eb045d78"],"returns":"445be54d"}}, "resetAppErrorStatus": {"hash":"ce32bbc2988b1cf3","shape":{"kind":"function","head":"7ffeb8e7","params":[],"returns":"445be54d"}} }, + "@ultimat3/core/internal/sse-frames": { + "SseFrame": {"hash":"639f216bcbeb0078","shape":{"kind":"members","head":"0634250a","members":{"data":"1fb0a448","dates":"?1fb0a448","event":"1fb0a448"}}}, + "takeFrames": {"hash":"ecb6182eb5d28d19","shape":{"kind":"function","head":"573569ac","params":["473287f8"],"returns":"d77c63a8"}} + }, "@ultimat3/core/outbound": { "DeadlineSignal": {"hash":"28ed3075830487bf","shape":{"kind":"members","head":"6174bbd9","members":{"signal":"2b99db86","timedOut":"05d1de47"}}}, "DeadlineTimer": {"hash":"89174fa67ab99194","shape":{"kind":"members","head":"71f0da35","members":{"clear":"5432dd8b","set":"2d5c0851"}}}, @@ -3598,7 +3609,6 @@ "memoryRepo": {"hash":"d8a5ae611c449738","shape":{"kind":"function","head":"88b40334","params":["4077f25d","?4545958a","?6dd23698"],"returns":"3820eb67"}}, "memorySearchIndex": {"hash":"3c4aeb8186be626c","shape":{"kind":"function","head":"d2a1fde7","params":[],"returns":"0f6f9ca2"}}, "memoryTransactor": {"hash":"95a2dfa8c1e0ce77","shape":{"kind":"function","head":"d95db665","params":[],"returns":"ab7cecb4"}}, - "memoryTxOpen": {"hash":"cdbee8d7cd9209c8","shape":{"kind":"function","head":"a2eee35f","params":["5b9e8d7c"],"returns":"bf84d3d6"}}, "money": {"hash":"1c54bffaf98437be","shape":{"kind":"function","head":"64a036a3","params":["?117c1122"],"returns":"3e9ac006"}}, "moneyColumns": {"hash":"d55844fb2ca02d49","shape":{"kind":"function","head":"2775f5fa","params":["473287f8","fec6318e"],"returns":"2b524d96"}}, "nPlusOne": {"hash":"5370a1e2cd4cbb56","shape":{"kind":"function","head":"56118f27","params":["3ba6642d"],"returns":"b0ea7bf1"}}, @@ -3725,6 +3735,9 @@ "upsertPlan": {"hash":"5ddf8d24362e3246","shape":{"kind":"function","head":"8f0441e8","params":["4077f25d","608b4949","21c248b4","47dbebec|d9aa61a4","?21c248b4"],"returns":"e2d61a23"}}, "valueAt": {"hash":"c6d416f0dc281248","shape":{"kind":"function","head":"fbd9a4dd","params":["b23a6a84","473287f8"],"returns":"b23a6a84"}} }, + "@ultimat3/entity/internal/memory-tx": { + "memoryTxOpen": {"hash":"cdbee8d7cd9209c8","shape":{"kind":"function","head":"a2eee35f","params":["5b9e8d7c"],"returns":"bf84d3d6"}} + }, "@ultimat3/entity/record": { "ENTITY_BRAND": {"hash":"bd689c01e58fa117","shape":{"kind":"declaration","keyword":"const","head":"bd689c01"}}, "ProjectedEntity": {"hash":"861e19c9827f604d","shape":{"kind":"members","head":"e893e6ca","members":{"$name":"1fb0a448","$schema":"bb0c97c8"}}}, @@ -3894,6 +3907,7 @@ "ValidationOutcome": {"hash":"1ba10e135776ae5a","shape":{"kind":"declaration","keyword":"type","head":"1ba10e13"}}, "VerifiedBody": {"hash":"05cd49c2d502ffd6","shape":{"kind":"members","head":"7e98bf6d","members":{"bytes":"c62d5aaa","text":"c380b02d"}}}, "VerifiedWebhook": {"hash":"17cc2ddde40e2284","shape":{"kind":"members","head":"60d3d4a8","members":{"body":"1fb0a448","eventId":"1fb0a448","signedAtMs":"4e57c805","topic":"1fb0a448"}}}, + "WIRE_DATES_MAX_BYTES": {"hash":"ded012a92486c6c3","shape":{"kind":"declaration","keyword":"const","head":"ded012a9"}}, "WebSocketMount": {"hash":"d164f2b51901e3b8","shape":{"kind":"members","head":"cba7f7b3","members":{"fetch":"4b806984","path":"1fb0a448","websocket":"4e39b815"}}}, "WebSocketOption": {"hash":"c02f0bdcbeff26e2","shape":{"kind":"declaration","keyword":"type","head":"c02f0bdc"}}, "WebhookVerifyOptions": {"hash":"839e2538b408098c","shape":{"kind":"members","head":"d6a74f52","members":{"clock":"?5a6c9eb0","maxBytes":"?4e57c805","secret":"1fb0a448","toleranceMs":"?4e57c805"}}}, @@ -3914,6 +3928,7 @@ "cacheControl": {"hash":"3ab863423364f847","shape":{"kind":"function","head":"7453bbdd","params":["0d29055d"],"returns":"473287f8"}}, "callerLocality": {"hash":"cea6c9de5f2da17e","shape":{"kind":"function","head":"965a8af3","params":["{headers=15f357d1,ip=c380b02d}"],"returns":"302c8141"}}, "canonicalPath": {"hash":"f87f97f8ffba4a7b","shape":{"kind":"function","head":"15313238","params":["473287f8"],"returns":"473287f8"}}, + "cappedWireDates": {"hash":"ec579a080f2d09f8","shape":{"kind":"function","head":"e4226c93","params":["b23a6a84","?10bc96af|eb045d78"],"returns":"742bc7c4"}}, "checkCsrf": {"hash":"732c721e6660d0fa","shape":{"kind":"function","head":"b631f101","params":["b78a9c04"],"returns":"9dc07bc1"}}, "clientAddress": {"hash":"20a3ea7edcac4bf9","shape":{"kind":"function","head":"7fe0dd01","params":["783985e1"],"returns":"5eeb3f06"}}, "compose": {"hash":"5759bcbc87873e2c","shape":{"kind":"function","head":"4e99d692","params":["6a66b06e"],"returns":"2ba999d4"}}, @@ -3943,7 +3958,6 @@ "httpRouter": {"hash":"b0b464dd8e9e51f8","shape":{"kind":"function","head":"a987e877","params":["35d592df"],"returns":"eada0318"}}, "httpServer": {"hash":"e05834d1f56294f3","shape":{"kind":"function","head":"182e2a45","params":["1c7c7e20"],"returns":"bd5e257e"}}, "installedRateLimitStore": {"hash":"25f60175a518c378","shape":{"kind":"function","head":"4ac76508","params":[],"returns":"02e4962b"}}, - "isCallerAbort": {"hash":"bf960b3e09569d3b","shape":{"kind":"function","head":"6d74c2c4","params":["b23a6a84","b3da7007"],"returns":"bf84d3d6"}}, "isCompressibleType": {"hash":"48c7838b8bd98a3c","shape":{"kind":"function","head":"3e7d2626","params":["473287f8|74234e98"],"returns":"bf84d3d6"}}, "joinWebSocketMounts": {"hash":"36ad04ecf1bca11d","shape":{"kind":"function","head":"7ac0e849","params":["938c234c"],"returns":"38c2aba3"}}, "jsonResponse": {"hash":"d9d6e82d31f79609","shape":{"kind":"function","head":"b179a981","params":["e632b709","?ffb23d77"],"returns":"9061383b"}}, @@ -4457,7 +4471,7 @@ "consumerRow": {"hash":"884cee30456e8386","shape":{"kind":"function","head":"4c969ea1","params":["{input=2456a234,name=1fb0a448,progress=2edb2c50}"],"returns":"ff8d4ba8"}}, "cronJob": {"hash":"4d34f949ca362d62","shape":{"kind":"overloads","signatures":[{"kind":"function","head":"5111b397","params":["2a3486a0"],"returns":"e96589fd"},{"kind":"function","head":"3726950e","params":["bc9febf8"],"returns":"e88c2896"}]}}, "currentStep": {"hash":"2edaa94f1f009c89","shape":{"kind":"function","head":"e318b93c","params":[],"returns":"742bc7c4"}}, - "cutoffTimes": {"hash":"eaaa3b17c4044efc","shape":{"kind":"function","head":"2202f436","params":["12886f9d","12886f9d"],"returns":"9bc04246"}}, + "cutoffTimes": {"hash":"93dd188572d96179","shape":{"kind":"function","head":"2202f436","params":["12886f9d","12886f9d","?12886f9d"],"returns":"9bc04246"}}, "declarationOf": {"hash":"1180dd5a46577537","shape":{"kind":"function","head":"1ceb55f8","params":["783d5039"],"returns":"0c015b5a"}}, "defineSubject": {"hash":"f2364b502ebf73d2","shape":{"kind":"function","head":"539c0797","params":["b5bec36d","e670eba9"],"returns":"07a8b7ca"}}, "describeJobs": {"hash":"1e604bd837ed6568","shape":{"kind":"function","head":"515204f7","params":[],"returns":"9c9144b1"}}, @@ -6094,7 +6108,7 @@ "GrantBook": {"hash":"b64da5941b4457ef","shape":{"kind":"class","head":"ad9c5f00","members":{"delete":"6390b1e7","expired":"2793fdd3","get":"83f9c323","set":"6521ff5a","size":"40e2836c"}}}, "GrantSweepDeps": {"hash":"fea38735b6ee6074","shape":{"kind":"members","head":"a1b32893","members":{"clock":"5a6c9eb0","grants":"3654edd3","onActor":"8c82cdb5","onRefreshFailed":"?b70c28a6","onRevoked":"9446ef1e","refreshDeadlineMs":"?5d7469a7","schedule":"?3f64e310"}}}, "GrantSweepResult": {"hash":"cc07cd57047c3f72","shape":{"kind":"members","head":"8017c3b6","members":{"failed":"4e57c805","refreshed":"4e57c805","revoked":"4e57c805"}}}, - "InProcessTransport": {"hash":"011c5a496101a2c0","shape":{"kind":"class","head":"86b16200","members":{"close":"6c20bfe0","name":"1ade987b","onReconnect":"7cceb9ef","publish":"ee7a4674","shared":"7b7cbb90","sharedKeys":"40e2836c","subjectCount":"40e2836c","subscribe":"ab5f43a1"},"ctor":["?216439ce"]}}, + "InProcessTransport": {"hash":"6470607d6a534428","shape":{"kind":"class","head":"86b16200","members":{"close":"6c20bfe0","name":"1ade987b","onReconnect":"7cceb9ef","publish":"ee7a4674","shared":"7b7cbb90","subjectCount":"40e2836c","subscribe":"ab5f43a1"},"ctor":["?216439ce"]}}, "InProcessTransportOptions": {"hash":"34a8a3dfdd900d88","shape":{"kind":"members","head":"4aecd744","members":{"clock":"?5a6c9eb0","onError":"?51219213"}}}, "IncrementalMatcher": {"hash":"743122feefddf2fe","shape":{"kind":"members","head":"0ce5f1ee","members":{"entities":"f8639a23","match":"33ce4fb1"}}}, "JsError": {"hash":"85221701886ce616","shape":{"kind":"members","head":"b44ca847","members":{"code":"4e57c805","description":"1fb0a448","errCode":"4e57c805"}}}, @@ -6162,7 +6176,7 @@ "SelectTransportOptions": {"hash":"3c4edbcd1c7e953a","shape":{"kind":"members","head":"98ad3fbd","members":{"backoff":"?94efd3cd","clock":"?ec3d6144","connect":"?4e1a9b1b","connectWithinMs":"?5d7469a7","onError":"?14bc2c56","presenceTtlMs":"?5d7469a7","scheduler":"?3f64e310","use":"?28d6787e"}}}, "SeqGapDetector": {"hash":"e6cb6b3708639b8e","shape":{"kind":"class","head":"9f3b4377","members":{"forget":"1563397b","handOver":"4c02b435","observe":"bfdab05f"}}}, "SnapshotResult": {"hash":"f21c11100cb68b73","shape":{"kind":"members","head":"e980ac96","members":{"lsn":"1fb0a448","rows":"8e861daf"}}}, - "SocketRegistry": {"hash":"9ca8499dbe4c107a","shape":{"kind":"class","head":"2b78c589","members":{"add":"856bcdb2","all":"7aa46a9e","announceGap":"9db3fec4","count":"40e2836c","deliver":"f1989bf4","deliverRecords":"dce777f8","droppedChannelFrames":"40e2836c","gapRepairs":"7d7de5fe","get":"f098f431","idle":"46c0fd86","idleTimeoutMs":"40e2836c","joinTopic":"1cfd69ce","leaveTopic":"1cfd69ce","remove":"c5853991","subscriberCount":"668887b7"},"ctor":["?bbd5b2e5"]}}, + "SocketRegistry": {"hash":"061ac1fa5760a42f","shape":{"kind":"class","head":"2b78c589","members":{"add":"856bcdb2","all":"7aa46a9e","announceGap":"9db3fec4","count":"40e2836c","deliver":"f1989bf4","deliverRecords":"899abe42","droppedChannelFrames":"40e2836c","gapRepairs":"7d7de5fe","get":"f098f431","idle":"46c0fd86","idleTimeoutMs":"40e2836c","joinTopic":"1cfd69ce","leaveTopic":"1cfd69ce","remove":"c5853991","subscriberCount":"668887b7"},"ctor":["?bbd5b2e5"]}}, "SocketRegistryOptions": {"hash":"6badc5de244e6782","shape":{"kind":"members","head":"571e1bcd","members":{"clock":"?5a6c9eb0","idleTimeoutMs":"?4e57c805"}}}, "SslMode": {"hash":"fb5b94993963c90f","shape":{"kind":"literals","head":"d3d59936","values":["0bfa14e9","3a118e0a","4eb7618d","58d46b62","c33216a8","ce9d08a2"]}}, "Subscriber": {"hash":"1649152d8c906465","shape":{"kind":"members","head":"8d4f5a21","members":{"actor":"84254bdd","sid":"1fb0a448"}}}, diff --git a/scripts/primitive-factories.test.ts b/scripts/primitive-factories.test.ts index e17fd9513..8360a96a0 100644 --- a/scripts/primitive-factories.test.ts +++ b/scripts/primitive-factories.test.ts @@ -108,6 +108,49 @@ const sourceFiles = async (): Promise<readonly string[]> => { const read = (path: string): Promise<string> => Bun.file(`${repoRoot()}/${path}`).text(); +interface Entry { + readonly path: string; + readonly source: string; +} + +/** Every file a value of a package's `exports` map names, conditions included, repo-relative. */ +const entryPaths = (pkg: string, exports: unknown): readonly string[] => { + if (typeof exports === 'string') return [`packages/${pkg}/${exports.replace(/^\.\//, '')}`]; + if (exports === null || typeof exports !== 'object') return []; + return Object.values(exports).flatMap((value: unknown) => entryPaths(pkg, value)); +}; + +const packageEntries = async (): Promise<readonly Entry[]> => { + const entries: Entry[] = []; + for (const manifest of new Bun.Glob('packages/*/package.json').scanSync({ cwd: repoRoot() })) { + const pkg = manifest.split('\\').join('/').split('/')[1] ?? ''; + const parsed = (await Bun.file(`${repoRoot()}/${manifest}`).json()) as { exports?: unknown }; + for (const path of entryPaths(pkg, parsed.exports)) { + if (path.endsWith('.ts') && (await Bun.file(`${repoRoot()}/${path}`).exists())) { + entries.push({ path, source: await read(path) }); + } + } + } + return entries; +}; + +/** + * Can an app import it? Only through an entry of the package that declares it: the entry IS the + * declaring module, or names the function (re-exports are explicit — no `export *`, CLAUDE.md). A + * helper a package's modules share and no entry names is internal, never a factory. + */ +export const importable = ( + found: { readonly factory: string; readonly at: string }, + entries: readonly Entry[], +): boolean => { + const pkg = found.at.split('/')[1]; + const named = new RegExp(`\\b${found.factory.replace(/\$/g, '\\$')}\\b`); + return entries.some( + (entry) => + entry.path.split('/')[1] === pkg && (entry.path === found.at || named.test(entry.source)), + ); +}; + /** * Every type that IS an `Action`/`JobHandle`, to a fixpoint. One hop is not enough and never was: * `llm()` returns `LlmAction`, which `extends Action` — so a scan keyed on the two root names alone @@ -164,7 +207,10 @@ export function factoriesIn( const files = await sourceFiles(); const sources = await Promise.all(files.map(read)); const kinds = primitiveTypes(sources); -const declared = files.flatMap((path, index) => factoriesIn(path, sources[index] as string, kinds)); +const entries = await packageEntries(); +const declared = files + .flatMap((path, index) => factoriesIn(path, sources[index] as string, kinds)) + .filter((found) => importable(found, entries)); const rowFor = (name: string) => PRIMITIVE_FACTORIES.find((entry) => entry.factory === name); @@ -330,6 +376,33 @@ describe('unit · the scan itself can fail', () => { expect(files).toContain('packages/jobs/src/backfill.ts'); }); + /** + * `factoryJob()` (`packages/jobs/src/job.ts`) returns a `JobHandle` and is exported from its + * module for the package's own factories, but no entry of `@ultimat3/jobs` names it: an app + * cannot import it, so it is no factory and needs no row. A function an entry re-exports is one. + */ + test('an export no package entry names is internal; one an entry names is a factory', () => { + const entries = [ + { path: 'packages/jobs/src/index.ts', source: "export { backfill } from './backfill';\n" }, + { path: 'packages/scraping/src/cdp.ts', source: 'export function cdpAt() {}\n' }, + ]; + expect(importable({ factory: 'backfill', at: 'packages/jobs/src/backfill.ts' }, entries)).toBe( + true, + ); + expect(importable({ factory: 'factoryJob', at: 'packages/jobs/src/job.ts' }, entries)).toBe( + false, + ); + // A subpath that IS the declaring module exports everything in it. + expect(importable({ factory: 'cdpAt', at: 'packages/scraping/src/cdp.ts' }, entries)).toBe( + true, + ); + // Named in ANOTHER package's entry is not this package's export. + expect(importable({ factory: 'backfill', at: 'packages/ai/src/backfill.ts' }, entries)).toBe( + false, + ); + expect(declared.map((entry) => entry.factory)).not.toContain('factoryJob'); + }); + test('a DeviceSocket-returning export is a route factory', () => { const source = 'export function deviceSocket(options: DeviceSocketOptions): DeviceSocket {\n return link;\n}\n'; diff --git a/scripts/template-codemods-rows.ts b/scripts/template-codemods-rows.ts index 2252bc4c0..1d08dd93c 100644 --- a/scripts/template-codemods-rows.ts +++ b/scripts/template-codemods-rows.ts @@ -278,6 +278,11 @@ export const TEMPLATE_CODEMOD_ROWS: readonly TemplateCodemodRow[] = [ ].map((template) => ({ template, since: '31.49.0', - none: "x g sign-in --oidc now also writes the second-factor leg and passes mfaPath; a sign-in an app already generated is its own code and keeps signing in as it did, and the password shape's files render byte-identical, so x upgrade leaves them alone", + none: "x g sign-in --oidc now also writes the second-factor leg and passes mfaPath, and both shapes hold the second-factor challenge in auth's own __Host-x_mfa cookie; a sign-in an app already generated is its own code and keeps signing in as it did with its own cookie, so x upgrade leaves them alone", })), + { + template: 'packages/cli/src/templates/sign-in-challenge.ts', + since: '31.49.0', + none: "x g sign-in now holds the second-factor challenge in auth's own cookie for both shapes; an existing app's sign-in-challenge.ts is its own code and keeps working with its own cookie, so x upgrade leaves it alone", + }, ]; diff --git a/tsconfig.base.json b/tsconfig.base.json index 135b1f24c..e9c3f7922 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -25,6 +25,7 @@ "@ultimat3/core/outbound": ["./packages/core/src/outbound-subpath.ts"], "@ultimat3/core/redis": ["./packages/core/src/redis-client.ts"], "@ultimat3/core/internal/error-status": ["./packages/core/src/error-status-declared.ts"], + "@ultimat3/core/internal/sse-frames": ["./packages/core/src/sse-frames.ts"], "@ultimat3/core/render-node": ["./packages/core/src/render-node.ts"], "@ultimat3/core/render-nodes": ["./packages/core/src/render-nodes.ts"], "@ultimat3/db/adapter": ["./packages/db/src/adapter.ts"], @@ -73,6 +74,7 @@ "@ultimat3/testing/registry-isolation": ["./packages/testing/src/registry-isolation.ts"], "@ultimat3/ui/icons/*": ["./packages/ui/src/icons/glyphs/*"], "@ultimat3/scraping/cdp": ["./packages/scraping/src/cdp.ts"], + "@ultimat3/entity/internal/memory-tx": ["./packages/entity/src/memory-tx-entry.ts"], "@ultimat3/*": ["./packages/*/src"] }, diff --git a/wiki/Actions.md b/wiki/Actions.md index 2d5eb374b..9bb7d0848 100644 --- a/wiki/Actions.md +++ b/wiki/Actions.md @@ -140,7 +140,7 @@ An action that answers in pieces declares `stream: <chunk schema>` and writes `h | refused before the handler starts (policy, input, rate limit) | the ordinary problem response, never a stream | | the client leaves mid-stream | `ctx.signal` aborts inside the handler | | a browser | `clientStream({ url, body })` from `@ultimat3/core`: `fetch`, never `EventSource` | -| a `Date` in the output | a `Date` again in `clientStream` and the typed client: the server names each instant's path (`x-ultimate-dates` on the plain and the enveloped 200, `dates:` on each `chunk` and the `done` frame) and the client revives it. The body and OpenAPI are unchanged; a client ignoring the header reads the ISO string. `As of 2026-11-19` (`packages/action/src/record-wire.ts`, `packages/action/src/http-stream.ts`) | +| a `Date` in the output | a `Date` again in `clientStream` and the typed client: the server names each instant's path (`x-ultimate-dates` on the plain and the enveloped 200, `dates:` on each `chunk` and the `done` frame) and the client revives it. The body and OpenAPI are unchanged; a client ignoring the header reads the ISO string. `As of 2026-11-19` (`packages/action/src/record-wire.ts`, `packages/action/src/http-stream.ts`). The header is capped at 4,096 bytes (`WIRE_DATES_MAX_BYTES`): an answer whose instants need one path each — a `string \| Date` column, a `[label, instant]` tuple — past that is sent with no `x-ultimate-dates` (and no `dates:` line), the client reads those instants as ISO strings, and the operation is logged once at `warn` as `http.wire_dates_dropped`. `As of 2026-11-19`. | A chunk its schema refuses, or `stream:` beside a handle that is not a generator, is `X_ACTION_STREAM_INVALID`. The OpenAPI 200 lists `text/event-stream` beside `application/json` for a streaming action only. `agent()` streams this way. diff --git a/wiki/Agents.md b/wiki/Agents.md index 1b0d27252..6b4b84aba 100644 --- a/wiki/Agents.md +++ b/wiki/Agents.md @@ -544,7 +544,7 @@ export async function writeThenFix(ctx: Ctx, problem: string): Promise<{ title: | Before | After | |---|---| | tools, system prompt (stable block, per-run block) | **the same bytes** — the provider's cached prefix survives | -| first user message: the rendered prompt | the prompt verbatim, then one `[compacted: N earlier turns …]` text block holding the summary | +| first user message: the rendered prompt | the prompt verbatim, then one `[compacted: N earlier turns …]` text block holding the summary, then the user's own text from summarised turns, ≤ 8,000 chars in total across every compaction (`KEPT_USER_CHARS`, newest kept first). `As of 2026-11-19` | | turns 1 … N−k | gone — folded into the summary | | the last `keepTurns` turns (each an assistant message and the user message answering its tool calls) | **the same bytes** — no tool call is ever separated from its result | diff --git a/wiki/Auth.md b/wiki/Auth.md index b6ed0ce6b..04def43a4 100644 --- a/wiki/Auth.md +++ b/wiki/Auth.md @@ -136,7 +136,9 @@ export const sso = identityProviderRoutes(auth, { A user with a second factor is sent to `mfaPath` (303) with the sealed challenge in the `__Host-x_mfa` cookie; that page finishes with `completeMfa(auth, readMfaChallenge(request) ?? '', code)`. `oauthLogin(auth, { mfaPath })` is the -same option. +same option. The write half is exported too — `mfaChallengeOf`, `mfaChallengeCookie`, +`MFA_CHALLENGE_COOKIE` — so a password sign-in holds its challenge in the same cookie +(`x g sign-in --password` does, `As of 2026-11-19`). `defineAuth({ providers })` lists both ids; an unknown or not-enabled id is `X_IDENTITY_PROVIDER_UNKNOWN` (404). diff --git a/wiki/CLI-Reference.md b/wiki/CLI-Reference.md index 0e9ab6fea..6e292933d 100644 --- a/wiki/CLI-Reference.md +++ b/wiki/CLI-Reference.md @@ -62,7 +62,7 @@ x version # CLI version | `x shot <route>` | photograph one route from a real browser, plus a `verdict.json` a picture cannot carry | shipped | | `x pr review\|resolve\|reply` | inline review threads — the ones `gh pr view --comments` does not show — plus every review verdict, every PR comment, and which review bots did not review | shipped | | `x ci` | the workflow runs for this branch, and the findings inside the failed step's log; `x ci tested`: whether a push reuses a green PR run | shipped | -| `x errors explain <CODE>` | code → cause, fix, docs | shipped | +| `x errors explain <CODE>` | code → cause, fix, docs; inside an app, its own `defineError()` code → title, HTTP status and the declaring `file:line` | shipped | | `x docs "<question>"` | framework docs and this wiki, offline, from the install — the first lookup | shipped | | `x fix boundary <file>` | plan the minimal cut for an import that crossed a surface boundary (never rewrites) | shipped | | `x upgrade` | one major per run: exact pins, the Bun floor, `bun install`, the release's codemods, the gate, the section to read · `x upgrade codemods` | shipped | @@ -504,7 +504,7 @@ x db gen "add publish_at" [--merge-fork] | migrate | rollback [--steps n] | rese |---|---|---| | `gen ["<name>"]` | diff the app's entities against what the migrations declare, write the next migration, then rewrite the schema dump | One run at a time per checkout, `As of 2026-11`. The summary names the tables the migration touches (`data.tables`); a run with nothing to write names the newest migration (`data.newest`), which a concurrent run may have written. A forked chain is refused first (`X_MIGRATION_FORKED`). the message becomes the id's slug; left out it is `change`. **Writes to no database of yours** — the diff reads the previous migration's snapshot, and the dump is replayed on a scratch database it boots and discards: the embedded one, restored from a snapshot under `.x/cache` after its first boot, or a real Postgres when a migration creates an extension PGlite cannot link ([the engine rule](Migrations-And-Backfills#extensions-and-the-scratch-database)). **Exit 1 with a migration written** is possible: the dump failed after the migration was generated, the summary and the finding both say so, and the next move is a bare `x db gen`, never the same message again. A bare `x db gen` with nothing to generate rewrites `packages/db/schema/` alone, which makes it `X_SCHEMA_DUMP_DRIFT`'s whole fix. On the **embedded** database it first reads the ledger once (through a running `x dev`, else a read-only open of `.x/pgdata` when it exists; `As of 2026-11-19`): an applied migration whose SQL was edited since is `X_MIGRATION_CONFLICT`, exit 1, nothing written — the dump is never rewritten to match an edit. A ledger it cannot read is a printed line, never a refusal; an external `DATABASE_URL` is never dialled. A change that needs a step outside the transaction is written as two migrations, `<id>` and `<id>_concurrently`, and the summary names both. When the app does not load, nothing is compared and the summary says so — *nothing was compared — the app did not load (N finding(s)); fix them, then run x db gen again* — never "no migration needed". `--json`: `data.schemaDump` = `{ directory, status, files, written, removed }`, `status` one of `written`, `unchanged`, `skipped` (no migration yet), `failed`. `--allow-destructive` lets it emit a drop whose `down` cannot restore the rows; `--rolling-unsafe` lets it drop a column never retired, for an app that stops before it starts → [A column drop takes two releases](Migrations-And-Backfills#a-column-drop-takes-two-releases) | | `migrate` | apply pending migrations, verify the result, then rewrite the schema dump | literally `ROLE=migrate`'s own `runMigrations` — which ends by diffing the live schema against the ledger it just wrote, on the connection it already holds. A difference is `X_DB_DRIFT` and a non-zero exit. Beside a live `x dev` holding the embedded database it is **applied by that dev server** (`POST /_x/db/migrate`, loopback and same-origin only), never by a second process: PGlite takes no lock of its own, and a second writer's tables are dropped by the holder's next write. The report, drift and dump are the same either way. The request sends `Sec-Fetch-Site: same-origin`, so an app's CSRF check admits it, and a holder still booting is waited for (up to 120 s; only a refused connection is retried, so a sent request is never sent twice). Applied that way, `x dev` serves the new schema without restarting. A holder that cannot answer (older server, dead port) or runs `database.rowSecurity` (it serves as `x_app`, which cannot migrate) is `X_DEV_ALREADY_RUNNING`, fix `x stop --json && x db migrate && x dev` (`As of 2026-11-19`; against an external `DATABASE_URL` it runs as always). Then, `x db migrate` only: the dump is regenerated as `gen` does, and the database is reopened to report any trigger, function, view, type or sequence no migration creates (`unexpected-object`, also `X_DB_DRIFT`). `--json` carries the same `data.schemaDump` | -| `rollback [--steps n]` | reverse the most recently applied migration(s), most recently applied first (`applied_at`, not id), by running each file's `-- down` half | default 1 (`--steps` is an integer ≥ 1, read before anything opens). The files stay, so each is pending again: `x db migrate` re-applies it, deleting its `.sql` / `.snapshot.json` / `.hash` drops the change. No `-- down` marker in the file: `X_MIGRATION_IRREVERSIBLE` (an empty `down` under the marker reverses with no statement). A ledger row whose file is gone: `X_MIGRATION_CONFLICT`. Outside development and test (staging included): `X_MIGRATION_ROLLBACK_DESTRUCTIVE` until `ROLLBACK_ALLOW_DESTRUCTIVE` names every id it would reverse — judged under the migrate lock against the rows it is about to reverse. Beside a live embedded `x dev` it is run by that server (`POST /_x/db/rollback`), as `migrate` is. A change `gen` wrote as `<id>` + `<id>_concurrently` takes `--steps 2`; one step reverses the second half and says the first is still applied. `--json`: `data` = `{ reverted, steps, files }`. `As of 2026-11-19` | +| `rollback [--steps n]` | reverse the most recently applied migration(s), most recently applied first (`applied_at`, not id), by running each file's `-- down` half | default 1 (`--steps` is an integer ≥ 1, read before anything opens). The files stay, so each is pending again: `x db migrate` re-applies it, deleting its `.sql` / `.snapshot.json` / `.hash` drops the change. No `-- down` marker in the file: `X_MIGRATION_IRREVERSIBLE` (an empty `down` under the marker reverses with no statement). A ledger row whose file is gone: `X_MIGRATION_CONFLICT`. On a named deploy (staging or production, `NODE_ENV=production` included), an `ULTIMATE_ENV` that names no environment, or — whatever the environment — an external `DATABASE_URL` whose host is not this machine (loopback or a local socket): `X_MIGRATION_ROLLBACK_DESTRUCTIVE` until `ROLLBACK_ALLOW_DESTRUCTIVE` names every id it would reverse — judged under the migrate lock against the rows it is about to reverse. Beside a live embedded `x dev` it is run by that server (`POST /_x/db/rollback`), as `migrate` is. A change `gen` wrote as `<id>` + `<id>_concurrently` takes `--steps 2`; one step reverses the second half and says the first is still applied. `--json`: `data` = `{ reverted, steps, files }`. `As of 2026-11-19` | | `reset` | delete the embedded data directory, then migrate | **embedded database only** — against an external Postgres it exits `X_NOT_IMPLEMENTED` and tells you to drop and recreate it yourself | | `seed [<name>]` | apply the app's seeds — every one this environment takes, or the one named | **replayable**: a second run writes nothing and raises nothing, on Postgres as well as in memory. One transaction per seed, so one bad fixture graph cannot roll back the seeds that already landed. `--dry-run` reports what each would write and writes nothing. Beside a live `x dev` holding the embedded database, `seed` (`--dry-run` and `--generate` included) is refused `X_DEV_ALREADY_RUNNING`, its fix `x stop --json && x db seed … && x dev` (`As of 2026-11-19`); `backfill --write` is refused the same way, `backfill` listing and dry runs are not | | `branch list` | every **managed** branch of this database: name, location, created-at, size | managed means this framework made it — external, a database carrying `createBranch()`'s `comment on database` marker; embedded, a `pgdata-<name>` directory. A branch cloned by the pre-1.2.x `psql` shell-out carries no marker, so it is absent here and `delete` refuses it → [Known gaps](Known-Gaps). `size` reads `unknown` on the embedded database — measuring it is a full directory walk. The delete path only touches what this lists | @@ -1463,7 +1463,7 @@ x tasks [list|show <name>|run <name>] [--count n] [--production] [--json] |---|---| | `list` | every registered `task`: cron, timezone, catch-up policy, the jobs it enqueues, the occurrence it **last** fired and its next one | | `show <name>` | the same plus the cron in words and the next `--count` occurrences (default 5, max 50) | -| `run <name>` | fire the task now: each job its occurrence enqueues goes onto the app's queue, through `TaskHandle.enqueue()` (the admin's run-now path). The scheduler's watermark is untouched, so the next scheduled occurrence still fires. Where the environment resolves `production` it needs `--production` (`X_CLI_BAD_FLAG` otherwise, nothing queued); beside an `x dev` holding the embedded database it is refused `X_DEV_ALREADY_RUNNING` with the stop–run–restart fix. `--json`: `data` = `{ task, jobs: [{ job, id, runId, deduped }] }`. `x g cron-job <name>` prints `bunx x tasks run <name>.schedule` as its next step. `As of 2026-11-19` | +| `run <name>` | fire the task now: each job its occurrence enqueues goes onto the app's queue, through `TaskHandle.enqueue()` (the admin's run-now path). The scheduler's watermark is untouched, so the next scheduled occurrence still fires. Where the environment resolves `production` it fires only when asked by name — `--production`, or `ULTIMATE_TASK_RUN=<name>` for a container whose command line is fixed — as `x db seed --tier` / `ULTIMATE_SEED_TIER` do (`X_TASK_RUN_PRODUCTION` otherwise, nothing queued); beside an `x dev` holding the embedded database it is refused `X_DEV_ALREADY_RUNNING` with the stop–run–restart fix. `--json`: `data` = `{ task, jobs: [{ job, id, runId, deduped }] }`. `x g cron-job <name>` prints `bunx x tasks run <name>.schedule` as its next step. `As of 2026-11-19` | | `--json` field | Is | |---|---| diff --git a/wiki/Caching-And-Invalidation.md b/wiki/Caching-And-Invalidation.md index 1b290f041..e2c96a35f 100644 --- a/wiki/Caching-And-Invalidation.md +++ b/wiki/Caching-And-Invalidation.md @@ -114,7 +114,7 @@ export const publishPost = action({ |---|---|---| | Tier 1 request memo | drop entries carrying the tag | immediate, same request | | Tier 2 in-process LRU (**all instances**) | tag-invalidation message on NATS | ~ms, best-effort; a missed message costs a stale read until TTL, never a wrong write | -| Tier 3 Redis | paged `ZSCAN` over the tag's sorted set, `ZREM` of what was read, `UNLINK` per value key, re-`ZADD` (at its read score) of any member whose `UNLINK` was refused. Sweep before delete, `As of 2026-11`: a fill from another replica landing mid-bust can no longer be left in no bucket, stale for its whole TTL. An inbound invalidation broadcast skips this shared tier — the sender's bust already cleared it for every replica | immediate, inside the fan-out; 10k keys in 25 round trips | +| Tier 3 Redis | paged `ZSCAN` over the tag's sorted set, `ZREM` of what was read, `UNLINK` per value key, re-`ZADD … GT` (at its read score, never lowering a later fill's; Redis ≥ 6.2) of any member whose `UNLINK` was refused. Sweep before delete, `As of 2026-11`: a fill from another replica landing mid-bust can no longer be left in no bucket, stale for its whole TTL. An inbound broadcast skips this shared tier only when the sender's frame names the same namespace (same build); another build's, or an older pod's, busts it. `As of 2026-11-19` | immediate, inside the fan-out; 10k keys in 25 round trips | | ISR pages | routes whose `revalidate.tags` include the tag are marked stale → regenerated in background | next request serves stale, regen enqueued as a job | | CDN | purge by surrogate key through the configured `PurgeDriver` — a row bust purges `post:1` and `post`, a collection bust `e:post` and `post` | seconds; `stale-while-revalidate` covers the gap | | Live queries | the same commit already flows through logical replication | **independent path** — realtime does not depend on cache invalidation | diff --git a/wiki/Configuration.md b/wiki/Configuration.md index e99a71996..48807c8dc 100644 --- a/wiki/Configuration.md +++ b/wiki/Configuration.md @@ -59,7 +59,7 @@ There is no `url` field. The canonical origin is an env key the app reads at its | field | type | default | notes | |---|---|---|---| | `database.driver` | `'postgres'` | `'postgres'` | one driver; `postgresDriver()` from `@ultimat3/entity` is its only implementation | -| `database.ssl` | `boolean` | `false` | `true` on managed Postgres: the pool the boot opens (every serving role, `x dev`, the migrate step, `x db status`/`recount`/`diagnostics`) adds `sslmode=require` to `DATABASE_URL` and its replica's URL, so a server with no TLS is refused. Added only where no mode is stated: a URL's own `sslmode` (or `ssl`) and a set `PGSSLMODE` always win, in either direction (`withRequiredTls`, `packages/cli/src/runtime-database-ssl.ts`). The same rule reaches every other pool, `As of 2026-11-19`: the replicator's `DATABASE_URL` and `REPLICATION_URL` sessions, `x doctor`'s database probes, `x db branch` and `x deploy verify`'s queue read (`withAppTls`). The embedded database has no wire and ignores it. `As of 2026-11`; before, the key was read by nothing | +| `database.ssl` | `boolean` | `false` | `true` on managed Postgres: the pool the boot opens (every serving role, `x dev`, the migrate step, `x db status`/`recount`/`diagnostics`) adds `sslmode=require` to `DATABASE_URL` and its replica's URL, so a server with no TLS is refused. Added only where no mode is stated: a URL's own `sslmode` (or `ssl`) and a set `PGSSLMODE` always win, in either direction; an empty `sslmode=` states nothing, and the names match case-insensitively (`As of 2026-11-19`) (`withRequiredTls`, `packages/cli/src/runtime-database-ssl.ts`). The same rule reaches every other pool, `As of 2026-11-19`: the replicator's `DATABASE_URL` and `REPLICATION_URL` sessions, `x doctor`'s database probes, `x db branch` and `x deploy verify`'s queue read (`withAppTls`). The embedded database has no wire and ignores it. `As of 2026-11`; before, the key was read by nothing | | `database.rowSecurity` | `boolean` | `false` | every `tenant:` table carries a forced row-security policy (`x db gen`), and a serving role Postgres exempts from it is refused at boot (`X_DB_ROW_SECURITY_BYPASSED`) | | `database.slowStatementMs` | whole ms ≥ 0 | unset: 500 | `As of 31.17.0`. A statement at or over it writes one `db.statement.slow` warn line in **production** — the normalised shape (never a bound value), duration, rows, the request/job id; one line per shape per 10 s, the rest counted as `suppressed`. `0` is off; `NaN`, a negative or a fraction is `X_CONFIG_INVALID` at boot. Outside production the line is off whatever the key says: a test suite's deliberately slow statements are not an incident | | ~~`database.urlEnv`~~ | — | — | **Deleted 2026-08.** Refused at boot since 25.0.0 (`X_CONFIG_INVALID`, naming the replacement). `@ultimat3/db`'s `client.ts` reads `process.env['DATABASE_URL']` as a hardcoded literal, so a different key here could never be honoured. Migration: delete the key; the connection string is `DATABASE_URL` | diff --git a/wiki/Deployment.md b/wiki/Deployment.md index e35f826f5..7a0cc1772 100644 --- a/wiki/Deployment.md +++ b/wiki/Deployment.md @@ -128,7 +128,7 @@ helm upgrade app docker/helm --set roles.worker.retireSeconds=7200 \ --set drain.workerDeadlineSeconds=7500 # 2 h worker; `x deploy --method helm` sets both itself ``` -**`x verify` holds the job to it**: a job whose declared `timeout` exceeds the worker's budget (`drain.workerRetireMs` when above 0, else `drain.workerDeadlineMs`, else `drain.deadlineMs`) reds the `manifest` step with `X_JOB_OUTLASTS_DRAIN`, naming the job, its limit and the budget. A job with no `timeout` is not graded. +**`x verify` holds the job to it**: a job whose declared `timeout` exceeds the worker's budget (`drain.workerRetireMs` when above 0, else when the drain cancels a held job: `drain.workerDeadlineMs`, else `drain.deadlineMs`, less the later hooks' reserve and the 2 s cut-off margin — 21 s of 25 s, `As of 2026-11-19`) reds the `manifest` step with `X_JOB_OUTLASTS_DRAIN`, naming the job, its limit and the budget. A job with no `timeout` is not graded. **Compose stays SIGTERM with `stop_grace_period`**: it has no `preStop`, and a SIGKILL mid-job is worse than a handed-back claim, so size `stop_grace_period` to the drain as below. It is the single-node rung, and makes no such claim → [scale ladder](https://github.com/developerz-ai/ultimate/blob/main/docs/idea/17-scale-ladder.md). diff --git a/wiki/Error-Codes-cli.md b/wiki/Error-Codes-cli.md index 3aef98adb..334ba4313 100644 --- a/wiki/Error-Codes-cli.md +++ b/wiki/Error-Codes-cli.md @@ -190,6 +190,7 @@ Part of [Error codes](Error-Codes): every code `@ultimat3/cli` registers. `x err | `X_STORAGE_UNWRITABLE` | the storage disk this process needs cannot be written to | a hardened container (`readOnlyRootFilesystem: true`) with no writable volume at the embedded disk's root, or `S3_ENDPOINT` set with `S3_BUCKET` empty | mount a writable volume at the path in the message, or set `S3_ENDPOINT` + `S3_BUCKET` to use object storage. `x doctor --json` shows which binding this process resolved | | `X_STREAM_ALREADY_FLUSHED` | a response header was written after the stream flushed | `setCookie()`, `deleteCookie()` or `setRedirect()` ran inside a `<Hole>` on a `render: 'stream'` page, after the status and headers left with the first flush. The hole shows its `error` markup and the monitor hears it | `load: async () => { setCookie(name, value); return data; }` in `defineRoute`, never under a `<Hole>` | | `X_SUPERSEDED_WORKAROUND` | a workaround the framework has since retired is still in the app | a comment or doc note names a workaround for a feature that has since shipped | `x doctor --json` — each finding names the file, the release that retired the workaround and its replacement | +| `X_TASK_RUN_PRODUCTION` | x tasks run refused to fire a task in production unasked | `x tasks run <name>` while `ULTIMATE_ENV` resolves `production`, with neither `--production` nor `ULTIMATE_TASK_RUN=<name>`. A manual fire there is real work beside the next scheduled occurrence (the watermark is never moved), so it is asked for by name, as `x db seed` asks for a `dev` tier. Its own code and not `X_CLI_BAD_FLAG`: the argv was well formed and the answer is still no. Nothing is queued | `x tasks run <name> --production --json`. For a container whose command line is fixed, `ULTIMATE_TASK_RUN=<name>` says the same thing, and the cause names it too | | `X_TEST_BUDGET_INVALID` | a test memory budget or worker cap env var does not parse | ULTIMATE_TEST_MEMORY_BUDGET is not a size like 3g/512m, or ULTIMATE_TEST_MAX_WORKERS is not a positive integer | ULTIMATE_TEST_MEMORY_BUDGET=3g x verify # or unset it; ULTIMATE_TEST_MAX_WORKERS takes a positive integer | | `X_TEST_FAILED` | a test type failed | a red test — or, from `x test`, a run in which every selected test skipped itself (`ran 0`, `skipped N`), which checked nothing (`As of 2026-11-19`) | `x test --json`. A failed run's fix reruns the first failing file alone, `x test <type> --filter <file> --workers 1`, and its cause names up to five failing files; the exact `bun test …` invocation only when bun named no file. An all-skipped run's fix starts the test services, then reruns the same selection | | `X_TEST_NO_FILES` | the test selection matched no files | a type or `--filter` that matches nothing, or `x test` run outside the app | `x test --affected --dirty` runs what your edits reach; or name a path that exists (`x test --filter <path>`), or point it at the right root: `x test --cwd <repo root>`. A green run over zero files is the most expensive false pass | diff --git a/wiki/Error-Codes.md b/wiki/Error-Codes.md index def2a80fa..f9b0eb9f2 100644 --- a/wiki/Error-Codes.md +++ b/wiki/Error-Codes.md @@ -39,7 +39,7 @@ Generated from the owner pages by `bun run scripts/error-code-pages.ts --write`; | `@ultimat3/ai` | [Error-Codes-ai](Error-Codes-ai) | 36 | | `@ultimat3/auth` | [Error-Codes-auth](Error-Codes-auth) | 30 | | `@ultimat3/cache` | [Error-Codes-cache](Error-Codes-cache) | 8 | -| `@ultimat3/cli` | [Error-Codes-cli](Error-Codes-cli) | 228 | +| `@ultimat3/cli` | [Error-Codes-cli](Error-Codes-cli) | 229 | | `@ultimat3/core` | [Error-Codes-core](Error-Codes-core) | 76 | | `@ultimat3/db` | [Error-Codes-db](Error-Codes-db) | 42 | | `@ultimat3/entity` | [Error-Codes-entity](Error-Codes-entity) | 44 | @@ -1260,6 +1260,7 @@ Generated from the owner pages by `bun run scripts/error-code-pages.ts --write`; | X_SURFACE_BOUNDARY | [render](Error-Codes-render) | | X_SW_SCOPE_INVALID | [pwa](Error-Codes-pwa) | | X_SYNC_UNCONFIGURED | [realtime](Error-Codes-realtime) | +| X_TASK_RUN_PRODUCTION | [cli](Error-Codes-cli) | | X_TELEMETRY_SAMPLER_ARG_INVALID | [core](Error-Codes-core) | | X_TEMPLATE_CODEMOD_MISSING | [scripts](Error-Codes-scripts) | | X_TENANCY_ACTOR_MISMATCH | [entity](Error-Codes-entity) | diff --git a/wiki/Queries-And-Live-Queries.md b/wiki/Queries-And-Live-Queries.md index 6187f958c..7442573ac 100644 --- a/wiki/Queries-And-Live-Queries.md +++ b/wiki/Queries-And-Live-Queries.md @@ -220,7 +220,7 @@ export const queries = queryClient<Api['queries']>({ baseUrl }); // reads | Why two clients and not one | actions and queries are two registries (`defineApi`'s `actions:` and `queries:` keys) answering two methods. A read taken off the action client is a name that does not exist on `Api['actions']` — a compile error, which is the point | | Types | the read's own `input` and row type. A list read answers `readonly TRow[]`, `limit(1)` included; a `single: true` read answers `TRow` and rejects with `X_NOT_FOUND` when the route 404s | | Failures | the server's own code, off `problem+json` — `X_INPUT_INVALID` stays `X_INPUT_INVALID`. A gateway answering HTML, a network fault and a 2xx body that is not JSON are `X_CLIENT_TRANSPORT_FAILED`, the same code an action's client answers. It was `X_RPC_FAILED` until 21.0.0 | -| Rows are JSON, with their instants revived | what the body parses to, plus every value the server answered as a `Date` handed back as one (`As of 2026-10`, #710): the route names them in `x-ultimate-dates` by path — one entry per column of a list — and `clientTransport` revives exactly those. The body and the OpenAPI document are unchanged; a client that ignores the header reads ISO strings. A query's rows are never parsed on the way out (a declared `rows:` publishes structure, it parses nothing), so the header is how the row type's `Date` stays true | +| Rows are JSON, with their instants revived | what the body parses to, plus every value the server answered as a `Date` handed back as one (`As of 2026-10`, #710): the route names them in `x-ultimate-dates` by path — one entry per column of a list — and `clientTransport` revives exactly those. The body and the OpenAPI document are unchanged; a client that ignores the header reads ISO strings. A query's rows are never parsed on the way out (a declared `rows:` publishes structure, it parses nothing), so the header is how the row type's `Date` stays true. The header is capped at 4,096 bytes (`WIRE_DATES_MAX_BYTES`): an answer whose instants need one path each — a `string \| Date` column, a `[label, instant]` tuple — past that is sent with no `x-ultimate-dates` (and no `dates:` line), the client reads those instants as ISO strings, and the operation is logged once at `warn` as `http.wire_dates_dropped`. `As of 2026-11-19`. | | `then` is not a read | the proxy answers `undefined` for it, so `await queries` resolves to the client instead of fetching `/_x/query/then`. Same rule in `rpc` | ## A file at a signed URL — `download:` diff --git a/wiki/Scheduled-Tasks.md b/wiki/Scheduled-Tasks.md index 110317b4e..10b22f9b1 100644 --- a/wiki/Scheduled-Tasks.md +++ b/wiki/Scheduled-Tasks.md @@ -162,7 +162,7 @@ Role table and drain sequence: [Deployment](Deployment). |---|---| | `x tasks list --json` | the descriptor — `name`, `cron`, `tz`, `catchUp`, `maxCatchUp`, `jobs` — plus the resolved **`next`** occurrence, rendered in the task's own `tz`, and its `nextMs` epoch instant; and the **`last`** fire (`last`, `lastMs`, `lastFiredAtMs` — `null` before the first), read from the queue, which `x tasks` opens when a task is declared. All derived, never declared fields | | `x tasks show <name> --json` | the same, plus the cron in words (`describe`) and the next N occurrences (`--count`, default 5) | -| `x tasks run <name> --json` | fires the task now: each job its occurrence enqueues goes onto the app's queue (`TaskHandle.enqueue()`, the run-now path; the scheduler's watermark is untouched, so the next scheduled occurrence still fires). Beside an `x dev` on the embedded database it refuses with the stop–run–restart fix; where the environment resolves `production` it needs `--production`. `x g cron-job` prints it as its next step. `As of 2026-11-19` | +| `x tasks run <name> --json` | fires the task now: each job its occurrence enqueues goes onto the app's queue (`TaskHandle.enqueue()`, the run-now path; the scheduler's watermark is untouched, so the next scheduled occurrence still fires). Beside an `x dev` on the embedded database it refuses with the stop–run–restart fix; where the environment resolves `production` it needs `--production` (or `ULTIMATE_TASK_RUN=<name>` in a container), else `X_TASK_RUN_PRODUCTION`. `x g cron-job` prints it as its next step. `As of 2026-11-19` | | `/admin/jobs/tasks` | the jobs dashboard every `defineAdmin()` serves: schedule, zone, last fire, next fire (`nextTaskRun`), paused; pause, resume and run now behind `job:manage` → [Admin dashboard](Admin-Dashboard#the-jobs-dashboard) | | MCP `admin.x_job_tasks.list`, `admin.action.job.task.run-now` | the same screen and actions as admin MCP tools, same authz: listing needs `job:read`, run-now `job:manage` — which `x new`'s `admin` role does **not** hold (it holds `job:read`); grant it in `apps/web/shared/roles.ts` to see the tool | | `/_x` dev panel | the jobs tab: the dev process's tasks beside its queues and runs | diff --git a/wiki/Upgrading.md b/wiki/Upgrading.md index 98d6ed23c..cc9f6b4d7 100644 --- a/wiki/Upgrading.md +++ b/wiki/Upgrading.md @@ -329,7 +329,7 @@ A setter still on a package's `.` barrel is `X_ADAPTER_PORT_INCOMPLETE` on the ` | `x exercise` with no `--seed`, and so `x verify`'s `exercise` step, runs one constant seed (**31.47.0**) where each run drew a random one, and `seed` in `.x/exercise.json` is always the number used, never `null`. One tree now gets one verdict, but an `exercise.unprovenMax` measured under random seeds can sit just below the constant seed's figure, so the first gate after the hop can be `X_EXERCISE_UNPROVEN_ABOVE_FLOOR`. `x upgrade` writes a figure only where the app states none, and never raises one | `x exercise --json`, then fix the helper or override each `unproven` record names: pick rows by what they are, never by id order, and assume no order between sized calls ([Testing](Testing)). If the figure that remains is the honest one, raising `unprovenMax` to it is your own reviewed edit of `x.verify.json`. `x exercise --seed random` looks for seed-dependent helpers | | `x upgrade` stops requiring an `e2e` suite no codemod wrote (**31.47.1**): an app with pages but no `apps/web/site/page.tsx` was left on `X_VERIFY_SUITE_VANISHED`. Rerunning `x upgrade` at the target no longer replays every codemod | nothing: `x upgrade` applies codemod `e2e-suite-floor`, which writes a `page.e2e.test.ts` beside the shortest parameter-free page, or moves `e2e` to `skip` with its why when no page can be visited. To apply codemods an older CLI left behind: `x upgrade codemods --from 0.0.0 --json` | | 24 shipped guards' fixes change (**31.49.0**), built in; their findings do not: `animated-layout-property`, `bare-error`, `error-declared`, `focus-visible`, `image-dimensions`, `island-mount-clears`, `native-confirm`, `raw-breakpoint`, `raw-colour`, `raw-fetch`, `raw-interval`, `raw-length`, `raw-motion`, `raw-shadow`, `raw-z-index`, `repo-await-in-loop`, `repo-raw-sql`, `repo-unbounded`, `runtime-pin`, `semantic-interactive`, `unbounded-fanout`, `undeclared-custom-property`, `undefined-style-class` and `unzoned-date` end their fix on the one step that re-checks it (`then: x verify --only boundaries`) in place of `then: x verify`, which started the whole gate. A copy still in `guards/` keeps the old text until `x upgrade` migrates it to the release after 31.48.0 | nothing | -| **Upgrading to 31.49.0: what to check**, in this order. `As of 2026-11-19`; each row below names one check, and [`CHANGELOG.md`](https://github.com/developerz-ai/ultimate/blob/main/CHANGELOG.md)'s `[Unreleased]` carries the detail. Five `app.config.ts` keys that were validated and read by nothing are **read** now (the next row) | run the rows in order, then `x verify` | +| **Upgrading to the next release: what to check**, in this order. `As of 2026-11-19`; each row below names one check, and [`CHANGELOG.md`](https://github.com/developerz-ai/ultimate/blob/main/CHANGELOG.md)'s `[Unreleased]` carries the detail. Five `app.config.ts` keys that were validated and read by nothing are **read** now (the next row) | run the rows in order, then `x verify` | | `app.config.ts` keys now read (**31.49.0**): `roles` — a `ROLE` it does not list refuses to boot (`X_CONFIG_INVALID`, `meta.key: 'roles'`; `ROLE=migrate` exempt); `database.ssl: true` adds `sslmode=require` on **every** pool — serving roles, `x dev`, migrate, the replicator's `DATABASE_URL` and `REPLICATION_URL`, `x doctor`'s probes, `x db branch`, `x deploy verify` — unless the URL or `PGSSLMODE` states a mode; `cache.defaultTtlMs` sets the boot-built `lru`/`redis` lease (a Redis rung held such values 300 s, now 60 s by default; `0` is refused); `jobs.maxAttempts` (default now `3`, not the documented `5`) and `jobs.backoff` apply to every job declaring no `retry` | `grep -n 'roles\|ssl\|defaultTtlMs\|maxAttempts\|backoff' app.config.ts`. `roles`: every `ROLE` your compose services, Helm values or platform processes start is listed, or drop the key. `ssl: true` against a Postgres without TLS: `database: { ssl: false }` or `?sslmode=disable` in each URL. `defaultTtlMs: 0`: a positive lease. `maxAttempts` / `backoff`: keep them only if they are the retry you want for every job declaring none | | `pwa.enabled`, `pwa.backgroundSync` and `pwa.push` must be real booleans (**31.49.0**), checked even when `enabled` is false: `'false'` used to turn the PWA **on**; a non-list `pwa.categories` / `shortcuts` / `screenshots`, a non-string `neverCache` entry or `site.favicon` are refused too — `X_CONFIG_INVALID` at boot | each a literal `true` or `false` in `app.config.ts`'s `pwa` block | | a records channel keyed by a param that is not the tenant column (a `roomId` topic) delivers a tenanted row only to members of that row's tenant, live and on replay (**31.49.0**); every other member receives the seq alone | nothing, unless a channel deliberately fanned one org's rows out to members of other orgs: that feed needs its own untenanted table or a channel keyed by the tenant column | @@ -347,6 +347,12 @@ A setter still on a package's `.` barrel is `X_ADAPTER_PORT_INCOMPLETE` on the ` | `x test <type>` exits 1 with `X_TEST_FAILED` when every test it selected skipped itself (**31.49.0**), where it exited 0 having checked nothing; `x verify` is unaffected | a script calling `x test live` (or any type) without the services: `docker compose -f docker/docker-compose.test.yml up -d --wait && set -a && . docker/test-services.env && set +a` first, or drop the call | | `x dev` is `✗ dev ready` while migrations on disk are ahead of its database (`X_APP_MIGRATIONS_UNAPPLIED`) or an applied one was edited (**31.49.0**), and a schema finding no longer restarts it; on the embedded database `x db gen` refuses an edited applied migration (`X_MIGRATION_CONFLICT`, nothing written) | a workflow starting `x dev` before its first migrate: `x db migrate`. A script waiting for a fresh `✓` banner after `x db gen`: read `/_x` (or `x dev --json --once`). An edited applied migration: restore it (`git checkout <rev> -- packages/db/migrations/<id>.sql`), or rebuild the dev database with `x stop --json && x db reset` | | `x policy explain --json` (**31.49.0**): a row whose predicate reads request input it was not given is `verdict: "needs-input"`, `allowed: null`, counted in `data.pending` — it was `allowed: false` | a script reading `!allowed` as denied: `verdict === "deny"`. To decide such a row: `x policy explain <subject> --input '<json>'` | +| an action's `Date` output now reaches the typed client as a `Date` (**31.49.0**), on the plain and enveloped 200 and in streamed `chunk` / `done` frames; past 4,096 bytes of `x-ultimate-dates` an answer's instants stay ISO strings (`http.wire_dates_dropped`, logged once) | island code that called string methods on such a value (`.slice`, `.localeCompare`) must change: `grep -rn 'useAction\|clientStream' apps/web`, then read each such field as a `Date` | +| a scheduled fan-out entry whose `tenant()` throws or answers empty (**31.49.0**) fails the whole occurrence: nothing queued, `jobs.scheduler.entry-refused` logged naming the task, job and entry, retried every tick until repaired | nothing, unless the log shows that line: repair the declaration or the data, and the next tick queues the whole occurrence | +| `x db rollback` against an external `DATABASE_URL` on another machine (**31.49.0**) needs `ROLLBACK_ALLOW_DESTRUCTIVE` naming each id, whatever `ULTIMATE_ENV` says (a compose service host like `db` included) | a script rolling back such a database: `ROLLBACK_ALLOW_DESTRUCTIVE=<id>[,<id>…] x db rollback --json` | +| `x dev` runs only the roles `app.config.ts` `roles` declares, when set (**31.49.0**), and logs the ones it left out; `x dev --role` naming only undeclared roles is `X_CONFIG_INVALID` | an app declaring `roles`: list every role `x dev` should run (the scheduler and sync included) | +| `x tasks run <name>` (new, **31.49.0**) under `ULTIMATE_ENV=production` fires only with `--production` or `ULTIMATE_TASK_RUN=<name>`, else `X_TASK_RUN_PRODUCTION` | nothing | +| `X_JOB_OUTLASTS_DRAIN` with `drain.workerRetireMs: 0` grades against the drain's real cancel (**31.49.0**), the later hooks' reserve and the 2 s margin before the deadline: 21 s of a 25 s `drain.deadlineMs`, was 23 s | `x verify --only manifest --json`; a job it names: raise `drain.workerRetireMs` or lower its `timeout` | | fix text changed, codes unchanged (**31.49.0**): `X_ENV_MISSING` is the line to add to the file the environment loads; `X_CATALOG_MISSING_KEYS`'s comment half; `X_TEST_FAILED` reruns the first failing file; on the embedded development database `X_MIGRATION_CONFLICT` and `X_MIGRATION_ROLLBACK_DESTRUCTIVE` lead with `x stop --json && x db reset` | anything matching those strings exactly: `grep -rn 'x env check\|as ⟦key⟧' <your scripts>` and match the new text | | new scaffolds (**31.49.0**): `docker/docker-compose.test.yml` is named `<app>-test-<hash of the directory>` with ports picked per directory, and `package.json` declares `@ultimat3/realtime` | nothing; an existing app keeps its `name:` and dependency set. One importing `@ultimat3/realtime` without declaring it: `bun add --exact @ultimat3/realtime@$(bun -p "require('./package.json').dependencies['@ultimat3/core']")`. Sharing a test stack with a same-named app: its own `name:` and ports in the compose file and `docker/test-services.env` | From 64a851a51a33c126f51f74403bbbb162b5e2e7c7 Mon Sep 17 00:00:00 2001 From: sebi <gore.sebyx@yahoo.com> Date: Thu, 19 Nov 2026 14:37:46 -0500 Subject: [PATCH 8/9] fix: measured budget raises for the sweep's client fixes --- CHANGELOG.md | 1 + examples/dummy/apps/web/app/feed/page.tsx | 13 ++++++++++++- examples/dummy/apps/web/app/posts/board/page.tsx | 13 ++++++++++++- examples/dummy/apps/web/app/posts/new/page.tsx | 9 ++++++++- examples/dummy/apps/web/app/runs/health/page.tsx | 9 ++++++++- examples/dummy/apps/web/app/runs/page.tsx | 14 +++++++++++++- examples/dummy/apps/web/app/settings/page.tsx | 13 ++++++++++++- examples/dummy/x.manifest.json | 14 +++++++------- 8 files changed, 73 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 40631d28c..813e774c8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -234,6 +234,7 @@ Semver applies from 1.0.0. A breaking change to a documented API needs a major - `x upgrade` recognises an unedited `undeclared-env` guard copy from an earlier release again; its released-form hash had been overwritten by a later refresh. - scripts: the public-API lock judges an optional trailing parameter added to a class method as compatible, as it does for a function. - test(action, query): browser client bundle pins raised by measured growth — rpc 25,281 B (≤ 25,303), query client 16,182 B (< 16,186): `clientStream`'s chunk `dates:` revival and coded mid-body cut (+272 B), and the unkeyed-write-once rule (+31 B). +- **examples/dummy:** six route budgets raised by their measured growth against origin/main built the same way — `/feed` `211kb` → `211.4kb`, `/posts/board` `110.5kb` → `111.3kb`, `/posts/new` and `/runs/health` `33.1kb` → `33.2kb`, `/runs` `243.6kb` → `244.3kb`, `/settings` `107kb` → `107.8kb`: the hydration runtime's own-wrapper props (+100 B), the router's fragment fixes (+45 B), `clientStream`/`clientTransport` (+31 B in the page boot, about +300 B in each island calling `rpc`), and the ui, i18n and `isRtl` fixes each island carries. The numbers per chunk are in the comment above each budget, where `bun run budget-raises` reads them. ## Releases diff --git a/examples/dummy/apps/web/app/feed/page.tsx b/examples/dummy/apps/web/app/feed/page.tsx index f8c1ccf57..1f2b3bb67 100644 --- a/examples/dummy/apps/web/app/feed/page.tsx +++ b/examples/dummy/apps/web/app/feed/page.tsx @@ -237,7 +237,18 @@ export const config = defineRoute({ // not the queue's holding the write queued), and the action client's title for // `X_REPLAY_PRINCIPAL_MISMATCH`, the refusal of an offline write replayed under another session. // Raised 210.6kb → 211kb. - budget: { js: '211kb' }, + // measured: 216404 B (2026-11-19; x build --target static) — why: +436 B, the feed island +260 B + // (96,473 → 96,733): `isRtl` reading a script subtag (`az-Arab` rtl), `t.has` true for a select + // or ordinal family authored only in plural forms, `navigate()`'s same-page fragment and the + // hotkey layer ignoring Enter while an IME composes (`keyCode 229`); the page boot +31 B (85,230 + // → 85,261), `clientTransport` sending a write with no idempotency key once; the client router + // +45 B (29,910 → 29,955), a soft navigation to a malformed fragment (`#50%`) still runs scripts + // and fires `ultimate:navigated`, and `navigate()` to a fragment of the page on screen scrolls + // instead of refetching and disposing its islands; the inline hydration runtime +100 B, an island + // boots with the props inside its own wrapper, not the first script in the document with its id + // (a modal's island took the page's). Against 215,968, origin/main built the same way. Raised + // 211kb → 211.4kb. + budget: { js: '211.4kb' }, meta: ({ t }) => ({ title: t('app.feed.metaTitle'), robots: { index: false } }), }); diff --git a/examples/dummy/apps/web/app/posts/board/page.tsx b/examples/dummy/apps/web/app/posts/board/page.tsx index 25db6060b..895d0a617 100644 --- a/examples/dummy/apps/web/app/posts/board/page.tsx +++ b/examples/dummy/apps/web/app/posts/board/page.tsx @@ -93,7 +93,18 @@ export const config = defineRoute({ // measured: 113106 B (2026-11-18; x build --target static, against 112,991) — why: +115 B, the // action client's title for `X_REPLAY_PRINCIPAL_MISMATCH`, the refusal of an offline write // replayed under another session. Raised 110.4kb → 110.5kb. - budget: { js: '110.5kb' }, + // measured: 113869 B (2026-11-19; x build --target static) — why: +763 B, the board island +618 B + // (79,258 → 79,876): `clientStream` reviving a chunk frame's `dates:` and coding a mid-body cut + // as `X_CLIENT_TRANSPORT_FAILED`, `clientTransport` sending a write with no idempotency key once, + // `isRtl` reading a script subtag (`az-Arab` rtl), `t.has` true for a select or ordinal family + // authored only in plural forms, and a sortable item deleted by a live update while lifted no + // longer blocking keyboard sorting; the client router +45 B (29,910 → 29,955), a soft navigation + // to a malformed fragment (`#50%`) still runs scripts and fires `ultimate:navigated`, and + // `navigate()` to a fragment of the page on screen scrolls instead of refetching and disposing + // its islands; the inline hydration runtime +100 B, an island boots with the props inside its own + // wrapper, not the first script in the document with its id (a modal's island took the page's). + // Against 113,106, origin/main built the same way. Raised 110.5kb → 111.3kb. + budget: { js: '111.3kb' }, load: () => memberQueries.orgPosts({ orgId: useActor().orgId }), meta: ({ t }) => ({ title: t('app.board.metaTitle'), robots: { index: false } }), }); diff --git a/examples/dummy/apps/web/app/posts/new/page.tsx b/examples/dummy/apps/web/app/posts/new/page.tsx index d6fa0e4ea..f84524971 100644 --- a/examples/dummy/apps/web/app/posts/new/page.tsx +++ b/examples/dummy/apps/web/app/posts/new/page.tsx @@ -116,7 +116,14 @@ export const config = defineRoute({ // raised 33kb → 33.1kb. measured: 33822 B (2026-11-12; x build --target static) — why: the client // router grew 29,764 → 29,884 (+120 B): a stylesheet that fails to load on navigation now forces a // full load and keeps the old sheets, so a page is never left unstyled. - budget: { js: '33.1kb' }, + // measured: 33993 B (2026-11-19; x build --target static) — why: +145 B, no island of its own: + // the client router +45 B (29,910 → 29,955), a soft navigation to a malformed fragment (`#50%`) + // still runs scripts and fires `ultimate:navigated`, and `navigate()` to a fragment of the page + // on screen scrolls instead of refetching and disposing its islands; the inline hydration runtime + // +100 B, an island boots with the props inside its own wrapper, not the first script in the + // document with its id (a modal's island took the page's). Against 33,848, origin/main built the + // same way. Raised 33.1kb → 33.2kb. + budget: { js: '33.2kb' }, /** * The org the draft is written in, and what the last submission left: `createPost` declares * `native`, so a refused draft lands back HERE (`refusal: () => '/posts/new'`) and this read — diff --git a/examples/dummy/apps/web/app/runs/health/page.tsx b/examples/dummy/apps/web/app/runs/health/page.tsx index 6dcae2da9..5612b57da 100644 --- a/examples/dummy/apps/web/app/runs/health/page.tsx +++ b/examples/dummy/apps/web/app/runs/health/page.tsx @@ -60,7 +60,14 @@ export const config = defineRoute({ // raised 33kb → 33.1kb. measured: 33822 B (2026-11-12; x build --target static) — why: the client // router grew 29,764 → 29,884 (+120 B): a stylesheet that fails to load on navigation now forces a // full load and keeps the old sheets, so a page is never left unstyled. - budget: { js: '33.1kb' }, + // measured: 33993 B (2026-11-19; x build --target static) — why: +145 B, no island of its own: + // the client router +45 B (29,910 → 29,955), a soft navigation to a malformed fragment (`#50%`) + // still runs scripts and fires `ultimate:navigated`, and `navigate()` to a fragment of the page + // on screen scrolls instead of refetching and disposing its islands; the inline hydration runtime + // +100 B, an island boots with the props inside its own wrapper, not the first script in the + // document with its id (a modal's island took the page's). Against 33,848, origin/main built the + // same way. Raised 33.1kb → 33.2kb. + budget: { js: '33.2kb' }, load: async ({ url }): Promise<RunHealthData> => { // The kill switch first: switched off, the page does not exist and neither read is sent. assertCoded( diff --git a/examples/dummy/apps/web/app/runs/page.tsx b/examples/dummy/apps/web/app/runs/page.tsx index 91fcb21fd..0e261eabb 100644 --- a/examples/dummy/apps/web/app/runs/page.tsx +++ b/examples/dummy/apps/web/app/runs/page.tsx @@ -204,7 +204,19 @@ export const config = defineRoute({ // not the queue's holding the write queued), and the action client's title for // `X_REPLAY_PRINCIPAL_MISMATCH`, the refusal of an offline write replayed under another session. // Raised 243.1kb → 243.6kb. - budget: { js: '243.6kb' }, + // measured: 250095 B (2026-11-19; x build --target static) — why: +745 B, the run console +569 B + // (129,855 → 130,424): `clientStream` reviving a chunk frame's `dates:` and coding a mid-body cut + // as `X_CLIENT_TRANSPORT_FAILED`, `clientTransport` sending a write with no idempotency key once, + // `isRtl` reading a script subtag (`az-Arab` rtl), `t.has` true for a select or ordinal family + // authored only in plural forms, Escape in a `Popover` or `Menu` no longer closing the enclosing + // `Dialog`, and a `DateRangePicker` pick calling `onChange` once; the page boot +31 B (85,230 → + // 85,261), the unkeyed write sent once; the client router +45 B (29,910 → 29,955), a soft + // navigation to a malformed fragment (`#50%`) still runs scripts and fires `ultimate:navigated`, + // and `navigate()` to a fragment of the page on screen scrolls instead of refetching and + // disposing its islands; the inline hydration runtime +100 B, an island boots with the props + // inside its own wrapper, not the first script in the document with its id (a modal's island took + // the page's). Against 249,350, origin/main built the same way. Raised 243.6kb → 244.3kb. + budget: { js: '244.3kb' }, // The URL rides along: the "created between" filter is read off it, in the member's zone. load: async ({ url }) => ({ connections: await memberQueries.runConnections({ orgId: useActor().orgId }), diff --git a/examples/dummy/apps/web/app/settings/page.tsx b/examples/dummy/apps/web/app/settings/page.tsx index c08adbd86..cbc4a965c 100644 --- a/examples/dummy/apps/web/app/settings/page.tsx +++ b/examples/dummy/apps/web/app/settings/page.tsx @@ -181,7 +181,18 @@ export const config = defineRoute({ // measured: 109549 B (2026-11-18; x build --target static, against 109,434) — why: +115 B, the // action client's title for `X_REPLAY_PRINCIPAL_MISMATCH`, the refusal of an offline write // replayed under another session. Raised 106.9kb → 107kb. - budget: { js: '107kb' }, + // measured: 110322 B (2026-11-19; x build --target static) — why: +773 B, the settings island + // +628 B (75,701 → 76,329): `clientStream` reviving a chunk frame's `dates:` and coding a + // mid-body cut as `X_CLIENT_TRANSPORT_FAILED`, `clientTransport` sending a write with no + // idempotency key once, `isRtl` reading a script subtag (`az-Arab` rtl), `t.has` true for a + // select or ordinal family authored only in plural forms, and `SearchableSelect` ignoring Enter, + // Escape and the arrows while an IME composes; the client router +45 B (29,910 → 29,955), a soft + // navigation to a malformed fragment (`#50%`) still runs scripts and fires `ultimate:navigated`, + // and `navigate()` to a fragment of the page on screen scrolls instead of refetching and + // disposing its islands; the inline hydration runtime +100 B, an island boots with the props + // inside its own wrapper, not the first script in the document with its id (a modal's island took + // the page's). Against 109,549, origin/main built the same way. Raised 107kb → 107.8kb. + budget: { js: '107.8kb' }, meta: ({ t }) => ({ title: t('app.settings.metaTitle'), robots: { index: false } }), }); diff --git a/examples/dummy/x.manifest.json b/examples/dummy/x.manifest.json index 797cf5e03..6b2eadcb0 100644 --- a/examples/dummy/x.manifest.json +++ b/examples/dummy/x.manifest.json @@ -1,6 +1,6 @@ { "manifestVersion": 1, - "buildId": "a2d7e691a4694854", + "buildId": "a1a1a2ca7e7b943a", "app": { "name": "@postly/root", "version": "0.0.1" @@ -495,7 +495,7 @@ "revalidateTags": [], "surface": "app", "budget": { - "js": "211kb" + "js": "211.4kb" } }, { @@ -539,7 +539,7 @@ "revalidateTags": [], "surface": "app", "budget": { - "js": "110.5kb" + "js": "111.3kb" } }, { @@ -550,7 +550,7 @@ "revalidateTags": [], "surface": "app", "budget": { - "js": "33.1kb" + "js": "33.2kb" } }, { @@ -578,7 +578,7 @@ "revalidateTags": [], "surface": "app", "budget": { - "js": "243.6kb" + "js": "244.3kb" } }, { @@ -589,7 +589,7 @@ "revalidateTags": [], "surface": "app", "budget": { - "js": "33.1kb" + "js": "33.2kb" } }, { @@ -600,7 +600,7 @@ "revalidateTags": [], "surface": "app", "budget": { - "js": "107kb" + "js": "107.8kb" } } ], From 3035f81ad176e54f9b3387d04d967285258e10d9 Mon Sep 17 00:00:00 2001 From: sebi <gore.sebyx@yahoo.com> Date: Thu, 19 Nov 2026 15:53:19 -0500 Subject: [PATCH 9/9] fix(ci): doctor asks each port's owner once, warn-once state reset per test, tutorial 3, compose var escaping --- CHANGELOG.md | 2 +- packages/cli/src/cmd-doctor-probe.test.ts | 8 +++-- packages/cli/src/cmd-doctor.ts | 10 +++--- packages/cli/src/cmd-errors.ts | 9 +++++- packages/cli/src/doctor-port.ts | 18 +++++++++++ packages/cli/src/doctor-warnings.test.ts | 19 ++++++++++++ .../scaffold-container-compose.test.ts | 19 ++++++++++++ .../templates/scaffold-container-compose.ts | 17 +++++++--- packages/testing/src/per-test-reset.test.ts | 31 ++++++++++++++++++- packages/testing/src/per-test-reset.ts | 19 ++++++++---- scripts/primitive-factories.test.ts | 2 +- wiki/Tutorial-03-Auth-And-Admin.md | 13 ++++---- 12 files changed, 140 insertions(+), 27 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 813e774c8..c2b85bb37 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -50,7 +50,7 @@ Semver applies from 1.0.0. A breaking change to a documented API needs a major - Fixes no longer send a worker to a whole run: `X_TEST_NO_FILES` suggests `x test --affected --dirty`, `X_TYPECHECK_FAILED` names the file to edit and `x verify --only typecheck`, and an unknown command whose nearest match runs every suite suggests its `--help`. - A ledger wait says to leave the command running (`bunx x heavy status`), and reads `admission in progress` while no holder is known. - A new app's `CLAUDE.md` lists a worker's commands, its `/feature` and `/verify` skip the gate for a worker given a file set, and `.claude/settings.json` allows `bunx x heavy` and `bunx x stop` in place of the raw typecheck and lint scripts (the `docs-worker-commands` codemod updates `CLAUDE.md` on `x upgrade`). -- `x doctor`: a port another checkout's dev server holds is a warning, not a failure; the suggested port pair is free when asked, and so is the sync role's. +- `x doctor`: a port another checkout's dev server holds is a warning, not a failure; the suggested port pair is free when asked, and so is the sync role's; each taken port is reported once, as a warning or a failure, never both. - `X_JOB_UNREGISTERED` names the job's file and prints the whole import line. - `x db gen` runs one at a time per checkout; its success line names the tables, and "no migration needed" names the migration that already records them. - The test step line reads `ran 2 at once (peak), planned 3`, or `1 worker, one per file (plan: …)`, in place of `2 of 4 of 6 workers`. diff --git a/packages/cli/src/cmd-doctor-probe.test.ts b/packages/cli/src/cmd-doctor-probe.test.ts index a02485926..1e7a1b17c 100644 --- a/packages/cli/src/cmd-doctor-probe.test.ts +++ b/packages/cli/src/cmd-doctor-probe.test.ts @@ -178,8 +178,12 @@ describe('unit · x doctor · the command', () => { codes: readonly string[]; warnings?: readonly { code: string; cause: string }[]; }; - const warned = (data.warnings ?? []).filter((warning) => warning.code === 'X_PORT_IN_USE'); - const failed = data.codes.filter((code) => code === 'X_PORT_IN_USE'); + // About THIS port only: the sync port beside a kernel-picked one is whatever the machine has + // there, and another suite's server may hold it. + const about = (one: { code: string; cause: string }): boolean => + one.code === 'X_PORT_IN_USE' && one.cause.startsWith(`port ${server.port} `); + const warned = (data.warnings ?? []).filter(about); + const failed = (result.findings ?? []).filter(about); expect(warned.length + failed.length).toBe(1); if (warned[0] !== undefined) expect(warned[0].cause).toContain(`port ${server.port} is held by`); diff --git a/packages/cli/src/cmd-doctor.ts b/packages/cli/src/cmd-doctor.ts index e016160fa..e9c53d622 100644 --- a/packages/cli/src/cmd-doctor.ts +++ b/packages/cli/src/cmd-doctor.ts @@ -19,7 +19,7 @@ import { guardedCheck, guardedListing } from './doctor-guarded'; import { shippedGuardsProbe, vendoredGuardWarnings, withGuardListing } from './doctor-guards'; import { offlineFallbackFinding } from './doctor-offline'; import { NO_POOLER_FACT, poolerFindings, withPoolerReport } from './doctor-pooler'; -import { doctorPort, portFindings } from './doctor-port'; +import { doctorPort, ownerAskedOnce, portFindings } from './doctor-port'; import type { DoctorProbe } from './doctor-probe'; import { probeFor } from './doctor-probe'; import { redundantIndexesProbe, withRedundantIndexes } from './doctor-redundant-indexes'; @@ -188,9 +188,11 @@ export async function reportDoctor(probe: DoctorReportProbe): Promise<CommandRes ? Promise.resolve(none) : guardedListing(name, failed, () => read(root), none); }; - // Asked once: `runDoctor` reads the verdict and the report beside it reads the numbers. + // Asked once: `runDoctor` reads the verdict and the report beside it reads the numbers. The port's + // owner too: the verdict and the warnings partition one answer (`ownerAskedOnce`). const pooler = await inApp('pooler', () => probe.pooler(), NO_POOLER_FACT); - const findings = await runDoctor({ ...probe, pooler: async () => pooler }); + const asked = { ...probe, pooler: async () => pooler, portOwner: ownerAskedOnce(probe) }; + const findings = await runDoctor(asked); const guardEntries = await inApp('shipped guards', shippedGuardsProbe, []); const listed = withGuardListing( { @@ -229,7 +231,7 @@ export async function reportDoctor(probe: DoctorReportProbe): Promise<CommandRes // Last, and beside the verdict on `main`: the 31.16.0 checks (`doctor-warnings.ts`). // A copy of a shipped guard among them (`X_GUARD_VENDORED`): a warning, so exit stays. const browser = await guardedListing('browser', failed, () => probe.browser(), undefined); - const warnings = await guardedListing('warnings', failed, () => doctorWarnings(probe), []); + const warnings = await guardedListing('warnings', failed, () => doctorWarnings(asked), []); const superseded = await inApp('superseded workarounds', supersededFindings, []); const floors = await inApp('advisory floors', advisoryFloorFindings, []); // An `x upgrade` driven by a CLI older than the codemod engine left files it owed. diff --git a/packages/cli/src/cmd-errors.ts b/packages/cli/src/cmd-errors.ts index be92703ee..99a5fe25b 100644 --- a/packages/cli/src/cmd-errors.ts +++ b/packages/cli/src/cmd-errors.ts @@ -3,6 +3,7 @@ // invented should come back refused: "no such code", never a plausible-sounding explanation. import { nearestName, singleLine } from '@ultimat3/core'; +import { definedErrorStatus } from '@ultimat3/core/internal/error-status'; import type { ErrorExplanation } from '@ultimat3/mcp'; import { findAppRoot } from './app-root'; import { type AppCodeExplanation, AppCodeUnknownError, explainAppCode } from './cmd-errors-app'; @@ -56,7 +57,13 @@ async function explainOne( cwd: string, reader?: ReaderOptions, ): Promise<CommandResult> { - const explanation = explainErrorCode(code) ?? (await explainGuardCode(code, cwd)); + // A `defineError()` code is an app's, even once this process has loaded the app (`x mcp serve`, a + // test rerun): the registry then knows it, and it was answered as a framework code with no throw + // site in the installed framework, never from the app that declares it. + const appDeclared = definedErrorStatus(code) !== undefined; + const explanation = appDeclared + ? undefined + : (explainErrorCode(code) ?? (await explainGuardCode(code, cwd))); if (explanation === undefined) { // Before the app loads, so the near miss is a framework code the caller mistyped. const suggestion = nearestName( diff --git a/packages/cli/src/doctor-port.ts b/packages/cli/src/doctor-port.ts index 8d6c97962..d9473d8bc 100644 --- a/packages/cli/src/doctor-port.ts +++ b/packages/cli/src/doctor-port.ts @@ -50,6 +50,24 @@ function inAnotherCheckout(owner: PortOwner, root: string | undefined): boolean const ownerLookup = (probe: PortProbe): ((port: number) => Promise<PortOwner>) => probe.portOwner ?? (probe.portFree === portFree ? (port) => portOwner(port) : async () => ({})); +/** + * The probe's owner lookup, asked at most once per port for this run. The verdict and the warnings + * each read the report, and each asked the OS: on a loaded CI runner the first `ss` named nobody (a + * finding) and the second another checkout (a warning) — one taken port, reported twice. Pinned, + * the two halves partition one answer. Per run, never per process: a port's holder changes. + */ +export function ownerAskedOnce(probe: PortProbe): (port: number) => Promise<PortOwner> { + const lookup = ownerLookup(probe); + const asked = new Map<number, Promise<PortOwner>>(); + return (port) => { + const known = asked.get(port); + if (known !== undefined) return known; + const owner = lookup(port); + asked.set(port, owner); + return owner; + }; +} + interface PortReport { readonly findings: readonly Finding[]; readonly warnings: readonly Finding[]; diff --git a/packages/cli/src/doctor-warnings.test.ts b/packages/cli/src/doctor-warnings.test.ts index 4564bbf56..b6810f202 100644 --- a/packages/cli/src/doctor-warnings.test.ts +++ b/packages/cli/src/doctor-warnings.test.ts @@ -98,6 +98,25 @@ describe('unit · x doctor · warnings beside the verdict', () => { expect(result.data).toMatchObject({ warnings: [{ code: 'X_PORT_IN_USE' }] }); }); + // The verdict and the warnings each asked the OS who held the port. On a loaded CI runner the + // first `ss` named nobody (a finding) and the second named another checkout (a warning): one + // taken port, reported twice. One report per run, so the two halves read the same answer. + test('a taken port is looked up once, so it is a finding or a warning, never both', async () => { + const root = appRoot(); + let asked = 0; + const result = await reportDoctor( + probe({ + root, + portFree: async (port) => port !== 3000, + portOwner: async () => (++asked === 1 ? {} : { pid: 41, cwd: `${root}-other` }), + }), + ); + const warned = ((result.data as { warnings?: readonly { code: string }[] }).warnings ?? []) + .length; + const failed = (result.findings ?? []).filter((one) => one.code === 'X_PORT_IN_USE').length; + expect({ asked, reported: warned + failed }).toEqual({ asked: 1, reported: 1 }); + }); + // Served by the scan, so never refused: an app that upgrades keeps a green doctor, and is told // the import line that lists the action — the one X_JOB_UNREGISTERED prints for a job. test('an action no defineApi() lists is a warning, never a finding', async () => { diff --git a/packages/cli/src/templates/scaffold-container-compose.test.ts b/packages/cli/src/templates/scaffold-container-compose.test.ts index ee49aa863..20468c1cb 100644 --- a/packages/cli/src/templates/scaffold-container-compose.test.ts +++ b/packages/cli/src/templates/scaffold-container-compose.test.ts @@ -109,6 +109,25 @@ describe('unit · the scaffolded compose file hands the page origin to sync', () ); }); + // Compose reads `${VAR}` and `${VAR:?msg}`, and `$$` as a literal `$`: every interpolation the + // file holds is written as exactly one `$` before its brace, and no backslash survives the template. + test('every compose interpolation is written as compose reads it, one $ and no backslash', () => { + const compose = composeProdFile(names('shop')); + expect(compose).not.toContain('\\$'); + expect(compose).not.toContain('$$'); + expect(compose.match(/\$\{[A-Z_]+[:?-]/g)).toEqual([ + '${VAR:', + '${IMAGE:', + '${POSTGRES_PASSWORD:', + '${SYNC_URL:', + '${APP_URL:', + ]); + expect(compose).toMatch( + /\n {6}POSTGRES_PASSWORD: \$\{POSTGRES_PASSWORD:\?set POSTGRES_PASSWORD\}\n/, + ); + expect(compose).toMatch(/\n {2}image: \$\{IMAGE:-shop:dev\}\n/); + }); + test('the header names both variables the env file must carry', () => { const header = composeProdFile(names('shop')).split('\nservices:')[0] ?? ''; expect(header).toContain('APP_URL'); diff --git a/packages/cli/src/templates/scaffold-container-compose.ts b/packages/cli/src/templates/scaffold-container-compose.ts index 1c45e4af2..aa3c71a7f 100644 --- a/packages/cli/src/templates/scaffold-container-compose.ts +++ b/packages/cli/src/templates/scaffold-container-compose.ts @@ -16,6 +16,13 @@ export const POSTGRES_IMAGE = */ export const PROD_ENV_FILE = '.env.production'; +/** + * A compose interpolation, `${expr}` in the written file: one `$`, which compose reads (its `$$` is + * a literal `$`). Never `\${` in the template below: CodeQL reads that escape as a regex one + * (js/useless-regexp-character-escape), and the bytes are the same. + */ +const composeVar = (expr: string): string => `${'$'}{${expr}}`; + /** The production topology `x new` writes at `docker/docker-compose.prod.yml`. */ export const composeProdFile = ( app: NameSet, @@ -26,7 +33,7 @@ export const composeProdFile = ( # # ${PROD_ENV_FILE} first: \`x env init --production\` writes every value below with fresh secrets. # -# By hand, always with \`--env-file ${PROD_ENV_FILE}\`: Compose fills \`\${VAR:?…}\` below from the shell +# By hand, always with \`--env-file ${PROD_ENV_FILE}\`: Compose fills \`${composeVar('VAR:?…')}\` below from the shell # and \`--env-file\` only, NEVER from \`env_file:\`, so without it a value set only in that file is # "missing" and the parse fails. \`x deploy\` passes it on every step. # @@ -51,7 +58,7 @@ x-logging: &logging options: { max-size: 10m, max-file: '3' } x-image: &image - image: \${IMAGE:-${app.kebab}:dev} + image: ${composeVar(`IMAGE:-${app.kebab}:dev`)} env_file: [../${PROD_ENV_FILE}] restart: unless-stopped logging: *logging @@ -97,7 +104,7 @@ services: # \`docker buildx imagetools inspect postgres:18-alpine\` and take a backup first. image: ${POSTGRES_IMAGE} environment: - POSTGRES_PASSWORD: \${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD} + POSTGRES_PASSWORD: ${composeVar('POSTGRES_PASSWORD:?set POSTGRES_PASSWORD')} POSTGRES_DB: ${app.kebab} volumes: ['pgdata:/var/lib/postgresql'] healthcheck: @@ -139,7 +146,7 @@ services: <<: *image # The page dials SYNC_URL; unset, it dials /_x/sync on :3000, which web does not serve here. # Set it in ${PROD_ENV_FILE}: \`--env-file\` (header) is what lets this line read it there. - environment: [ROLE=web, 'SYNC_URL=\${SYNC_URL:?set SYNC_URL=ws://<host>:3001/_x/sync, see wiki/Deployment.md}'] + environment: [ROLE=web, 'SYNC_URL=${composeVar('SYNC_URL:?set SYNC_URL=ws://<host>:3001/_x/sync, see wiki/Deployment.md')}'] depends_on: db: { condition: service_healthy } migrate: { condition: service_completed_successfully } @@ -152,7 +159,7 @@ services: # APP_URL's origin and no other once declared (scheme, host and port, exactly); undeclared, from # the origin it was reached on. Unset, every websocket is 403 X_SOCKET_ORIGIN_REFUSED, so it is # required: the same value web builds its links from. - environment: [ROLE=sync, 'APP_URL=\${APP_URL:?set APP_URL=http://<host>:3000 — the origin the pages are served on, see wiki/Deployment.md}'] + environment: [ROLE=sync, 'APP_URL=${composeVar('APP_URL:?set APP_URL=http://<host>:3000 — the origin the pages are served on, see wiki/Deployment.md')}'] depends_on: db: { condition: service_healthy } migrate: { condition: service_completed_successfully } diff --git a/packages/testing/src/per-test-reset.test.ts b/packages/testing/src/per-test-reset.test.ts index 23fbb8010..dfc437548 100644 --- a/packages/testing/src/per-test-reset.test.ts +++ b/packages/testing/src/per-test-reset.test.ts @@ -3,7 +3,8 @@ // test answered resumed the next test's waiting run. import { afterAll, beforeAll, describe, expect, test } from 'bun:test'; -import { installedRateLimitStore, memoryRateLimitStore } from '@ultimat3/http'; +import { installLogSink } from '@ultimat3/core'; +import { cappedWireDates, installedRateLimitStore, memoryRateLimitStore } from '@ultimat3/http'; import { installRateLimitStore } from '@ultimat3/http/adapter'; import { eventBus, memoryEventBus, publishEvent } from '@ultimat3/jobs'; import { installEventBus } from '@ultimat3/jobs/adapter'; @@ -88,6 +89,34 @@ describe(testName('unit', 'a bus installed for the file survives every test'), ( }); }); +// `cappedWireDates` warns ONCE per operation per process. Under `--rerun-each` every run of a test +// is one process, so the run after the first logged nothing and `http-dates.test.ts` went red on +// the flaky rerun. Each test below expects the warn its own call earns. +describe(testName('unit', 'the once-per-operation wire-dates warn is the test’s own'), () => { + const AT = new Date('2026-03-04T05:06:07.089Z'); + const unfoldable = { + points: Array.from({ length: 2_000 }, (_, index) => [`series-${index % 3}`, AT] as const), + }; + const warnsOnCap = (): number => { + const lines: string[] = []; + const release = installLogSink((line) => void lines.push(line)); + try { + expect(cappedWireDates(unfoldable, undefined)).toBeUndefined(); + } finally { + release(); + } + return lines.filter((line) => line.includes('http.wire_dates_dropped')).length; + }; + + test('a test past the cap is warned', () => { + expect(warnsOnCap()).toBe(1); + }); + + test('the next test past the cap is warned again', () => { + expect(warnsOnCap()).toBe(1); + }); +}); + describe(testName('unit', 'loaded answers absent for a package it cannot resolve'), () => { test('an app install that never reaches the package: undefined, never a throw', () => { // `@ultimat3/flags` is not testing's dependency, so in an app's isolated install it does not diff --git a/packages/testing/src/per-test-reset.ts b/packages/testing/src/per-test-reset.ts index edcc41b9e..fe1b7a0a6 100644 --- a/packages/testing/src/per-test-reset.ts +++ b/packages/testing/src/per-test-reset.ts @@ -1,7 +1,7 @@ // What every test starts from, put back by the preload before each one — the per-TEST half of -// isolation, beside `file-boundary.ts`'s per-file half: the jobs event bus, which STORES what it is -// handed (an answer one test published resumed the next test's waiting run), and the installed -// rate-limit store, read per request (a bucket one test drained was the next test's 429). +// isolation, beside `file-boundary.ts`'s per-file half: the jobs event bus (it STORES what it is +// handed), the installed rate-limit store (a drained bucket was the next test's 429) and the +// once-per-operation wire-dates warn (a rerun in one process never saw its warn). import { beforeEach } from 'bun:test'; import type { clearDefaultRateLimitBuckets } from '@ultimat3/http/adapter'; @@ -42,9 +42,9 @@ function resolvedFrom(pkg: string): string | null { const paths = new Map<string, string | null>(); /** - * Before each test: a fresh DEFAULT event bus and the DEFAULT rate-limit buckets emptied — each - * only when its package is loaded. Already evaluated, so each import answers from the registry, the - * same instance. Only the defaults: a bus or store installed for the file (`beforeAll`, a booted + * Before each test: a fresh DEFAULT event bus, the DEFAULT rate-limit buckets emptied and the + * wire-dates warn forgotten — each only when its package is loaded. Already evaluated, so each + * import answers from the registry, the same instance. Only the defaults: a bus or store installed for the file (`beforeAll`, a booted * app's) stays installed, and carries across that file's tests as it would in production. */ export async function resetPerTestState(): Promise<void> { @@ -62,6 +62,13 @@ export async function resetPerTestState(): Promise<void> { }; http.clearDefaultRateLimitBuckets(); } + const wireDates = loaded('@ultimat3/http', 'wire-dates-cap.ts'); + if (wireDates !== undefined) { + // An internal seam, off the package's API on purpose: an app forgets nothing it warned about. + // Its name is held by `per-test-reset.test.ts`, which reds if this stops resetting the set. + const http = (await import(wireDates)) as { readonly resetWireDatesCap: () => void }; + http.resetWireDatesCap(); + } } /** diff --git a/scripts/primitive-factories.test.ts b/scripts/primitive-factories.test.ts index 8360a96a0..175955feb 100644 --- a/scripts/primitive-factories.test.ts +++ b/scripts/primitive-factories.test.ts @@ -144,7 +144,7 @@ export const importable = ( entries: readonly Entry[], ): boolean => { const pkg = found.at.split('/')[1]; - const named = new RegExp(`\\b${found.factory.replace(/\$/g, '\\$')}\\b`); + const named = new RegExp(`\\b${RegExp.escape(found.factory)}\\b`); return entries.some( (entry) => entry.path.split('/')[1] === pkg && (entry.path === found.at || named.test(entry.source)), diff --git a/wiki/Tutorial-03-Auth-And-Admin.md b/wiki/Tutorial-03-Auth-And-Admin.md index 2132c95ea..de49c0f44 100644 --- a/wiki/Tutorial-03-Auth-And-Admin.md +++ b/wiki/Tutorial-03-Auth-And-Admin.md @@ -83,14 +83,14 @@ bunx x policy explain todo:write ```text action archiveTodo — policy todo:write - actor verdict deciding reason - anonymous deny todo:write no actor for todo:write - admin deny todo:write todo:write predicate returned false - member deny todo:write actor lacks todo:write + actor verdict deciding reason + anonymous deny todo:write no actor for todo:write + admin needs input todo:write not denied — every actor-only clause passes, and todo:write has a predicate that reads the request input + member deny todo:write actor lacks todo:write evaluated with no request input and no row — a rule reading either decides again on the real request action createTodo — policy todo:write … -✓ todo:write — allowed for 0 of 6 actor evaluation(s) +✓ todo:write — allowed for 0 of 6 actor evaluation(s); 1 not denied, decided by a predicate that reads the request input — x policy explain todo:write --input '<the request input as JSON>' ``` Read the `reason` column, not the verdict: @@ -98,7 +98,8 @@ Read the `reason` column, not the verdict: | Reason | Means | |---|---| | `actor lacks todo:write` | the grant is missing — a role problem, fix it in `defineRoles` | -| `predicate returned false` | the grant is held, the predicate said no. Here that is tenancy, with no `input.orgId` to compare against outside a request | +| `predicate returned false` | the grant is held, the predicate said no | +| `needs input` | the grant is held and every clause that reads only the actor passes; the rest reads the request input — here archive's tenancy rule, `input.orgId`. Not a denial: run the summary's own command with the input a request sends, `x policy explain todo:write --input '{"orgId":"…"}'` | | `no actor for …` | anonymous. Every surface agrees on this one | `<subject>` resolves against a permission, an action name, a query name, then an action's HTTP path — so the `fix:` line an `X_FORBIDDEN` prints is runnable whichever of the four the throwing surface had. Verdicts come from `policyMatrix()` over the app's real `Policy` objects, never a second evaluation.