feat(analytics): BI-P061 — dashboard releases, with the publish race measured both ways
CI (SIAX Cloud) / quality (push) Successful in 50s
Security Scan (SIAX Cloud) / security (push) Successful in 45s
CI (SIAX Cloud) / security (push) Successful in 1m0s
CI (SIAX Cloud) / integration (push) Successful in 1m12s
CI (SIAX Cloud) / quality (pull_request) Successful in 1m6s
CI (SIAX Cloud) / security (pull_request) Successful in 33s
Security Scan (SIAX Cloud) / security (pull_request) Successful in 32s
CI (SIAX Cloud) / integration (pull_request) Successful in 47s

DRAFT -> PUBLISHED -> SUPERSEDED as a ledger (sql/010) rather than a column on
the frozen version: sql/008 already makes DashboardVersion immutable at the
database, and a lifecycle column there would have meant weakening that.

Rollback mints a NEW version carrying the old document and publishes it, so
"we went back to v3" is a timestamped fact (v5 = rollback_of_version 3) rather
than a hole where v4 used to be. It is verified by BI-P060 canonical hash, and
documentOf() refuses to serve a stored document whose hash no longer matches
the release — a dashboard that renders an unapproved definition is worse than
one that will not open.

The claim worth attacking is "only one release can be live". The application
check is read-then-write, so it is NOT the guarantee, and the evidence says so
in both directions against Postgres 16.15:

  guard_absent   partial unique index dropped -> BOTH concurrent publishes
                 commit, dashboard ends with TWO live versions
  guard_present  index in place -> loser fails 23505 on
                 opt_analytics_dashboard_release_one_published, one live

evidence/bi-p061/dashboard-release-race.json, reproducible with
scripts/bi-p061-release-race.mjs.

Two findings while writing the tests, both fixed here rather than papered over:
the one-draft-per-dashboard index makes the two-draft race impossible to even
construct (so the race is run as two create-and-publish transactions, which is
what a "save and publish" button does), and an UPDATE matching zero rows
raises nothing — which reads as "refused" to a careless test, so the
immutability test asserts the row exists first.

