Documentation update log

On this page

This log records changes to the documentation bundle: page additions, renames and deprecations, structural refactors, and corrections. Feature and code records live in the software Changelog, which Release Please maintains from the commit history.

Unreleased

  • Update: Widened the out-of-line payload gap to the Go SDK. ADR 0013 records that migration 109_create_workflow_payload_tables (commit ed914c4, "Workflow payload tables", #470) first released in Go SDK v1.4.0, so applications at v1.4.0 and above store workflow inputs and outputs out of line, confirmed by the DBOS September 2026 release post. Data plane now names Go at v1.4.0 and above alongside TypeScript and Python, and the supported window recorded in Supported SDKs permits Go up to v1.6.0 while the pinned client stays at v1.3.0.
  • Update: Added the Supported SDKs page recording the supported executor SDK range as policy, with each version claim cited against its SDK repository tag and its package-registry upload date, and added a section to Multi-SDK verification naming the offline ceiling check. Linked both from the usage and documentation indexes.
  • Update: Closed the review follow-ups from the is_fork fold. Data plane records that the local SDK-client fallback does not apply the filter and returns a superset, with the upstream commits and releases that added it; the wire catalogue in Executor WebSocket protocol lists is_fork on list_workflows; the codec suite pins that a nil filter leaves the key off the wire; the data-plane field-coverage guard now fails when a field listed as knowingly unmapped starts being applied by the data plane; and the two handler provenance comments carry the current specification fetch date.
  • Update: Recorded the is_fork workflow filter across the wire catalogue, the wire to REST mapping and the Conformance Batteries, and re-vendored the Conductor v2 OpenAPI documents with the matching isFork property (fetched 2026-10-11).
  • Creation: Added ADR 0013 recording the decision to keep the Go SDK data-plane client pinned at v1.3.0 and treat reads of out-of-line workflow payloads as a documented capability gap. Corrected the multi-SDK schema claim in Data plane, added a qualifying addendum to ADR 0004, and registered the tagged Go SDK sources in the provenance ledger.
  • Update: Aligned user-facing docs with the merged rewind and token-rename changes: the protocol message count is now 33 in the README and landing page, dbosctl api-key rename is documented in Client behaviour, the Operate and Identity tiers list rewind and API key rename, and Conformance Batteries adds the Battery 4 rewind check. Corrected the relay test-conformance help text and the conformance-drift skill to name Fork rather than Restart.
  • Update: Refreshed the provenance ledger and citations to the current upstream commits (Go fb3e33e, Python 2b93e14, TypeScript 749a4d4, Java ecc2bda, dbos-ctl 1e6d20e, Argus 66ae6da), renamed the Go SDK repository reference to dbos-transact-golang, corrected the restart note (Python and TypeScript removed it), and recorded that retention is acknowledged asynchronously.
  • Update: Recorded the queue partition fields in the wire to REST mapping as they pass from list_queues and get_queue executor frames to the Queue schema.
  • Update: Re-vendored the Conductor v2 OpenAPI documents (fetched 2026-09-30) and added the rewindWorkflow and updateToken operations to the REST surface inventory, recording the dropped partition restriction on autoscaling policy queues and the raised application name length as open divergences.
  • Update: Documented shared-database retention semantics, the resume executor-health requirement and the restart divergence in Workflow retention.
  • Update: Documented OIDC profile setup in Quickstart.
  • Creation: Added ADR 0012 and the Autoscaling page covering queue-driven executor recommendations for external scalers, with Relay recommending counts and actuation left to the orchestrator.
  • Update: Extended the dashboard acceptance checklist to cover the Settings, Autoscaling and Audit Log views.

2026-09-18

  • Creation: Added the software Changelog, rendered on the documentation site and reserved in the OKF bundle validator.
  • Creation: Added ADR 0011 establishing dual-engine storage architecture with PostgreSQL as flagship production engine, pure-Go SQLite for zero-dependency embedded mode, Turso MVCC for scale-out, and future adoption of Turso's PostgreSQL wire mode.
  • Update: Converted the ASCII architecture and lifecycle diagrams across the docs to Mermaid flowcharts and sequence diagrams with a vendored offline runtime, added Chroma syntax highlighting to wiki rendering, made the documentation sidebar sections collapsible, and unified section headings with section index routes.
  • Update: Documented the multi-database fleet architecture and the design rationale for omitting database credentials and topology management from the control plane UI in Data plane access via SDK client.
  • Creation: Added the standalone Cloudflare-deployable landing page and documentation site in site/, with a live dashboard screenshot showcase, feature comparison matrix, and static OKF wiki generator.
  • Update: Updated Dashboard manual acceptance checklist to cover canvas viewport controls, workflow family hierarchies, live telemetry polling options, and shortcut cheat sheets.
  • Update: Overhauled the dashboard design tokens to an industrial zinc and technical cobalt palette, achieving WCAG AA and AAA contrast ratios, tabular lining numerals, authored inline SVGs, and intentional alternatives under prefers-reduced-motion.
  • Creation: Designed the bespoke brandmark and favicon ("Circuit Handoff R") representing durable state control, orchestration consensus, and dynamic executor dispatch, replacing generic clipart.

2026-09-17

  • Creation: Added Dashboard manual acceptance checklist documenting systematic verification across fleet management, workflows, step graph visualisations, schedules, queues, and alerting rules.
  • Update: Expanded Conductor Protocol (WebSocket) to cover all 32 wire protocol message types.
  • Update: Clarified that application autoscaling policy is an orchestrator responsibility and a deferred non-goal in Goals and boundaries.
  • Update: Recorded in Conformance testing that the workflow recovery lifecycle is verified through the chaos testing harness.
  • Update: Documented the multi-SDK system database schema compatibility requirements for direct data-plane queries in Data plane.

2026-09-14

  • Creation: Added Production Hardening documenting in-process TLS certificate configuration and reverse proxy access log restrictions against recording WebSocket URIs.
  • Creation: Added ADR 0010 recording the provenance, attribution posture, and clean-room redistribution rationale for vendored OpenAPI interface specifications.
  • Update: Documented the database migration management subcommands and skip-migrations support in Operations and migrations.
  • Update: Reconciled the autoscale REST operations in REST surface discovery as uninstalled policy 404 Problem Details responses and deferred Tier 5 capabilities.
  • Update: Clarified the supported Scale-tier metric families in Metrics, alerting, and HA peer forwarding.
  • Update: Reconciled ADR 0004 to delineate implemented connection pool sizing and per-query statement timeouts from planned scale-tier guardrails.
  • Update: Updated the Conductor Protocol (WebSocket) section structure to document heartbeat, liveness, and timeout semantics.
  • Update: Added a release checklist to Maintainer guide specifying clean-room legal provenance verification and pre-release history hygiene requirements.

2026-09-13

  • Update: Reconciled the executor lifecycle status definitions (HEALTHY, DISCONNECTED, DEAD, Deleted), heartbeat timing parameters, and peer failover mechanics in Recovery and Recovery timing parameters against the normative WebSocket protocol specification.
  • Update: Aligned the data-plane documentation in Data plane with ADR 0004 and ADR 0008, detailing SkipMigrations: true schema safety, VerifyMigrations checks, deferred serialization boundaries, fork mutation semantics, and the separation of Conductor alerting rules from Prometheus operational alerts.
  • Update: Aligned the WebSocket alert frame documentation in Metrics, alerting, and HA peer forwarding with the unidirectional notification contract in Conductor Protocol (WebSocket), removing the invalid response envelopes and detailing the HMAC-SHA256 authenticated peer-forwarding route /internal/v1/forward/{appID} with loop prevention headers.
  • Update: Aligned the conformance battery 4 documentation in Conformance testing and Conformance Batteries Specification to specify fork_workflow mutations rather than unimplemented restart types, and removed internal discovery shorthand.

2026-09-12

  • Update: Sanitized internal process vocabulary, phase numbering, and legacy document prefix identifiers across all documentation and discovery references, renaming the discovery documents to topic-only paths (rest-surface.md, authz.md, client-behaviour.md, dashboard-reuse.md, recovery-params.md, metrics-alerting.md).
  • Update: Aligned the project status, architecture components, and recovery documentation with the shipped Go implementation, removing pre-implementation disclaimers and defining executor liveness parameters against Conductor Protocol (WebSocket).
  • Update: Reconciled the overview and goals documentation with the ADR 0004 data-plane architecture, noting read-by-default SDK client database fallback access and removing outdated database boundary claims.
  • Creation: Added ADR 0009 recording the zero-dependency vanilla JS dashboard architecture, bespoke SVG step graph renderer, and manual OpenAPI model maintenance.
  • Correction: Corrected the quickstart environment variable usage (DBOS__CONDUCTOR_URL, DBOS_URL, DBOS_TOKEN), clarified the sample app RELAY_URL wiring, and aligned the Go prerequisite floor with go.mod.
  • Creation: Added Operations and migrations documenting startup auto-migration, rolling upgrade expand/contract schema evolution, and database restore rollback procedures.
  • Update: Documented declarative configuration secret indirection via environment variable expansion, runtime timing overrides, the --env-out flag, and the repository gitignore refusal checks in Declarative operations.
  • Update: Regenerated the client command endpoints and acceptance checklists in Client behaviour to match the upstream dbosctl client and OpenAPI specifications.
  • Creation: Added THIRD-PARTY-LICENSES.md with attribution and licence notices for the MIT, BSD-3-Clause, and Apache-2.0 dependencies, including the DBOS Go SDK.
  • Update: Documented the synthetic executor disclosure in the conformance test reporting and the CLI usage guide in Conformance testing.
  • Correction: Corrected the provenance ledger description in Clean-room rules as a permitted source register, and replaced minified JSON line citations with standard JSON pointer paths in the discovery documentation.
  • Update: Aligned the multi-SDK verification matrix documentation in Multi-SDK verification matrix with genuine REST endpoint probes rather than unexercised client CLI binaries, and specified verbatim payload byte preservation rather than unmodelled serialization tags.
  • Update: Removed the duplicated clean-room source listings from the agent governance references, leaving the contribution guide the canonical copy.
  • Update: Updated ADR 0009 and Dashboard component reuse evaluation to describe the esbuild asset bundling and vanilla JavaScript browser runtime architecture.
  • Correction: Reconciled the quickstart guide to use default local organization resolution across key creation and REST query examples.
  • Update: Documented the executor liveness timeout and ping interval parameters in Recovery.
  • Update: Added exact permitted source citations for the workflow status cancellation and resume SQL update semantics in Data plane.
  • Update: Clarified the data-plane fallback metrics and alert rules as planned observability tier features in Data plane.
  • Update: Removed local scratch path references from the contributor documentation and project rules.
  • Update: Rebuilt Conductor Protocol (WebSocket) covering all 32 implemented message types with normalized envelope definitions, aligned handshake and alert payloads, and inline citations for the idempotence guarantees.
  • Creation: Added NOTICE acknowledging the clean-room derivation of wire types from MIT-licensed SDK source and amended ADR 0001.
  • Correction: Corrected the schedule property mappings and list workflow filter names in Wire to REST mapping and removed the fabricated HTTP 502 status claims.
  • Update: Reconciled ADR 0008 with the OpenAPI specification enum for the declarative alert rule types.
  • Update: Documented the external alerting notification channels (Webhook with timestamped HMAC-SHA256 signatures, Slack, PagerDuty) as Relay control plane extensions in Metrics, alerting, and HA peer forwarding.
  • Update: Updated the Java SDK verification status in Multi-SDK verification matrix to required for the socket, presence, chaos, and live fork cells (Cells 1, 2, 3, 5, and 7) backed by dual-executor container orchestration and real timer failover, while documenting the upstream schema version divergence (v19 vs v107) for the data-plane cells (Cells 4 and 6).

2026-09-08

  • Correction: Corrected the resume SQL status predicate to status NOT IN ('SUCCESS', 'ERROR') in Data plane, aligned with the Go, Python, and TypeScript implementations, and documented the durable sleep and message receive cancellation semantics across SDKs.
  • Correction: Corrected the Problem Details specification citation to RFC 9457 in Client behaviour.
  • Update: Documented the wire and data-plane parity for cancellation and resume operations, step-boundary outcome check semantics across SDKs, and served-from auditing in Data plane.
  • Creation: Added Declarative operations documenting the relay.yaml manifest format, relay diff, and relay apply.
  • Creation: Added Data plane documenting optional application database access through the Go SDK client, fallback routing, and safety invariants.
  • Update: Updated the database access invariant in AGENTS.md to permit optional data-plane reads and mutations through the official SDK client library.
  • Creation: Added ADR 0004 recording optional data-plane access via the SDK client.
  • Creation: Added ADR 0005, ADR 0006, and ADR 0007 recording rejected explorations for executor sidecars, network tunnels, and native Postgres extensions.
  • Creation: Added Conformance testing documenting the conformance test suite, its in-process and blackbox runners, the relay test-conformance command, and the make test/conformance target.
  • Update: Documented web dashboard access in the quickstart guide.
  • Update: Documented alerting WebSocket dispatch and multi-instance peer forwarding in Executor WebSocket Protocol.
  • Update: Documented executor lifecycle state transitions, timeout parameters, and recovery failover mechanics in Executor WebSocket Protocol.
  • Update: Updated the quickstart guide with REST API querying, dbosctl CLI usage, and RFC 9457 Problem Details error responses.
  • Update: Expanded Wire to REST mapping with comprehensive field and type mappings for workflows, steps, events, notifications, queues, and schedules.
  • Refactor: Sanitized internal verification identifiers across the discovery documents.
  • Creation: Opened the usage section with Quickstart for running Relay locally with Postgres.
  • Update: Added development targets to the contributor guide and noted completion of the discovery findings and initial foundation packages.
  • Update: Added governance invariants to the contributor guide and maintainer guide on scope tightness, avoiding duplication and divergence, and keeping committed files free of internal process references.
  • Update: Linked the usage section from the root index.
  • Creation: Opened the discovery section and its provenance ledger recording permitted public sources for clean-room derivation.
  • Creation: Opened the protocol section index for the executor WebSocket specification and wire mappings.
  • Creation: Added ADR 0003 recording Go as the implementation language, which closes the stack question discovery was opened to answer. The record also fixes the supporting library choices, including the corrected import path for the WebSocket library, whose old path appears in older design notes.
  • Update: Linked both the discovery and protocol sections from the root index.
  • Update: Components now names the planned Go package for each module. The page still describes an intended design, and says so.

2026-09-07

  • Creation: Opened the bundle with the operational baseline. Added the root index, this log, the overview, the design section (goals, compatibility tiers, terminology), the architecture section (components, recovery), the first two decision records, and the contribution section (guide, clean-room rules, maintainer guide).
  • Note: The bundle deliberately has no usage or reference section yet. There is nothing to run, so a page describing how to run it would be fiction. Both sections open when the first binary does.
  • Note: Every architecture page describes an intended design, not shipped behaviour, and says so. Pages are rewritten against the code as the code lands.

2026-09-08, Discovery and Foundation Core

Added discovery reference documents and initial foundation packages: