Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 8 additions & 9 deletions .dz/briefs/security-release.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,18 @@
# Brief: does a confirmed security fix need a release today?

Daily checkup on the days `release-due` does not run, fired by `schedules: security-release` in
Devops session on Thursdays and Sundays, so a confirmed fix waits at most three days with the Tuesday `release-due`, fired by `schedules: security-release` in
`.dz/maintainer/maintainer.yml`. This is the one off-cycle release. Everything else waits for
Tuesday's `.dz/briefs/release-due.md`, and a person can still cut by hand.

## Run

```bash
git fetch --tags origin && bun run scripts/release-due.ts --json
bun run scripts/release-due.ts --json
```

You have a shell, no `git` writes and no `gh`; the runner ships what you leave in the tree. A refusal
(`ok:false`): report its `cause` and stop.

Read `data.shipping` for what merged since the last tag, then look for a commit that fixes a security
advisory.

Expand All @@ -27,10 +30,6 @@ such advisory does not qualify: it waits for Tuesday unless a person cuts it.

## When it qualifies

File one ask, **Release `<data.next>`**, opening with the advisory's id and source URL, then
following `.dz/briefs/release-due.md` § The ask. Its dedupes and refusals apply, and a major stays a
maintainer's. Otherwise file nothing and end your run summary with `no release: <reason>`.

## Rows

- `security-fix-unreleased` — A commit in `data.shipping` fixes an advisory a first-tier source confirms, naming something these packages ship, and no release carries it yet.
Follow `.dz/briefs/release-due.md` § Cut the release, opening `PR.md` and the `### Highlights` with the
advisory's id and source URL. A major stays a maintainer's. Otherwise change no file and end
`REPORT.md` with `no release: <reason>`.
3 changes: 2 additions & 1 deletion .dz/maintainer/maintainer.yml
Original file line number Diff line number Diff line change
Expand Up @@ -139,8 +139,9 @@ schedules:
brief_file: .dz/briefs/release-due.md
# The one exception, so a confirmed security fix does not wait up to a week for Tuesday.
- name: security-release
days: [mon, wed, thu, fri, sat, sun]
days: [thu, sun]
hours_utc: [4]
mode: devops
brief_file: .dz/briefs/security-release.md
# The failures nothing announces: a red `main`, a publish that did not land, npm drift, a stuck
# Dependabot PR. Bot-authored alarm issues never pass intake, so this is how they reach the bot.
Expand Down
29 changes: 28 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,34 @@ Semver applies from 1.0.0. A breaking change to a documented API needs a major

## [Unreleased]

Nothing yet.
### Added

- **Merging two features:** `x merge-driver install`, run by `bun run setup`, lets two branches that each ran `x g resource` merge with no hand edit: registries keep what both sides added, catalogs merge by key, `x.manifest.json` and `openapi.json` are rebuilt by `x manifest`. New apps write one registry entry per line, and `x upgrade` applies it (the `merge-drivers` codemod). `x doctor` warns `X_MERGE_DRIVER_UNSET` on a clone without the drivers ([Many agents → Merging two features](wiki/Many-Agents.md#merging-two-features)).
- `X_MIGRATION_FORKED`: `x db gen`, `x db migrate` and the gate's `drift` step refuse a migration chain two merged branches forked, before suggesting a `record …` migration that could never replay. `x db gen --merge-fork` corrects the newest snapshot, changes no SQL and deletes nothing.
- `X_MERGE_UNRESOLVED` names the files a merge left unresolved, and `X_CATALOG_UNPARSEABLE` names an i18n catalog that does not parse, in place of a parse error blamed on every module that imports it.
- `x heavy run --max-wait <seconds>` gives up with `X_HEAVY_WAIT_EXPIRED` (exit 75); `x heavy status` names each run's wrapper and command pids (`wrapperAlive`, `childPids` in `--json`), and a heavy run also waits while the CPU is saturated and another run is admitted.
- `x clean --services` stops this app's test service stack, and the gate prints one line saying whether it started, reused or shared one.
- `x dev`'s port refusal names the directory of the process holding the port.

### Changed

- A fix line that ends `then: x …` prints `bunx x …`, as does the gate's stderr pointer and `x errors explain`; a shipped guard's fix re-runs its own step (`x verify --only boundaries`), never the whole gate.
- 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_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`.
- A doctor probe that throws is an `X_DOCTOR_PROBE_FAILED` finding, never a crash whose fix is the doctor itself.

### Fixed

- `bun run preflight` and `bun run coverage` stopped by a signal kill the suites they started, so no orphan keeps its ledger reservation.
- In-process test fixtures no longer join the real ledger queue and leave frozen tickets at its head.
- `x upgrade`'s `docs-many-agents` codemod no longer reports `changed: [], skipped: []` when the app reworded its conventions table: it finds the table in `AGENTS.md` too, and otherwise reports the file as skipped with the row to add. It also checks the brief's byte budget (`agentsMdMaxBytes`, 12,000 by default) before writing, and skips with the byte count instead of pushing `CLAUDE.md` over it into `X_AGENTS_MD_TOO_LARGE`. `docs-worker-commands` does the same.
- `x upgrade` installs the merge drivers a hop's `.gitattributes` names, as `bun run setup` does, so an upgraded clone has no `X_MERGE_DRIVER_UNSET` left to fix by hand.
- A live suite no longer joins another app's test stack that shares its compose project name: it is refused with `X_TEST_SERVICES_UNAVAILABLE`.

## Releases

Expand Down
2 changes: 1 addition & 1 deletion PUBLISHING.md
Original file line number Diff line number Diff line change
Expand Up @@ -500,7 +500,7 @@ a first-tier source confirms is the one off-cycle release (`.dz/briefs/security-
tip when the checkout lacks it. The window is every commit since the highest `v*` tag HEAD contains,
release commits excluded. A commit **ships** when it changes a path a published tarball packs —
each package's `files` field, plus its `package.json` — minus `*.md`, tests and fixtures. Root
tooling, `bun.lock`, `.github/`, docs, the wiki and both tracked apps ship nothing.
tooling, `bun.lock`, `.github/`, docs, the wiki and the tracked apps ship nothing.

| `.data.reason` | Not due because |
|---|---|
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ Something narrower than the default dashboard? Start from a shape: `--shape api`

Or look first: **[the live demo](https://social-media.ultimate.demo.developerz.ai)**, a social network built on Ultimate, deployed from `main` on every green push. Fabricated data, every row decided by a policy. Source: [`dummy/social-media-clone/`](dummy/social-media-clone/).

No Docker, no env hunt: embedded Postgres, in-process NATS, storage in a local directory, a seeded database and a dev dashboard at `/_x`. `bun run setup` is required: `x new` installs nothing, and the app's own README names the six steps. → [Getting started](wiki/Getting-Started.md)
No Docker, no env hunt: embedded Postgres, in-process NATS, storage in a local directory, a seeded database and a dev dashboard at `/_x`. `bun run setup` is required: `x new` installs nothing, and the app's own README names the seven steps. → [Getting started](wiki/Getting-Started.md)

## Why pick it

Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/12-generated-app.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ myapp/
i18n/ # app catalogs (en, es, ...)
ui/ # app-specific Solid components on top of @ultimat3/ui
mcp/ # the app's own MCP tools (its dashboards are AI-first too)
bin/ # setup.ts (six steps); the gate is `bun run verify` (x verify), no file
bin/ # setup.ts (seven steps); the gate is `bun run verify` (x verify), no file
.github/workflows/ # ci.yml — bun run setup then bun run verify, on push and pull request
docker/ # compose (dev) + per-role compose (prod) + Dockerfile
app.config.ts # the one config file
Expand Down
1 change: 1 addition & 0 deletions docs/architecture/guards.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ The codes are in
| `bun run finite-bounds` | Enforce, as a ratchet, that a NUMERIC option defaulted with `??` is checked for finiteness. | `X_FINITE_BOUND_PIN_STALE` `X_FINITE_BOUND_UNCHECKED` `X_FINITE_BOUND_UNSCANNED` |
| `bun run scripts/fix-prose.ts` | Enforce, as a ratchet, that a `fix:` is a runnable command or a pasteable code shape, never prose. | `X_CLI_BAD_FLAG` `X_FIX_PROSE` `X_FIX_PROSE_PIN_STALE` `X_FIX_PROSE_PIN_UNEXPLAINED` `X_FIX_PROSE_UNSCANNED` `X_PIN_EDIT_UNPLACED` `X_PIN_RAISE_UNSTATED` |
| `bun run fix-shell-arg` | Enforce, as a ratchet, that a value spliced into a `fix:` line never lands in a SHELL COMMAND POSITION unscreened. | `X_CLI_BAD_FLAG` `X_FIX_SHELL_ARG_PIN_STALE` `X_FIX_SHELL_ARG_PIN_UNEXPLAINED` `X_FIX_SHELL_ARG_UNSCANNED` `X_FIX_SHELL_ARG_UNSCREENED` `X_PIN_EDIT_UNPLACED` `X_PIN_RAISE_UNSTATED` |
| `bun run scripts/fix-tails.ts` | Enforce, as a gate rule, that the command a `fix:` line ends on runs as printed and stays narrow. | `X_FIX_TAIL_BARE` `X_FIX_TAIL_WHOLE_RUN` |
| `bun run scripts/flake-hunt.ts` | The nightly flake hunt's two commands: `run` one shuffled round of a suite under a recorded seed, and `file` the rounds' failures as one GitHub issue per test. | `X_CLI_BAD_FLAG` `X_FLAKE_HUNT_TEST_FAILED` `X_FLAKE_HUNT_UNREADABLE` |
| `bun run flight-copies` | One home per helper: a retry delay is computed in ONE place, no die rolls that a test cannot control, and each helper in `lib/helper-homes.ts` (escaper, cookie reader, hashes, `PgExecutor`, `storeMode`) has one implementation. | `X_FLIGHT_RANDOM_UNINJECTED` `X_FLIGHT_SECOND_CURVE` `X_HELPER_COPY` |
| `bun run framework-env` | Enforce, as a build error, that every environment name shipped framework source reads by literal is in `FRAMEWORK_ENV` (`packages/core/src/framework-env.ts`), and that the list names nothing the source no longer mentions. | `X_FRAMEWORK_ENV_STALE` `X_FRAMEWORK_ENV_UNREGISTERED` |
Expand Down
2 changes: 1 addition & 1 deletion docs/idea/00-thesis.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ Each one is a permanent no, not a "later".
bunx create-ultimate myapp && cd myapp && bun run setup && bun run dev
```

`bun run setup` is six steps — `bun install`, an `.env.development.local` touch, `x db gen "initial"`,
`bun run setup` is seven steps — `bun install`, `x merge-driver install`, an `.env.development.local` touch, `x db gen "initial"`,
`x db migrate`, `x db seed`, `x manifest` — the scaffold's own script, and not optional
([`13-dx.md`](./13-dx.md)). No Docker install. No `.env` scavenger hunt. Embedded Postgres, in-process NATS, S3 → local dir. A landing page in `site/` at 0kb JS, an authed dashboard in `app/` streaming, an admin app that already speaks MCP, and `x verify` green — before the first line of user code. **`x verify` alone**, `As of 30.0`: the gate's `budgets` step weighs `.x/build-stats.json`, and runs the static build that writes it whenever the file is missing or older than the source.

Expand Down
6 changes: 3 additions & 3 deletions docs/idea/13-dx.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,11 @@
bunx create-ultimate myapp && cd myapp && bun run setup && bun run dev
```

Four commands. `bun run setup` is the scaffold's own script, six steps — `bun install`, an
`.env.development.local` touch, `x db gen "initial"` when `packages/db/migrations` holds no `.sql`,
Four commands. `bun run setup` is the scaffold's own script, seven steps — `bun install`,
`x merge-driver install`, an `.env.development.local` touch, `x db gen "initial"` when `packages/db/migrations` holds no `.sql`,
`x db migrate`, `x db seed`, `x manifest` — and it is **not optional**: `x new` installs nothing, so
`x dev` straight after `cd` stops on `X_BUILD_FAILED` naming `bun install`. Measured
`As of 2026-09-11` on a warm Bun cache: 6,802ms for all six steps, and 12.0s when the install is
`As of 2026-09-11` on a warm Bun cache: 6,802ms for the six steps it then had, and 12.0s when the install is
cold. This page wrote the three-command form until 2026-08-23.

```
Expand Down
2 changes: 1 addition & 1 deletion docs/idea/21-the-range.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Measured on a scaffold written by this checkout, `As of 2026-08-23`. Re-derive:
| files you write before the first page | **0 of 151** — re-derived `As of 2026-09-11`; `scripts/generator-counts.ts` turns a stale count red on the commit that moves it |
| commands from nothing to a running app | **4** |
| packages installed | **104**, in the one `bun install` `bun run setup` runs |
| `bun run setup` wall time, warm cache | **6,802ms** for all six steps, `As of 2026-09-11` — install, the env file, generate the first migration, apply it, seed, write the manifest. A **cold** first install takes it to 12.0s ([Bare VM](../../wiki/Bare-VM.md)) |
| `bun run setup` wall time, warm cache | **6,802ms** for the script as it stood `As of 2026-09-11` — install, the env file, generate the first migration, apply it, seed, write the manifest. A **cold** first install takes it to 12.0s ([Bare VM](../../wiki/Bare-VM.md)) |
| what `x dev` starts | 4 roles in one process (`web` `sync` `worker` `scheduler`), 11 `/_x` panels, `db=embedded events=embedded storage=embedded mail=embedded` |

The four commands, and they are the whole of it:
Expand Down
Loading
Loading