What's New

Recent changes across Manzano and Grove. Breaking changes are called out explicitly — check the "Action Required" section first if you're upgrading an existing project.

Action Required

If you're carrying a project forward from before April 2026, three changes may require edits before manzano test or manzano deploy will succeed:

1. kind "xxx" is now required on every root record. Add kind "..." as the first item inside every record { ... } block. 2-5 lowercase ASCII letters, not starting with mz. See Declarations — The kind declaration and checker error E0112.
2. grove.toml uses project_id at the top level. The old [project] name = "..." version = "..." table is no longer what the CLI reads or writes. Move to:

   project_id = "my-app"
   

   See Configuration Reference.
3. Anonymous route calls are now truly anonymous. If your Cedar policies or authorize hooks relied on the old synthetic "route" principal fallback, update them to either require authentication or to permit Role::"__anonymous" explicitly. See Per-Project Cedar Policy.

April 2026

Authentication — new top-level section

Identity now has a dedicated section separate from authorization. Four pages cover the end-to-end story:

• Authentication Overview — the three-layer browser / edge / backend mental model.
• Identity Providers — Auth0, Clerk, WorkOS, Google, Apple, custom OIDC, built-in email magic link, Turnstile.
• Identity Flow — edge-stamped headers (X-Sub, X-Email, X-Site-Id, …) and the HMAC trust boundary.
• Enabling Authentication — the app-developer path to turning on login, with all-or-nothing protection caveats and anonymous-access patterns.

security/authorization.md picks up a "Where ctx.principal comes from" cross-link and retains the authorize hook model it always had.

Language

• kind declaration on root records. Required; 2-5 lowercase ASCII letters; mz prefix reserved. Errors E0112 / E0113 / E0114.
• Id is a prefixed KSUID. Short form kind_suffix (e.g. post_2wNBB8TuBRfOQxMmCQJpTfqDjRi), long form project:kind_suffix for cross-project references. See Types — Id. The old "UUID v7 internally" description is gone.
• Versioned sources and triggers. Declare events with an explicit version (source deploy_started v1 { ... }), subscribe to a specific version (trigger ... from StudioEdge.deploy_started.v1). Ambiguity errors if an unversioned reference matches multiple versions. See Triggers — Versioned Sources.
• System ID prefixes. Commands are now mzcmd_<ksuid> (was cmd-<uuid>); workflows are mzwf_<ksuid> (was raw UUID). User-defined kind prefixes cannot start with mz.

CLI — manzano 0.4.x

• First-deploy flow. manzano deploy on a fresh project prompts to create it, mints a server-side prj_<ksuid>, and writes it back into grove.toml. New flags: --yes / -y (skip prompt, required in CI), --new-project (force-create, recovery path), --name <NAME> (override project name). See CLI — deploy.
• manzano init scaffolds a working project. The starter module ships with a populated record / events / actions body, not an empty stub. Two assistant-context files (AGENTS.md, CLAUDE.md) are added at the project root. On completion, init prints a concise Grove cheat sheet. See CLI — init.
• grove.toml is now project_id = "..." at the top level. The old [project] table is gone. See Configuration Reference.
• CLI self-expiration. manzano warns at ~10 days past its build timestamp and refuses to run at ~14 days. Plan to brew upgrade manzano weekly if you use it intermittently. See Installation — Keep the CLI Up to Date.
• Deploy tarball contents. grove.toml, modules/**/*.grove, apps/**/*, and an optional policies.cedar at the project root.

Authorization

• Per-project Cedar policy. Drop a policies.cedar at the project root. If present, Cedar evaluation runs on every action and query invocation alongside authorize hooks; both must permit. See Per-Project Cedar Policy.
• Sentinel roles. Role::"__authenticated" fires when ctx.principal is non-null; Role::"__anonymous" fires when it's null. Write cross-cutting policy without enumerating every real role.
• Role vocabulary. Declared roles are resolved at runtime through Grove's vocabulary layer, so Cedar principal-role assertions work against application-defined roles.
• Breaking: no more synthetic route principal. Anonymous route calls are now truly anonymous; update policies to permit __anonymous where public access is intended.

Runtime and Database

• Per-resource tables are authoritative. The old {module}_events + {module}_state pair is gone. Aggregate state lives in a single per-resource table (grove_order for the order module). Events, outbox, audit, and other runtime state live in nine shared grove_* system tables. See Database Backends — Scoping.
• Synthetic pk primary key. Per-resource tables use an auto-increment pk (INTEGER AUTOINCREMENT / BIGINT IDENTITY / AUTO_INCREMENT / AUTO_RANDOM(5) depending on backend). id is demoted to NOT NULL UNIQUE.
• Id SQL type changed. Now TEXT (SQLite, Postgres) / VARCHAR(96) (MySQL, TiDB). Was UUID / CHAR(36).
• DateTime on MySQL/TiDB is now BIGINT (epoch milliseconds). Dodges the TIMESTAMP 2038 boundary. SQLite (TEXT) and Postgres (TIMESTAMPTZ) unchanged.
• 256 KiB event payload cap. Oversized events return HTTP 413 Payload Too Large with code Z4004. Use the File type or an out-of-band URL for larger payloads. See Limitations — Event payload size.
• Identity header rename. x-user-id is now x-sub. The edge sets this automatically; self-hosted backends verifying edge-signed requests should update their header reads.
• Route path params resolve on every method. input.params.<name> was previously empty on POST/PUT/PATCH/DELETE under [id] directories; now works on all methods. Requires Grove 2026-04-17 or later.

Workflows — two new subsystems documented

• Outbox. The transactional outbox pattern Grove uses for reliable event publishing. Covers the grove_outbox schema, the claim-lease dispatch protocol, at-least-once and per-aggregate ordering semantics, (project_id, dedup_key) idempotency, and debugging queries.
• Ingress. The inbound event pipeline. Covers sources, stable target keys, the per-target shedder circuit breaker, the NaiveScheduler and Tiller scheduler, and the SqsSource for pulling from AWS SQS.

Web and HTTP

• /_file/* file endpoints (renamed from /_blob/*). See File Uploads.

Running the server

• Hosted vs self-run is now disambiguated. Server has a callout at the top clarifying that Manzano-hosted deployments don't run grove-server directly; manzano deploy handles it. The rest of the page covers the self-hosted path for local integration, CI, and on-premise use.

Errors and limits

• New error code Z4004 / HTTP 413 for oversize events. See Error Reference.
• New checker codes E0112 / E0113 / E0114 for kind declaration errors.

See Also

• Installation — start here if you're new
• Authentication Overview — the new section
• Configuration Reference — grove.toml schema