@selvajs/server 0.2.0-beta.2 → 0.2.0-beta.4

package/src/compute/transform-input.ts

@@ -1,66 +0,0 @@
-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);
-	// Two cases where processInput drops a default we must carry anyway (the
-	// default IS what TreeBuilder puts on the wire; a dropped default means the
-	// input is omitted from the solve and the user's selection never reaches
-	// Grasshopper):
-	//  - a plain array default (multi-select widgets, e.g. a dynamic value list
-	//    checklist) is dropped as "malformed"; TreeBuilder.appendFlat handles
-	//    arrays natively.
-	//  - since @selvajs/compute 3.1.0-beta.5, the ValueList fallback drops a
-	//    scalar default it can't validate against a `values` map — and
-	//    `SchemaInput` never carries the option map (it lives on the layout
-	//    item's config), so every app value-list selection lands here.
-	const effective = value ?? input.default;
-	if (processed.default == null && effective != null) {
-		if (Array.isArray(effective)) {
-			(processed as { default: unknown }).default = effective;
-		} else if (processed.paramType === 'ValueList' && typeof effective !== 'object') {
-			// Scoped to ValueList: for other types a dropped scalar default means
-			// the package rejected it as unparseable — restoring it would ship
-			// garbage to Grasshopper.
-			(processed as { default: unknown }).default = effective;
-		}
-	}
-	return processed;
-}

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

@@ -1,244 +0,0 @@
-/**
- * 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

@@ -1,137 +0,0 @@
-/**
- * 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

@@ -1,243 +0,0 @@
-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));
-	}
-}