Skip to content

Release v0.5.0

Choose a tag to compare

@homer6 homer6 released this 23 Oct 22:45
· 56 commits to main since this release
e11c02f

v0.5.0

Released: 2026-10-23 · Branch: dev · Previous: v0.4.0 (2026-10-19)

v0.4.0 was about datasets. v0.5.0 is the security release: the fixes from the auth review
(#759–#769), the multi-tenant audit, TC-5 and the pre-launch security review (LSR findings,
#1388), plus the features that landed beside them: three
new source connectors (MySQL, TiDB, lake's SQLite/DuckDB/Polars services), a per-database safe mode,
WHERE with AND/OR/NOT, published pipelines, and run proposals a person approves.

73 pull requests since v0.4.0 (52 fixes, 12 features, 2 tests, 1 performance change, 6 docs).
The generated OpenAPI has 190 /v1 paths (was 177), the capability registry has 179
capabilities (was 168), and the test sources hold 3,554 test cases (was 3,042).


Upgrade: read this first

  • Upgrade every node of a cluster together. Several changes are not compatible with a node from
    v0.4.0 in the same cluster:
    • Sealed identity (#1340, #1359): accounts, roles, tokens, grants and policies are sealed under a
      cluster identity root, and every record carries a version. A v0.4.0 node refuses token records
      that carry _seal, so its callers get 401 until it is upgraded.
    • Text entity-key mappings as a table (#1442).
    • Indexed search (#1459): a v0.4.0 peer refuses the database field a v0.5.0 coordinator
      sends, so distributed search fails closed until every node is upgraded.
    • Distributed WHERE (#1366): a v0.4.0 partition owner refuses a compound WHERE with an
      error (never partial results); a single comparison keeps the old shape.
  • #1442 cannot be rolled back. Text entity-key mappings written by v0.5.0 are stored in the new
    table; a v0.4.0 node does not read them.
  • The identity root is created on the first v0.5.0 start (#1340, #1480), from
    --admin-token/ZETTA_ADMIN_TOKEN (or generated), and pinned with its seed in
    <data_dir>/security/identity-root.json (mode 0600). Under the Orama operator every node has the
    same token, so every node derives the same root and nothing changes in the operator. Records held
    before the upgrade are sealed once on that first start. See
    identity-seal.md.
  • Outbound connections are denied by default (#1321): the node reaches only loopback, the Clerk
    issuer and --egress-allow/ZETTA_EGRESS_ALLOW. Under a Lake the operator sets * and the
    namespace's NetworkSandbox enforces egress
    (orama-operator#723, rolled).
  • Connector sources need an approved destination (#1469): a private or loopback source is dialled
    only when ZETTA_CONNECTOR_ALLOW_DESTINATIONS lists it as an exact host:port. Roll
    orama-operator#890 before this image
    ,
    or every in-cluster source (lake's SQLite/DuckDB/Polars, in-cluster Postgres, TiDB) is refused. A
    lake SQL endpoint must now name http:// or https://.
  • Action and report delivery dial only public addresses (#1452) unless
    ZETTA_ACTION_ALLOW_DESTINATIONS names a class.
  • Pending action-outbox and report rows written before the upgrade cannot be delivered (#1467):
    their records carry no actor binding. Re-enqueue them after the upgrade
    (#1474).
  • Agent checkpoints must be registered (#1465): agent.model must be base-agent,
    /data/models/base-agent or an entry of ZETTA_AGENT_CHECKPOINTS. Lake's default base model path
    is registered; agents on other model strings stop serving.
  • The corosio pin moves to orama-main be514224 (corosio#15 peer certificate, corosio#16
    full-duplex TLS, and the reactor fixes #6, #8, #11, #13).

Behaviour changes

  • Safe mode per database (#1373): set_safe_mode / get_safe_mode set Off, Warn Writes or Warn
    All on a Zetta database or a saved connection. A warned statement is refused with
    safe_mode_warning (REST 428) carrying the exact statements and a confirmation bound to them; the
    same call with safe_mode_confirmation runs it. A database defaults to Off and a connection to
    Warn Writes
    (connections are read-only, so Warn Writes prompts for nothing until Warn All). See
    safe-mode.md. The consent gate stays off by default; its approval
    surface (Governance → Consent requests) is new.
  • Authorization is per caller in more places: the system catalog and /v1/specs (#1358), indexed
    search with row policies (#1459), analyze_dataset/plan_features (#1451), virtual tables
    (admin-only, #1449), trace diagnostics (admin-only, #1462), the cookie blob routes (#1448), and a
    legacy AccessKey (row security and grants, #1361). Each graph step runs as the run's principal
    (#1330). A reader may see fewer rows or get unauthorized where it used to read.
  • Role management is bounded by the caller's own rights, and built-in roles are fixed (#1355).
  • A row policy missing its condition denies instead of admitting every row (#1352).
  • agent_run runs a plan only after a person approves it (#913, #1337), and the chat agent
    proposes runs a person approves (#1384).
  • The owner token is stored as PBKDF2-SHA256 (#1311); seeding resumes after a crash.
  • Blob grants match on a / path boundary (#1312): a grant on report no longer admits
    report-secret-2026.
  • Refused reads are audited and do not reveal whether a table exists (TC-5, #1345); the node
    audits its own catalogue changes and names the caller on every row (#847, #1333).
  • The SQL parser never throws (#1336), so no statement can end the node.
  • Peers: a HELLO is bounded and shape-checked (#1313), its node id must be its certificate's
    common name (#1326), setup has one deadline and accept errors are recovered (#1457), and mTLS links
    are full duplex (#1347, the fix for the silent SYNC stall #835).
  • Imports and exports resolve only under the node's import and export roots (#1450, #1454); model
    downloads stay in their directory (#1466); Parquet input is bounded and type-checked (#1463, #1464);
    model imports are bounded (#1447, #1472); dataset generation has a ceiling (#1456).
  • Browser sessions and actions are bound to their origin (#1471); JSON embedded in HTML is encoded
    (#1461); public LLM docs carry no inventory (#1458).
  • The join token is never printed (#1446), reaches cloud VMs from each vendor's secret store
    (#1318, #1346), and cluster secrets are created private (#1468).

Added

  • Source connectors: native MySQL, read-only and TLS by default (#1371); TiDB over the MySQL
    protocol, fenced the way TiDB allows (#1387); lake's SQLite, DuckDB and Polars services (#1385).
    Catalog filters are encoded per SQL dialect (#1460).
  • WHERE with AND, OR, NOT and parentheses (#912, #1366), with three-valued logic.
  • Published pipelines (#1289, #1444): expose_pipeline pins a pipeline as
    POST /v1/pipelines/{name}/run; a call runs with the caller's own grants and a per-node rate limit.
  • Safe mode (#1373), above.
  • list_projects returns graph summaries (#1436); a lean list_datasets summary (#1438);
    60-second long polls for receive_events and browse_topic (#1437).
  • Full-text search: a query naming a field searches only that field (#1363), and every shard is
    scored with the merged corpus statistics (#1372, with oramacore-cpp#2).
  • Chaos experiments (#1353): an mTLS cluster tormented on a seeded schedule; the long runs and the
    every-fault-class smoke are opt-in (ZETTA_CHAOS_SMOKE, ZETTA_CHAOS_SCHEDULES).
  • The authz regression harness for #759–#769 (#1325).

Performance

  • Gossip sends only the changes a peer lacks (#794, #1350): 13–17× fewer bytes per round.
  • Catalogue reads no longer wait for a save (#1248, #1440).

Not in this release

  • Root rotation, and handing the identity root to a node added after an admin-token rotation
    (#1479).
  • Safe mode in the desktop SQL console and the governed console, in a pipeline run that reads a
    saved connection, and a Run / Cancel dialog in Zetta's own web console (Lake has one, lake#1080).
  • Provisioned burst nodes are not given the identity root
    (#1343).

Known issues

Security-relevant first.

  • The remaining pre-launch review findings are open under
    #1388, among them: LSR-173 synchronous action delivery
    can block the owner loop (#1406); LSR-174 system SQL views expose metadata without their read
    permission (#1407); LSR-162 cookie routes buffer unauthenticated bodies (#1395); and the p3 findings
    LSR-244 to LSR-262 (#1417–#1435).
  • A node that never saw a newer sealed record accepts an older one when no holder is left (#1360).
  • Node certificates can be minted by any join-token holder, and there is no per-node revocation
    (#1319, #1320); network and filesystem reach is node-wide, not per run principal (#1323); a saved
    connection's credential is usable by anyone holding the connection capability (#1339).
  • /v1/openapi.json and /llms*.txt are public and list every capability (#1357).
  • An intermittent segfault in Uc1Journey.ARunWithoutADatasetReadsItsPipelinesTable (#1485),
    under investigation with AddressSanitizer.
  • Latency-budget tests fail on a loaded host (#1256).
  • WHERE NOT (x = 5) matches rows where x is null (#1473).
  • Pending outbox and report rows from before LSR-237 are not delivered after the upgrade (#1474).

Where it has run

Not yet on any cluster. The image above is rolled by the operator release that carries
orama-operator#890; the roll is recorded
here when it happens.

Verification

Full test suite, run serially (ctest --test-dir build, no -j) on the release branch at
c0ec95c3 plus the version bump, macOS 14.6.1 arm64, Clang 22.1.8, static Release build, 1,226 s of
tests, on a host loaded by other builds:

3,454 tests · 3,420 passed · 10 failed · 23 skipped · 1 disabled

The 10 failures, each accounted for:

Failure Cause State
GovernedConsole.SimPythonLowersGatesExecutesAndAudits, GovernedConsole.CapabilityGrantAllowsTheRun a run started with a principal recorded no audit row and no actor (#1333 with #1330) fixed, #1484 by #1488
PipelineServingFixture.ExposeServeReadBackAndUnexpose a served run's caller needs each step's right (#1444 with #1330); test and docs updated fixed, #1481 by #1488
ActionIntegrationFixture.ReportDeliveryRefusesAPrivateOrMetadataEndpoint egress default-deny refused first (#1452 with #1321); the test now reaches the destination check fixed, #1482 by #1488
SystemCatalogAccess.AnUnknownUserReadsOnlyPublicMetadata a caller's own refusals are now audited and readable (#1345 with #1358) fixed, #1483 by #1488
RestServerFixture.FiveHundredLongPollsLeaveNoWaitReceivesFast, SmallConnectionCacheFixture.FiveHundredHeldPollsLeaveTwentyFreshConnectionsFast, ObjectRoutes.RangedReadsStayInsideTheirBudgets, RecordStoreBenchmark.GetAndListStayInsideTheTenMillisecondBudget wall-clock latency budgets on a loaded host; each passed rerun alone known, #1256
Uc1Journey.ARunWithoutADatasetReadsItsPipelinesTable segfault, intermittent (1 in 3 runs through ctest; passes run directly) open, #1485; an AddressSanitizer build is running the full suite

After #1488, the affected suites (GovernedConsole, PipelineServing, ActionIntegration,
SystemCatalogAccess, StepAuthority, AuditCompleteness, Uc1Journey) ran 90 tests: 88 passed, the 2
failures being the Uc1Journey segfault above. The full suite was not rerun with #1488.

Skipped (23): tests that need a real model checkpoint, a GPU, a generated corpus, an external
OramaCore engine, or a live MySQL, TiDB or lake SQL service that this host does not configure. The
pub/sub throughput benchmark is disabled.

AddressSanitizer (full suite, -fsanitize=address, RelWithDebInfo): 3,453 tests, 6 failed. One
ASan report, a test bug: a stack-use-after-scope in ObjectLogCrash (#1491, fixed by #1492 after the
tag, test-only). Three failures are memory or throughput budgets that ASan inflates (no report). The
two GovernedConsole failures predate #1488. The Uc1Journey segfault (#1485) did not reproduce under
ASan and stays open.

Linux: the image built from the tag on the cluster BuildKit:
oramasearch/zetta:main-e11c02f5 = oramasearch/zetta:v0.5.0,
sha256:25f9365f4ea8b3f663c8170ba1494bb4053bb3bc1eeb175462b569917fc0b3c0 (private).