@selvajs/server 0.2.0-beta.1

package/src/compute/transform-input.ts

@@ -0,0 +1,52 @@
+import { type InputParam, type InputParamSchema, processInput } from '@selvajs/compute';
+import type { SchemaInput } from '@selvajs/schemas';
+
+/**
+ * Adapt a persisted `SchemaInput` (plus the user's chosen value) into the package's
+ * raw `InputParamSchema`, then let `@selvajs/compute`'s own `processInput` produce the
+ * typed `InputParam`. The package handles every paramType (Number/Integer/Text/Boolean/
+ * ValueList/Geometry/File/Color), normalizes the lowercase UI paramType to its
+ * PascalCase form, and falls back gracefully on underspecified inputs — so we no longer
+ * maintain a parallel hand-rolled transform that silently coerced valueList/file/color
+ * to Text and drifted from the package (and from the parapet app, which already delegates
+ * here). `values`/`acceptedFormats` are absent on `SchemaInput` (they live on the layout
+ * item's config), so valueList/file inputs fall back to carrying the selected value with
+ * no option list — the same value that reaches Grasshopper.
+ */
+export function transformInputParameter(
+	input: SchemaInput & { minimum?: number; maximum?: number; stepSize?: number },
+	value: unknown
+): InputParam {
+	const raw: InputParamSchema = {
+		id: input.id,
+		name: input.nickname,
+		nickname: input.nickname || null,
+		description: input.description || '',
+		// Dynamic value lists ride the ValueList contract on the wire — the plugin's
+		// GetDynamicValueListParameter deliberately reuses TypeName "ValueList" so the
+		// compute fork's existing ValueList input case assigns it. processInput has no
+		// dynamicValueList handler; without this mapping it falls back to Geometry with
+		// a null default and TreeBuilder DROPS the input, so the user's selection never
+		// reaches the definition (the param then solves on its own stale fallback).
+		paramType: input.paramType === 'dynamicValueList' ? 'valueList' : input.paramType,
+		treeAccess: input.inputStructure === 'tree',
+		minimum: input.minimum ?? null,
+		maximum: input.maximum ?? null,
+		atLeast: 1,
+		atMost: 1,
+		stepSize: input.stepSize,
+		// The user's selection wins; otherwise the schema default.
+		default: value ?? input.default
+	};
+
+	const processed = processInput(raw);
+	// processInput's default-normalization only understands scalars and innerTree
+	// objects — a plain array default (multi-select widgets, e.g. a dynamic value
+	// list checklist) is dropped as "malformed", which would omit the input from
+	// the solve entirely. Restore it; TreeBuilder.appendFlat handles arrays natively.
+	const effective = value ?? input.default;
+	if (Array.isArray(effective) && processed.default == null) {
+		(processed as { default: unknown }).default = effective;
+	}
+	return processed;
+}

package/src/definitions/__tests__/load-for-render.test.ts