23 tests: 8 unit + 15 against live Postgres.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
2026-09-07 03:51:04 +02:00
parent 2af126dfc4
commit 1a12e8a882
6 changed files with 1311 additions and 0 deletions
@@ -0,0 +1,449 @@
/**
* src/analytics/dashboards/dashboard-release.ts
* ==============================================
* BI-P061 — DASHBOARD VERSIONING.
*
* DRAFT -> PUBLISHED -> SUPERSEDED, and the DoD: "rollback to previous
* dashboard definition".
*
* Three decisions worth stating, because each one is a bug someone would
* otherwise write:
*
* 1. ROLLBACK MINTS A NEW VERSION. It does not resurrect the old release row
* and it does not edit the published one. "We went back to v3" is then a
* fact with a timestamp (v5 = rollback_of_version 3) instead of a hole in
* the history where v4 used to be. `verifyRollback()` proves the restore is
* faithful by comparing BI-P060 canonical hashes, so a rollback that
* silently restored a different document fails loudly.
*
* 2. THE DOCUMENT IS FROZEN, THE RELEASE MOVES. sql/008 makes
* DashboardVersion rows immutable at the database. The release ledger
* (sql/010) carries the state, and its trigger allows exactly two
* transitions and freezes every other column. Un-publishing is refused:
* it is how a rollback gets faked without leaving a trace.
*
* 3. THE APPLICATION CHECK IS NOT THE GUARANTEE. `publish()` checks for an
* existing published release, and that check is a read-then-write race.
* The partial unique index in sql/010 is what actually holds under
* concurrency; the realinfra test drops it, runs the race and shows two
* published releases for one dashboard, so nobody has to take that on
* faith. This module maps the resulting constraint violation onto a
* CONFLICT rather than a 500.
*/
import crypto from 'node:crypto';
import { SiaxError } from '../../platform/errors';
import { dashboardDocumentHash, parseDashboardDocument, type DashboardDocument } from './dashboard-document';
export const DASHBOARD_RELEASE_STATES = ['draft', 'published', 'superseded'] as const;
export type DashboardReleaseState = (typeof DASHBOARD_RELEASE_STATES)[number];
/** The only transitions that exist. Everything else is a refusal, not a no-op. */
const LEGAL_TRANSITIONS: Readonly<Record<DashboardReleaseState, readonly DashboardReleaseState[]>> = {
draft: ['published'],
published: ['superseded'],
superseded: [],
};
export function isLegalTransition(from: DashboardReleaseState, to: DashboardReleaseState): boolean {
return LEGAL_TRANSITIONS[from].includes(to);
}
export interface DashboardRelease {
release_id: string;
dashboard_id: string;
dashboard_version_id: string;
tenant_id: string;
project_id: string;
version: number;
state: DashboardReleaseState;
/** BI-P060 canonical hash of the released document. */
document_hash: string;
/** Set when this release restores an earlier version. */
rollback_of_version?: number;
created_by?: string;
created_at: string;
published_at?: string;
superseded_at?: string;
superseded_by_release_id?: string;
}
/** The immutable frozen document behind a release (sql/008's DashboardVersion). */
export interface DashboardVersionRecord {
dashboard_version_id: string;
dashboard_id: string;
tenant_id: string;
project_id: string;
version: number;
layout_json: string;
layout_hash: string;
created_at: string;
created_by?: string;
}
export interface TenantScope {
tenant_id: string;
project_id: string;
}
/**
* The persistence port. Deliberately narrow, and every method is tenant-scoped
* — there is no signature that lets a caller forget the tenant.
*/
export interface DashboardReleaseStore {
/** Highest version number ever minted for this dashboard, or 0. */
maxVersion(scope: TenantScope, dashboardId: string): Promise<number>;
insertVersionAndRelease(version: DashboardVersionRecord, release: DashboardRelease): Promise<void>;
getRelease(scope: TenantScope, releaseId: string): Promise<DashboardRelease | undefined>;
getVersion(scope: TenantScope, dashboardVersionId: string): Promise<DashboardVersionRecord | undefined>;
findVersionByNumber(
scope: TenantScope,
dashboardId: string,
version: number,
): Promise<DashboardVersionRecord | undefined>;
findByState(
scope: TenantScope,
dashboardId: string,
state: DashboardReleaseState,
): Promise<DashboardRelease | undefined>;
listReleases(scope: TenantScope, dashboardId: string): Promise<DashboardRelease[]>;
/**
* Publish `releaseId` and supersede `supersedes` in ONE transaction. Both or
* neither: a supersede that lands without its publish leaves a dashboard
* with no live version, and a publish that lands without its supersede
* leaves two.
*/
publishAtomically(args: {
scope: TenantScope;
releaseId: string;
publishedAt: string;
supersedes?: { release_id: string; superseded_at: string };
}): Promise<void>;
}
function conflict(detail: string): never {
throw new SiaxError('CONFLICT', '0pt.analytics.dashboard', detail);
}
function notFound(detail: string): never {
throw new SiaxError('NOT_FOUND', '0pt.analytics.dashboard', detail);
}
function assertScope(scope: TenantScope): void {
if (!scope?.tenant_id?.trim() || !scope?.project_id?.trim()) {
throw new SiaxError(
'UNAUTHENTICATED',
'0pt.analytics.dashboard',
'dashboard releases require a verified tenant_id + project_id',
);
}
}
export interface DraftResult {
release: DashboardRelease;
version: DashboardVersionRecord;
}
/**
* The lifecycle. Stateless apart from its store and its clock; the clock is
* injectable so a test can pin timestamps instead of sleeping.
*/
export class DashboardReleaseService {
constructor(
private readonly store: DashboardReleaseStore,
private readonly now: () => Date = () => new Date(),
private readonly newId: () => string = () => crypto.randomUUID(),
) {}
/**
* Freeze a document as the next version and open a DRAFT release for it.
* The document is re-parsed here even if the caller already parsed it: what
* gets frozen must be what the model accepts, not what a caller assembled.
*/
async draft(args: {
scope: TenantScope;
dashboardId: string;
document: unknown;
createdBy?: string;
rollbackOfVersion?: number;
}): Promise<DraftResult> {
assertScope(args.scope);
const document = parseDashboardDocument(args.document);
const existingDraft = await this.store.findByState(args.scope, args.dashboardId, 'draft');
if (existingDraft) {
conflict(
`dashboard "${args.dashboardId}" already has an open draft (version ${existingDraft.version}); ` +
`publish or abandon it before opening another — two drafts race to publish and the loser's ` +
`edits vanish`,
);
}
const next = (await this.store.maxVersion(args.scope, args.dashboardId)) + 1;
const at = this.now().toISOString();
const hash = dashboardDocumentHash(document);
const version: DashboardVersionRecord = {
dashboard_version_id: this.newId(),
dashboard_id: args.dashboardId,
tenant_id: args.scope.tenant_id,
project_id: args.scope.project_id,
version: next,
layout_json: JSON.stringify(document),
layout_hash: hash,
created_at: at,
...(args.createdBy ? { created_by: args.createdBy } : {}),
};
const release: DashboardRelease = {
release_id: this.newId(),
dashboard_id: args.dashboardId,
dashboard_version_id: version.dashboard_version_id,
tenant_id: args.scope.tenant_id,
project_id: args.scope.project_id,
version: next,
state: 'draft',
document_hash: hash,
created_at: at,
...(args.createdBy ? { created_by: args.createdBy } : {}),
...(args.rollbackOfVersion ? { rollback_of_version: args.rollbackOfVersion } : {}),
};
await this.store.insertVersionAndRelease(version, release);
return { release, version };
}
/**
* DRAFT -> PUBLISHED, superseding whatever was live, in one transaction.
* The pre-check exists to return a friendly CONFLICT; the guarantee is the
* partial unique index (sql/010).
*/
async publish(args: {
scope: TenantScope;
releaseId: string;
}): Promise<{ published: DashboardRelease; superseded?: DashboardRelease }> {
assertScope(args.scope);
const release = await this.store.getRelease(args.scope, args.releaseId);
if (!release) notFound(`dashboard release "${args.releaseId}" does not exist in this tenant`);
if (release.state !== 'draft') {
conflict(
`release "${args.releaseId}" is ${release.state}, not draft — ${release.state} -> published is ` +
`not a legal transition (BI-P061)`,
);
}
const live = await this.store.findByState(args.scope, release.dashboard_id, 'published');
const at = this.now().toISOString();
await this.store.publishAtomically({
scope: args.scope,
releaseId: release.release_id,
publishedAt: at,
...(live ? { supersedes: { release_id: live.release_id, superseded_at: at } } : {}),
});
return {
published: { ...release, state: 'published', published_at: at },
...(live
? {
superseded: {
...live,
state: 'superseded',
superseded_at: at,
superseded_by_release_id: release.release_id,
},
}
: {}),
};
}
/** The release currently serving, or undefined if the dashboard has never been published. */
async live(scope: TenantScope, dashboardId: string): Promise<DashboardRelease | undefined> {
assertScope(scope);
return this.store.findByState(scope, dashboardId, 'published');
}
/** The frozen document behind a release, re-parsed on the way out. */
async documentOf(scope: TenantScope, release: DashboardRelease): Promise<DashboardDocument> {
assertScope(scope);
const version = await this.store.getVersion(scope, release.dashboard_version_id);
if (!version) notFound(`dashboard version "${release.dashboard_version_id}" is missing`);
const document = parseDashboardDocument(JSON.parse(version.layout_json));
const hash = dashboardDocumentHash(document);
if (hash !== release.document_hash) {
// Storage returned something other than what was released. Refusing is
// the only safe answer: a dashboard that renders a document nobody
// approved is worse than a dashboard that will not open.
throw new SiaxError(
'PERMANENT_FAILURE',
'0pt.analytics.dashboard',
`stored document for release "${release.release_id}" hashes to ${hash}, not the released ` +
`${release.document_hash} — refusing to serve an unapproved definition`,
);
}
return document;
}
/**
* BI-P061's DoD. Restores version `toVersion` by minting a NEW version with
* the SAME document and publishing it. Returns the new release plus the
* verification that the restore is faithful.
*/
async rollback(args: {
scope: TenantScope;
dashboardId: string;
toVersion: number;
createdBy?: string;
}): Promise<{ release: DashboardRelease; restored_from: number; document_hash: string }> {
assertScope(args.scope);
const target = await this.store.findVersionByNumber(args.scope, args.dashboardId, args.toVersion);
if (!target) {
notFound(`dashboard "${args.dashboardId}" has no version ${args.toVersion} in this tenant`);
}
const live = await this.store.findByState(args.scope, args.dashboardId, 'published');
if (live && live.version === args.toVersion) {
conflict(`version ${args.toVersion} is already live; a rollback to the live version is a no-op`);
}
const document = parseDashboardDocument(JSON.parse(target.layout_json));
const hash = dashboardDocumentHash(document);
if (hash !== target.layout_hash) {
throw new SiaxError(
'PERMANENT_FAILURE',
'0pt.analytics.dashboard',
`version ${args.toVersion} hashes to ${hash} but was stored as ${target.layout_hash} — ` +
`refusing to roll back to a definition that has changed underneath us`,
);
}
const { release } = await this.draft({
scope: args.scope,
dashboardId: args.dashboardId,
document,
...(args.createdBy ? { createdBy: args.createdBy } : {}),
rollbackOfVersion: args.toVersion,
});
const { published } = await this.publish({ scope: args.scope, releaseId: release.release_id });
if (published.document_hash !== target.layout_hash) {
throw new SiaxError(
'PERMANENT_FAILURE',
'0pt.analytics.dashboard',
`rollback published ${published.document_hash}, not the requested ${target.layout_hash}`,
);
}
return { release: published, restored_from: args.toVersion, document_hash: published.document_hash };
}
/** Full ledger, oldest first. A rollback is an entry here, never a deletion. */
async history(scope: TenantScope, dashboardId: string): Promise<DashboardRelease[]> {
assertScope(scope);
const rows = await this.store.listReleases(scope, dashboardId);
return [...rows].sort((a, b) => a.version - b.version);
}
}
/**
* In-memory store. Used by the unit tests, and it enforces the same two
* uniqueness rules the SQL does — a store that is laxer than the database
* makes the unit tests pass on states production can never reach.
*/
export class InMemoryDashboardReleaseStore implements DashboardReleaseStore {
private readonly versions: DashboardVersionRecord[] = [];
private readonly releases: DashboardRelease[] = [];
private scoped<T extends { tenant_id: string; project_id: string }>(scope: TenantScope, rows: T[]): T[] {
return rows.filter((r) => r.tenant_id === scope.tenant_id && r.project_id === scope.project_id);
}
async maxVersion(scope: TenantScope, dashboardId: string): Promise<number> {
return this.scoped(scope, this.versions)
.filter((v) => v.dashboard_id === dashboardId)
.reduce((max, v) => Math.max(max, v.version), 0);
}
async insertVersionAndRelease(version: DashboardVersionRecord, release: DashboardRelease): Promise<void> {
const scope = { tenant_id: release.tenant_id, project_id: release.project_id };
if (
release.state === 'draft' &&
this.scoped(scope, this.releases).some(
(r) => r.dashboard_id === release.dashboard_id && r.state === 'draft',
)
) {
conflict('one open draft per dashboard');
}
if (this.versions.some((v) => v.dashboard_id === version.dashboard_id && v.version === version.version)) {
conflict(`version ${version.version} already exists for "${version.dashboard_id}"`);
}
this.versions.push({ ...version });
this.releases.push({ ...release });
}
async getRelease(scope: TenantScope, releaseId: string): Promise<DashboardRelease | undefined> {
const r = this.scoped(scope, this.releases).find((x) => x.release_id === releaseId);
return r ? { ...r } : undefined;
}
async getVersion(scope: TenantScope, id: string): Promise<DashboardVersionRecord | undefined> {
const v = this.scoped(scope, this.versions).find((x) => x.dashboard_version_id === id);
return v ? { ...v } : undefined;
}
async findVersionByNumber(
scope: TenantScope,
dashboardId: string,
version: number,
): Promise<DashboardVersionRecord | undefined> {
const v = this.scoped(scope, this.versions).find(
(x) => x.dashboard_id === dashboardId && x.version === version,
);
return v ? { ...v } : undefined;
}
async findByState(
scope: TenantScope,
dashboardId: string,
state: DashboardReleaseState,
): Promise<DashboardRelease | undefined> {
const r = this.scoped(scope, this.releases).find(
(x) => x.dashboard_id === dashboardId && x.state === state,
);
return r ? { ...r } : undefined;
}
async listReleases(scope: TenantScope, dashboardId: string): Promise<DashboardRelease[]> {
return this.scoped(scope, this.releases)
.filter((r) => r.dashboard_id === dashboardId)
.map((r) => ({ ...r }));
}
async publishAtomically(args: {
scope: TenantScope;
releaseId: string;
publishedAt: string;
supersedes?: { release_id: string; superseded_at: string };
}): Promise<void> {
const target = this.releases.find(
(r) =>
r.release_id === args.releaseId &&
r.tenant_id === args.scope.tenant_id &&
r.project_id === args.scope.project_id,
);
if (!target) notFound(`release "${args.releaseId}" not found`);
if (!isLegalTransition(target.state, 'published')) {
conflict(`illegal transition ${target.state} -> published`);
}
const alreadyLive = this.releases.find(
(r) =>
r.dashboard_id === target.dashboard_id &&
r.state === 'published' &&
r.release_id !== args.supersedes?.release_id,
);
if (alreadyLive) conflict('one published release per dashboard');
if (args.supersedes) {
const live = this.releases.find((r) => r.release_id === args.supersedes?.release_id);
if (!live) notFound(`release "${args.supersedes.release_id}" not found`);
if (!isLegalTransition(live.state, 'superseded')) {
conflict(`illegal transition ${live.state} -> superseded`);
}
live.state = 'superseded';
live.superseded_at = args.supersedes.superseded_at;
live.superseded_by_release_id = target.release_id;
}
target.state = 'published';
target.published_at = args.publishedAt;
}
}