@@ -0,0 +1,244 @@
+/**
+ * Tests for `createDefinitionLoader` (K4) — version resolution, error
+ * classification, and the ADR 0005 schema-staleness behavior: a cached schema
+ * is used only at the app's current format version; anything else re-extracts
+ * from compute and persists back (best-effort, current-version only).
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { UI_SCHEMA_VERSION, type UISchema } from '@selvajs/schemas';
+import type {
+	ComputeServerConfig,
+	DefinitionRecord,
+	DefinitionVersion,
+	RequestContext
+} from '@selvajs/platform';
+import { createDefinitionLoader, DefinitionLoadError } from '../load-for-render.js';
+
+const ctx = { userId: 'user-1' } as RequestContext;
+
+function uiSchema(version: string, inputs: unknown[] = []): UISchema {
+	return {
+		id: 'schema-1',
+		name: 'Test',
+		schemaVersion: version,
+		inputs,
+		outputs: [],
+		layout: { type: 'tabbed', tabs: [] }
+	} as unknown as UISchema;
+}
+
+const record = {
+	guid: 'def-1',
+	projectId: 'proj-1',
+	computeServerId: null,
+	liveVersionId: 'v-live',
+	draftVersionId: 'v-draft'
+} as unknown as DefinitionRecord;
+
+function version(overrides: Partial<DefinitionVersion> = {}): DefinitionVersion {
+	return {
+		id: 'v-live',
+		definitionId: 'def-1',
+		versionNumber: 1,
+		fileExt: 'gh',
+		fileKey: 'definitions/def-1/versions/v1.gh',
+		uploadedBy: 'user-1',
+		uploadedAt: '2026-07-01T00:00:00Z',
+		...overrides
+	} as DefinitionVersion;
+}
+
+const computeServer = { id: 'srv-1', serverUrl: 'http://c.example' } as ComputeServerConfig;
+
+function makeDeps(overrides: Record<string, unknown> = {}) {
+	const getIO = vi.fn(async () => ({ inputs: [{ id: 'a', default: 42 }], outputs: [] }));
+	const deps = {
+		storage: { get: vi.fn(async () => new Uint8Array([1, 2, 3])) },
+		definitions: {
+			getVersion: vi.fn(async () => version()),
+			setVersionSchema: vi.fn(async () => {})
+		},
+		projects: { getProject: vi.fn(async () => ({ id: 'proj-1', orgId: 'org-1' })) },
+		resolveServer: vi.fn(async () => computeServer),
+		getClient: vi.fn(async () => ({ client: { getIO, getRawIO: vi.fn() } })),
+		fetchSchema: vi.fn(async () => uiSchema(UI_SCHEMA_VERSION, [{ id: 'a' }])),
+		onWarn: vi.fn(),
+		...overrides
+	};
+	return {
+		deps: deps as never as Parameters<typeof createDefinitionLoader>[0],
+		mocks: deps,
+		getIO
+	};
+}
+
+async function flushMicrotasks() {
+	await new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+describe('schema cache staleness (ADR 0005)', () => {
+	it('uses the cached schema when its version matches, without re-extracting or persisting', async () => {
+		const cached = uiSchema(UI_SCHEMA_VERSION, [{ id: 'a' }]);
+		const { deps, mocks } = makeDeps();
+		mocks.definitions.getVersion.mockResolvedValue(version({ schema: cached }));
+
+		const result = await createDefinitionLoader(deps)(ctx, record, 'live');
+
+		expect(mocks.fetchSchema).not.toHaveBeenCalled();
+		expect(mocks.definitions.setVersionSchema).not.toHaveBeenCalled();
+		// Compute defaults are merged into the cached schema's inputs.
+		expect((result.schema.inputs[0] as { default?: unknown }).default).toBe(42);
+	});
+
+	it('re-extracts and persists when the cached schema is at an older format version', async () => {
+		const { deps, mocks } = makeDeps();
+		mocks.definitions.getVersion.mockResolvedValue(version({ schema: uiSchema('2.10.0') }));
+
+		await createDefinitionLoader(deps)(ctx, record, 'live');
+		await flushMicrotasks();
+
+		expect(mocks.fetchSchema).toHaveBeenCalledTimes(1);
+		expect(mocks.definitions.setVersionSchema).toHaveBeenCalledWith(
+			ctx,
+			'v-live',
+			expect.objectContaining({ schemaVersion: UI_SCHEMA_VERSION })
+		);
+	});
+
+	it('re-extracts and persists when no schema is cached (pre-caching row)', async () => {
+		const { deps, mocks } = makeDeps();
+		mocks.definitions.getVersion.mockResolvedValue(version({ schema: undefined }));
+
+		await createDefinitionLoader(deps)(ctx, record, 'live');
+		await flushMicrotasks();
+
+		expect(mocks.fetchSchema).toHaveBeenCalledTimes(1);
+		expect(mocks.definitions.setVersionSchema).toHaveBeenCalledTimes(1);
+	});
+
+	it('does NOT persist a re-extracted schema that is still not at the current version', async () => {
+		// Compute plugin behind the app: re-extraction yields an older format.
+		const { deps, mocks } = makeDeps({
+			fetchSchema: vi.fn(async () => uiSchema('2.10.0'))
+		});
+		mocks.definitions.getVersion.mockResolvedValue(version({ schema: undefined }));
+
+		const result = await createDefinitionLoader(deps)(ctx, record, 'live');
+		await flushMicrotasks();
+
+		expect(mocks.definitions.setVersionSchema).not.toHaveBeenCalled();
+		// The older schema still renders (older shapes only lack optional additions).
+		expect(result.schema.schemaVersion).toBe('2.10.0');
+	});
+
+	it('a failed persist warns but does not fail the render', async () => {
+		const { deps, mocks } = makeDeps();
+		mocks.definitions.getVersion.mockResolvedValue(version({ schema: undefined }));
+		mocks.definitions.setVersionSchema.mockRejectedValue(new Error('RLS: not allowed'));
+
+		const result = await createDefinitionLoader(deps)(ctx, record, 'live');
+		await flushMicrotasks();
+
+		expect(result.schema.schemaVersion).toBe(UI_SCHEMA_VERSION);
+		expect(mocks.onWarn).toHaveBeenCalledWith(expect.stringContaining('cache refresh failed'));
+	});
+});
+
+describe('version resolution', () => {
+	it('resolves the draft pointer for the draft channel', async () => {
+		const { deps, mocks } = makeDeps();
+		mocks.definitions.getVersion.mockResolvedValue(version({ id: 'v-draft' }));
+
+		await createDefinitionLoader(deps)(ctx, record, 'draft');
+		expect(mocks.definitions.getVersion).toHaveBeenCalledWith(ctx, 'v-draft');
+	});
+
+	it('an explicit versionId wins over the channel pointer', async () => {
+		const { deps, mocks } = makeDeps();
+		mocks.definitions.getVersion.mockResolvedValue(version({ id: 'v-7' }));
+
+		await createDefinitionLoader(deps)(ctx, record, 'live', 'v-7');
+		expect(mocks.definitions.getVersion).toHaveBeenCalledWith(ctx, 'v-7');
+	});
+
+	it("rejects a version that belongs to another definition ('data')", async () => {
+		const { deps, mocks } = makeDeps();
+		mocks.definitions.getVersion.mockResolvedValue(version({ definitionId: 'other-def' }));
+
+		await expect(createDefinitionLoader(deps)(ctx, record, 'live')).rejects.toMatchObject({
+			name: 'DefinitionLoadError',
+			kind: 'data'
+		});
+	});
+});
+
+describe('error classification', () => {
+	it("no pointer for the channel → 'data'", async () => {
+		const { deps } = makeDeps();
+		const bare = { ...record, liveVersionId: null } as unknown as DefinitionRecord;
+		await expect(createDefinitionLoader(deps)(ctx, bare, 'live')).rejects.toMatchObject({
+			kind: 'data'
+		});
+	});
+
+	it("missing blob → 'data'", async () => {
+		const { deps, mocks } = makeDeps();
+		mocks.storage.get.mockResolvedValue(null as never);
+		await expect(createDefinitionLoader(deps)(ctx, record, 'live')).rejects.toMatchObject({
+			kind: 'data'
+		});
+	});
+
+	it("unresolvable compute server → 'missing-config'", async () => {
+		const { deps, mocks } = makeDeps();
+		mocks.resolveServer.mockRejectedValue(new Error('none visible'));
+		await expect(createDefinitionLoader(deps)(ctx, record, 'live')).rejects.toMatchObject({
+			kind: 'missing-config'
+		});
+	});
+
+	it("client connect failure → 'connect'", async () => {
+		const { deps, mocks } = makeDeps();
+		mocks.getClient.mockRejectedValue(new Error('ECONNREFUSED'));
+		await expect(createDefinitionLoader(deps)(ctx, record, 'live')).rejects.toMatchObject({
+			kind: 'connect'
+		});
+	});
+
+	it("IO/schema phase failure → 'schema'", async () => {
+		const { deps, mocks } = makeDeps({
+			fetchSchema: vi.fn(async () => {
+				throw new Error('no Schema output');
+			})
+		});
+		mocks.definitions.getVersion.mockResolvedValue(version({ schema: undefined }));
+		const err = await createDefinitionLoader(deps)(ctx, record, 'live').catch((e) => e);
+		expect(err).toBeInstanceOf(DefinitionLoadError);
+		expect(err.kind).toBe('schema');
+	});
+});
+
+describe('compute default merging', () => {
+	beforeEach(() => vi.clearAllMocks());
+
+	it('converts Color defaults to hex', async () => {
+		const { deps, mocks } = makeDeps({
+			getClient: vi.fn(async () => ({
+				client: {
+					getIO: vi.fn(async () => ({
+						inputs: [{ id: 'col', paramType: 'Color', default: '255,128,0' }],
+						outputs: []
+					})),
+					getRawIO: vi.fn()
+				}
+			}))
+		});
+		mocks.definitions.getVersion.mockResolvedValue(
+			version({ schema: uiSchema(UI_SCHEMA_VERSION, [{ id: 'col' }]) })
+		);
+
+		const result = await createDefinitionLoader(deps)(ctx, record, 'live');
+		expect((result.schema.inputs[0] as { default?: unknown }).default).toBe('#ff8000');
+	});
+});

package/src/definitions/__tests__/schema-extraction.test.ts

@@ -0,0 +1,137 @@
+/**
+ * Tests for the compute-schema extraction gate (K4 / ADR 0005).
+ *
+ * `fetch` is stubbed per test to script the compute `/grasshopper/schema`
+ * response. The version-compat gate (`assertSupportedSchemaVersion`) is also
+ * exercised directly: newer-than-supported must throw 'unsupported', while
+ * older / missing versions pass (compute's C# migrator emits its own current
+ * version; older shapes only lack optional additions).
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { UI_SCHEMA_VERSION, type UISchema } from '@selvajs/schemas';
+import type { ComputeServerConfig } from '@selvajs/platform';
+import {
+	fetchSchemaFromCompute,
+	assertSupportedSchemaVersion,
+	SchemaExtractionError
+} from '../schema-extraction.js';
+
+function schema(version?: string): UISchema {
+	return {
+		id: 'schema-1',
+		name: 'Test',
+		...(version !== undefined && { schemaVersion: version }),
+		inputs: [],
+		outputs: [],
+		layout: { type: 'tabbed', tabs: [] }
+	} as unknown as UISchema;
+}
+
+function bump(version: string, part: 0 | 1 | 2): string {
+	const nums = version.split('.').map(Number);
+	nums[part] += 1;
+	return nums.join('.');
+}
+
+const server: ComputeServerConfig = {
+	id: 'srv-1',
+	serverUrl: 'http://compute.example.com',
+	apiKey: 'secret'
+} as ComputeServerConfig;
+
+describe('assertSupportedSchemaVersion', () => {
+	it('passes the current version', () => {
+		expect(() => assertSupportedSchemaVersion(schema(UI_SCHEMA_VERSION))).not.toThrow();
+	});
+
+	it('passes older versions (older shapes only lack optional additions)', () => {
+		expect(() => assertSupportedSchemaVersion(schema('1.0.0'))).not.toThrow();
+		expect(() => assertSupportedSchemaVersion(schema('2.0.0'))).not.toThrow();
+	});
+
+	it('passes a schema without a version (pre-2.12.0 plugin)', () => {
+		expect(() => assertSupportedSchemaVersion(schema())).not.toThrow();
+	});
+
+	it.each([
+		['major', 0],
+		['minor', 1],
+		['patch', 2]
+	] as const)('throws unsupported for a newer %s version', (_label, part) => {
+		const newer = bump(UI_SCHEMA_VERSION, part);
+		try {
+			assertSupportedSchemaVersion(schema(newer));
+			expect.unreachable('should have thrown');
+		} catch (err) {
+			expect(err).toBeInstanceOf(SchemaExtractionError);
+			expect((err as SchemaExtractionError).kind).toBe('unsupported');
+			expect((err as SchemaExtractionError).message).toContain(newer);
+			expect((err as SchemaExtractionError).message).toContain(UI_SCHEMA_VERSION);
+		}
+	});
+
+	it('passes an unparseable version string (fail open — invalid is not "newer")', () => {
+		expect(() => assertSupportedSchemaVersion(schema('abc'))).not.toThrow();
+	});
+});
+
+describe('fetchSchemaFromCompute', () => {
+	let fetchMock: ReturnType<typeof vi.fn>;
+
+	beforeEach(() => {
+		fetchMock = vi.fn();
+		vi.stubGlobal('fetch', fetchMock);
+	});
+
+	afterEach(() => {
+		vi.unstubAllGlobals();
+	});
+
+	function computeResponse(schemas: unknown[]): Response {
+		// Compute wraps results with PascalCase keys.
+		return new Response(JSON.stringify([{ FileName: 'definition.gh', Schemas: schemas }]), {
+			status: 200,
+			headers: { 'content-type': 'application/json' }
+		});
+	}
+
+	it('extracts the first schema and sends the API key header', async () => {
+		fetchMock.mockResolvedValue(computeResponse([schema(UI_SCHEMA_VERSION)]));
+		const result = await fetchSchemaFromCompute(new Uint8Array([1]), server);
+		expect(result.id).toBe('schema-1');
+
+		const [url, init] = fetchMock.mock.calls[0];
+		expect(url).toBe('http://compute.example.com/grasshopper/schema');
+		expect((init.headers as Record<string, string>)['RhinoComputeKey']).toBe('secret');
+	});
+
+	it('throws unreachable when the network request fails', async () => {
+		fetchMock.mockRejectedValue(new Error('ECONNREFUSED'));
+		await expect(fetchSchemaFromCompute(new Uint8Array([1]), server)).rejects.toMatchObject({
+			name: 'SchemaExtractionError',
+			kind: 'unreachable'
+		});
+	});
+
+	it('throws unreachable on a non-OK status', async () => {
+		fetchMock.mockResolvedValue(new Response('nope', { status: 500 }));
+		await expect(fetchSchemaFromCompute(new Uint8Array([1]), server)).rejects.toMatchObject({
+			kind: 'unreachable'
+		});
+	});
+
+	it('throws invalid when the definition yields no schemas', async () => {
+		fetchMock.mockResolvedValue(computeResponse([]));
+		await expect(fetchSchemaFromCompute(new Uint8Array([1]), server)).rejects.toMatchObject({
+			kind: 'invalid'
+		});
+	});
+
+	it('applies the version gate to the extracted schema', async () => {
+		fetchMock.mockResolvedValue(computeResponse([schema(bump(UI_SCHEMA_VERSION, 1))]));
+		await expect(fetchSchemaFromCompute(new Uint8Array([1]), server)).rejects.toMatchObject({
+			kind: 'unsupported'
+		});
+	});
+});

package/src/definitions/definition-service.ts

@@ -0,0 +1,243 @@
+import { randomUUID } from 'node:crypto';
+import type {
+	IDataProvider,
+	IStorageProvider,
+	RequestContext,
+	DefinitionRecord,
+	DefinitionFileExt,
+	DefinitionVersion,
+	UpdateMetadataInput,
+	UISchema
+} from '@selvajs/platform';
+import { ProviderError, definitionPaths } from '@selvajs/platform';
+
+/**
+ * Input passed to `DefinitionService.create`. Carries everything the service
+ * needs to assemble a `DefinitionRecord` plus orchestrate the v1 upload.
+ *
+ * Distinct from `CreateDefinitionInputSchema` exported by
+ * `@selvajs/platform/definitions`, which validates the user-facing
+ * HTTP body (no guid/ownerId — those are derived server-side).
+ */
+export interface CreateDefinitionRecord {
+	guid: string;
+	projectId: string;
+	ownerId: string;
+	fileExt: DefinitionFileExt;
+	originalFilename?: string;
+	displayName: string;
+	description?: string;
+	category?: string;
+	tags?: string[];
+	coverImage?: string;
+	computeServerId?: string;
+}
+
+/**
+ * Orchestrates writes that span IDataProvider + IStorageProvider for the
+ * spec §6 versioning model. Lives in @selvajs/selva (not @selvajs/platform)
+ * because it is application orchestration, not platform contract.
+ *
+ * Ordering rules:
+ *
+ *   create — metadata-first, then v1:
+ *     1. Write record with status='pending', both pointers null
+ *     2. Upload v1 blob to versions/v1.{ext}
+ *     3. Insert DefinitionVersion row v1
+ *     4. `attachInitialVersion` — atomically set live + draft pointers and
+ *        flip status to 'draft' in a single store operation.
+ *   Step 4 is one round-trip so a mid-flight failure can't leave a partial
+ *   state (status='draft' with null pointers, or status='pending' with
+ *   pointers set). If step 2 fails the record stays 'pending' with no
+ *   blob and is filtered out of list endpoints by default.
+ *
+ *   uploadVersion — append-only:
+ *     1. Resolve next versionNumber from the version list
+ *     2. Upload blob to versions/v{N}.{ext}
+ *     3. Insert DefinitionVersion row
+ *     4. Advance draft pointer (live unchanged)
+ *
+ *   publish — pointer flip only, no blob writes.
+ *
+ *   deleteVersion — store enforces "not referenced by live/draft"; on
+ *   success, delete the underlying blob.
+ */
+export class DefinitionService {
+	constructor(
+		private data: IDataProvider,
+		private storage: IStorageProvider
+	) {}
+
+	async create(
+		ctx: RequestContext,
+		input: CreateDefinitionRecord,
+		file: Uint8Array,
+		schema: UISchema
+	): Promise<{ record: DefinitionRecord; version: DefinitionVersion }> {
+		const now = new Date().toISOString();
+		const actor = ctx.userId || input.ownerId;
+		const record: DefinitionRecord = {
+			guid: input.guid,
+			projectId: input.projectId,
+			ownerId: input.ownerId,
+			createdBy: actor,
+			updatedBy: actor,
+			displayName: input.displayName,
+			description: input.description,
+			category: input.category,
+			tags: input.tags,
+			coverImage: input.coverImage,
+			computeServerId: input.computeServerId,
+			status: 'pending',
+			solveCount: 0,
+			liveVersionId: null,
+			draftVersionId: null,
+			createdAt: now,
+			updatedAt: now,
+			deletedAt: null
+		};
+
+		// 1. Metadata first — if this fails there's nothing to clean up.
+		await this.data.definitions.create(ctx, record);
+
+		// 2. v1 blob — if this fails the record stays 'pending' and is hidden
+		//    from default list queries.
+		const versionId = randomUUID();
+		const fileKey = definitionPaths.version(input.guid, 1, input.fileExt);
+		await this.storage.put(fileKey, file, 'application/octet-stream');
+
+		// 3. Version row.
+		const version: DefinitionVersion = {
+			id: versionId,
+			definitionId: input.guid,
+			versionNumber: 1,
+			fileExt: input.fileExt,
+			fileKey,
+			originalFilename: input.originalFilename,
+			uploadedBy: actor,
+			uploadedAt: now,
+			schema,
+			schemaExtractedAt: now
+		};
+		await this.data.definitions.createVersion(ctx, version);
+
+		// 4. Atomically point both channels at v1 and flip status='draft' in a
+		//    single store operation. Replaces three separate writes
+		//    (setLiveVersion + setDraftVersion + update) — see the class
+		//    header for why ordering matters here.
+		await this.data.definitions.attachInitialVersion(ctx, input.guid, versionId);
+
+		return {
+			record: { ...record, status: 'draft', liveVersionId: versionId, draftVersionId: versionId },
+			version
+		};
+	}
+
+	/**
+	 * Upload a new version of an existing definition. Writes the blob, inserts
+	 * the version row, and advances the draft pointer. `live` is unchanged —
+	 * use `publish` to promote.
+	 */
+	async uploadVersion(
+		ctx: RequestContext,
+		guid: string,
+		file: Uint8Array,
+		ext: DefinitionFileExt,
+		originalName: string,
+		schema: UISchema,
+		changeNote?: string
+	): Promise<DefinitionVersion> {
+		const existing = await this.data.definitions.get(ctx, guid);
+		if (!existing) throw new ProviderError(`Definition not found: ${guid}`, 404);
+
+		// Highest existing versionNumber + 1; covers gaps from deletions.
+		const versions = await this.data.definitions.listVersions(ctx, guid, { limit: 1 });
+		const next = (versions.items[0]?.versionNumber ?? 0) + 1;
+
+		const versionId = randomUUID();
+		const fileKey = definitionPaths.version(guid, next, ext);
+		await this.storage.put(fileKey, file, 'application/octet-stream');
+
+		const now = new Date().toISOString();
+		const actor = ctx.userId || existing.ownerId;
+		const version: DefinitionVersion = {
+			id: versionId,
+			definitionId: guid,
+			versionNumber: next,
+			fileExt: ext,
+			fileKey,
+			originalFilename: originalName,
+			uploadedBy: actor,
+			uploadedAt: now,
+			changeNote: changeNote?.trim() || undefined,
+			schema,
+			schemaExtractedAt: now
+		};
+		await this.data.definitions.createVersion(ctx, version);
+		await this.data.definitions.setDraftVersion(ctx, guid, versionId);
+
+		return version;
+	}
+
+	/**
+	 * Advance the live channel. If `versionId` is omitted, promotes the
+	 * current draft. Pass an arbitrary version id to roll forward/back —
+	 * spec §6 makes rollback a first-class operation.
+	 */
+	async publish(ctx: RequestContext, guid: string, versionId?: string): Promise<DefinitionVersion> {
+		const existing = await this.data.definitions.get(ctx, guid);
+		if (!existing) throw new ProviderError(`Definition not found: ${guid}`, 404);
+
+		const target = versionId ?? existing.draftVersionId;
+		if (!target) throw new ProviderError('No version to publish', 400);
+
+		const version = await this.data.definitions.getVersion(ctx, target);
+		if (!version || version.definitionId !== guid) {
+			throw new ProviderError(`Version '${target}' not found for this definition`, 404);
+		}
+
+		await this.data.definitions.setLiveVersion(ctx, guid, target);
+		// Flip status to 'published' the first time live moves off pending/draft.
+		if (existing.status === 'draft' || existing.status === 'pending') {
+			await this.data.definitions.update(ctx, guid, { status: 'published' });
+		}
+		return version;
+	}
+
+	async deleteVersion(ctx: RequestContext, guid: string, versionId: string): Promise<void> {
+		const version = await this.data.definitions.getVersion(ctx, versionId);
+		if (!version || version.definitionId !== guid) {
+			throw new ProviderError(`Version '${versionId}' not found for this definition`, 404);
+		}
+		// Store enforces the live/draft reference check; if it throws, blob stays.
+		await this.data.definitions.deleteVersion(ctx, versionId);
+		await this.storage.delete(version.fileKey);
+	}
+
+	async updateMeta(ctx: RequestContext, guid: string, patch: UpdateMetadataInput): Promise<void> {
+		await this.data.definitions.update(ctx, guid, patch);
+	}
+
+	async saveCoverImage(ctx: RequestContext, guid: string, imageData: Uint8Array): Promise<string> {
+		const path = definitionPaths.image(guid);
+		await this.storage.put(path, imageData, 'image/webp');
+		const url = this.storage.getPublicUrl(path);
+		await this.data.definitions.update(ctx, guid, { coverImage: url });
+		return url;
+	}
+
+	async delete(ctx: RequestContext, guid: string): Promise<void> {
+		// CONTRACT (spec §9): metadata is soft-deleted (preserved for audit,
+		// restorable by clearing `deleted_at`); blobs are HARD-deleted. The
+		// record is the audit trail; the blobs are storage cost.
+		//
+		// Order matters. Metadata first so the API immediately hides the
+		// record (RLS / `deleted_at IS NULL` filter). If the blob wipe then
+		// fails, the orphan storage is unreachable through the API — a
+		// retention sweep can clean it up later. The reverse order leaves a
+		// window where the record is still alive but its blobs are gone — a
+		// 404 source for any in-flight reader.
+		await this.data.definitions.delete(ctx, guid);
+		await this.storage.deletePrefix(definitionPaths.prefix(guid));
+	}
+}