@ours.network/fleet 0.15.6 → 0.16.0

package/dist/web/fleet-config-service.js

@@ -1,14 +1,15 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { chmodSync, existsSync, lstatSync, readFileSync, rmSync, } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
-import { stringify } from 'yaml';
 import { replaceFileAtomically, withFileLock } from '../atomic-file.js';
 import { loadConfig } from '../config.js';
 import { parseFleetDocument } from '../config-yaml.js';
 import { defaultConfigPath } from '../paths.js';
 import { FleetError } from '../application/errors.js';
+import { redactSourceSecrets, renderModelOntoSource } from './yaml-document-edit.js';
 export const REDACTED_ENV_VALUE = '__OURS_FLEET_SECRET_REDACTED__';
 const MAX_CONFIG_BYTES = 256 * 1024;
+const DIFF_CONTEXT_LINES = 3;
 const emptyReport = () => ({ ok: true, checks: [] });
 export class FleetConfigService {
     path;
@@ -32,13 +33,13 @@ export class FleetConfigService {
         this.assertRevision(baseRevision, currentSource);
         const current = parseFleetDocument(this.path, currentSource, 'strict').value;
         const restored = restoreRedactions(assertModel(model), current);
-        const source = serialize(restored);
-        const candidate = this.validateCandidate(source);
-        const [redactedCurrent, redactedNext] = [redactModel(current), redactModel(restored)];
+        const nextSource = render(currentSource, restored);
+        const candidate = this.validateCandidate(nextSource);
+        const redactedNext = redactModel(restored);
         const preflight = await this.preflight(candidate.path).finally(candidate.remove);
         return {
             valid: true, revision: digest(currentSource), normalizedModel: redactedNext.model,
-            diff: exactDiff(serialize(redactedCurrent.model), serialize(redactedNext.model)),
+            diff: sourceDiff(currentSource, nextSource),
             redactions: redactedNext.paths,
             impact: restartImpact(current, restored), preflight,
         };
@@ -49,13 +50,12 @@ export class FleetConfigService {
             this.assertRevision(baseRevision, currentSource);
             const current = parseFleetDocument(this.path, currentSource, 'strict').value;
             const restored = restoreRedactions(assertModel(model), current);
-            const nextSource = serialize(restored);
+            const nextSource = render(currentSource, restored);
             const candidate = this.validateCandidate(nextSource);
             const preflight = await this.preflight(candidate.path).finally(candidate.remove);
             // The lock coordinates trusted web/agent writers. An operator's editor does
             // not take it, so re-check immediately before replacement as well.
             this.assertRevision(baseRevision, this.readSource());
-            const redactedCurrent = redactModel(current);
             const redactedNext = redactModel(restored);
             let backup;
             if (existsSync(this.path)) {
@@ -67,7 +67,7 @@ export class FleetConfigService {
             return {
                 saved: true, valid: true, revision: digest(currentSource), newRevision: digest(nextSource),
                 normalizedModel: redactedNext.model,
-                diff: exactDiff(serialize(redactedCurrent.model), serialize(redactedNext.model)),
+                diff: sourceDiff(currentSource, nextSource),
                 redactions: redactedNext.paths, impact: restartImpact(current, restored), preflight,
                 backup,
             };
@@ -110,8 +110,17 @@ function assertModel(value) {
         throw new FleetError('invalid_request', 'model must be a JSON object');
     return structuredClone(value);
 }
-function serialize(model) {
-    return stringify(model, { lineWidth: 0, sortMapEntries: false });
+/**
+ * Apply the edited model onto the user's own document rather than re-serializing
+ * it, so comments, key order and formatting outside the edit survive the save.
+ */
+function render(currentSource, model) {
+    try {
+        return renderModelOntoSource(currentSource, model);
+    }
+    catch (error) {
+        throw new FleetError('invalid_request', error.message);
+    }
 }
 function digest(source) {
     return createHash('sha256').update(source).digest('hex');
@@ -173,12 +182,39 @@ function restoreRedactions(next, current) {
         }
     return next;
 }
-function exactDiff(before, after) {
-    if (before === after)
+/**
+ * Unified-style diff of the real file text with env secrets masked. Common
+ * leading/trailing lines are trimmed, so a surgical edit reviews as a small
+ * hunk instead of the whole configuration twice.
+ */
+function sourceDiff(beforeSource, afterSource) {
+    const before = splitLines(redactSourceSecrets(beforeSource, REDACTED_ENV_VALUE));
+    const after = splitLines(redactSourceSecrets(afterSource, REDACTED_ENV_VALUE));
+    let head = 0;
+    while (head < before.length && head < after.length && before[head] === after[head])
+        head += 1;
+    let tail = 0;
+    while (tail < before.length - head && tail < after.length - head
+        && before[before.length - 1 - tail] === after[after.length - 1 - tail])
+        tail += 1;
+    if (head === before.length && head === after.length)
         return '';
-    return ['--- fleet.yaml (current)', '+++ fleet.yaml (proposed)',
-        ...before.trimEnd().split('\n').map(line => `-${line}`),
-        ...after.trimEnd().split('\n').map(line => `+${line}`), ''].join('\n');
+    const start = Math.max(0, head - DIFF_CONTEXT_LINES);
+    const trailing = Math.min(DIFF_CONTEXT_LINES, tail);
+    const beforeSpan = before.length - tail + trailing - start;
+    const afterSpan = after.length - tail + trailing - start;
+    return [
+        '--- fleet.yaml (current)', '+++ fleet.yaml (proposed)',
+        `@@ -${start + 1},${beforeSpan} +${start + 1},${afterSpan} @@`,
+        ...before.slice(start, head).map(line => ` ${line}`),
+        ...before.slice(head, before.length - tail).map(line => `-${line}`),
+        ...after.slice(head, after.length - tail).map(line => `+${line}`),
+        ...before.slice(before.length - tail, before.length - tail + trailing).map(line => ` ${line}`),
+        '',
+    ].join('\n');
+}
+function splitLines(source) {
+    return source.replace(/\n$/, '').split('\n');
 }
 function objectKeys(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? Object.keys(value) : [];

package/dist/web/runtime.js

@@ -19,7 +19,9 @@ import { AuditSink } from './audit.js';
 import { FleetEventBus } from './events.js';
 import { buildWebServer } from './server.js';
 import { FleetConfigService } from './fleet-config-service.js';
-import { deriveTopology } from './topology.js';
+import { mergeTopology } from './topology-model.js';
+import { TopologyDraftStore } from './topology-draft-store.js';
+import { TopologyPromoteService } from './topology-promote.js';
 import { doctor } from '../doctor.js';
 import { TerminalBridgeManager } from './terminal/bridge.js';
 import { acquireWebServerLock } from './lock.js';
@@ -148,11 +150,16 @@ export async function startWebConsole(options) {
         configPath: options.configPath,
         preflight: path => doctor({ configPath: path, yamlMode: 'strict' }),
     });
+    const topologyDrafts = new TopologyDraftStore({ dir: webDir });
+    const readTopology = async () => mergeTopology(loadConfig(options.configPath), await query.list(), topologyDrafts.read());
+    const topologyPromote = new TopologyPromoteService({
+        drafts: topologyDrafts, configuration, topology: readTopology,
+    });
     let server;
     try {
         server = await buildWebServer({
             query, repository, logs, commands, creation, removal, audit, events, watchdogs, configuration,
-            topology: async () => deriveTopology(loadConfig(options.configPath), await query.list()),
+            topology: readTopology, topologyDrafts, topologyPromote,
             terminalUpgrade: terminalAvailable
                 ? async (socket, _request, roleId, _ticket, hello) => terminals.connect(socket, roleId, hello)
                 : undefined,

package/dist/web/server.d.ts

@@ -11,7 +11,9 @@ import { AuditSink } from './audit.js';
 import { WebAuth } from './auth.js';
 import { FleetEventBus } from './events.js';
 import type { FleetConfigService } from './fleet-config-service.js';
-import type { TopologySnapshot } from './topology.js';
+import type { MergedTopology } from './topology-model.js';
+import type { TopologyDraftStore } from './topology-draft-store.js';
+import type { TopologyPromoteService } from './topology-promote.js';
 import type { RoleRemovalService } from '../application/role-removal-service.js';
 export interface WebServices {
     query: FleetQueryService;
@@ -24,7 +26,9 @@ export interface WebServices {
     events?: FleetEventBus;
     watchdogs?: WatchdogQueryService;
     configuration?: FleetConfigService;
-    topology?: () => Promise<TopologySnapshot>;
+    topology?: () => Promise<MergedTopology>;
+    topologyDrafts?: TopologyDraftStore;
+    topologyPromote?: TopologyPromoteService;
     removal?: RoleRemovalService;
     terminalUpgrade?: (socket: WebSocket, request: FastifyRequest, roleId: string, ticket: string, hello: Record<string, unknown>) => Promise<void>;
 }

package/dist/web/server.js

@@ -159,6 +159,46 @@ export async function buildWebServer(services, boundary, options = {}) {
             throw new FleetError('capability_unavailable', 'fleet topology is unavailable');
         return services.topology();
     });
+    const drafts = () => {
+        if (!services.topologyDrafts)
+            throw new FleetError('capability_unavailable', 'topology sketching is unavailable');
+        return services.topologyDrafts;
+    };
+    app.get('/api/v1/topology/draft', async (request) => {
+        auth.authenticate(request);
+        return drafts().read();
+    });
+    app.put('/api/v1/topology/draft', async (request) => {
+        const session = auth.authenticate(request, true);
+        const body = request.body;
+        const result = await drafts().write(String(body?.revision ?? ''), body?.draft);
+        events.publish('topology.draft.changed', { revision: result.revision });
+        await audit.record({
+            requestId: request.id, browser: session.id, action: 'topology.draft.save', result: 'succeeded',
+        });
+        return result;
+    });
+    const promotion = () => {
+        if (!services.topologyPromote)
+            throw new FleetError('capability_unavailable', 'adding sketches to the fleet is unavailable');
+        return services.topologyPromote;
+    };
+    app.post('/api/v1/topology/promote/preview', async (request) => {
+        auth.authenticate(request, true);
+        return promotion().preview(promoteRequest(request.body));
+    });
+    // Writes configuration only. Nothing here starts a process: `Launch` is a
+    // separate, explicit action, so adding to the fleet can never launch by surprise.
+    app.post('/api/v1/topology/promote', async (request) => {
+        const session = auth.authenticate(request, true);
+        const result = await promotion().promote(promoteRequest(request.body));
+        events.publish('configuration.changed', { revision: result.newRevision });
+        events.publish('topology.draft.changed', { revision: result.draftRevision });
+        await audit.record({
+            requestId: request.id, browser: session.id, action: 'topology.promote', result: 'succeeded',
+        });
+        return result;
+    });
     app.get('/api/v1/roles/:id', async (request) => {
         auth.authenticate(request);
         return services.query.detail(request.params.id);
@@ -454,6 +494,16 @@ function clearAuthCookies(reply) {
         'ofs_device=; HttpOnly; SameSite=Strict; Path=/api; Max-Age=0',
     ]);
 }
+function promoteRequest(body) {
+    const value = (body ?? {});
+    if (!Array.isArray(value.ids) || value.ids.some(id => typeof id !== 'string'))
+        throw new FleetError('invalid_request', 'ids must be a list of sketch ids');
+    return {
+        ids: value.ids,
+        configRevision: String(value.configRevision ?? ''),
+        draftRevision: typeof value.draftRevision === 'string' ? value.draftRevision : undefined,
+    };
+}
 function cryptoRandomId() { return randomBytes(12).toString('hex'); }
 function escapeHtml(value) {
     return value.replace(/[&<>"']/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[char]));

package/dist/web/topology-draft-store.d.ts

@@ -0,0 +1,80 @@
+import type { Problem } from '../application/types.js';
+import type { TopologyNodeKind } from './topology.js';
+/**
+ * Durable storage for *sketches*: nodes the owner has drawn but not yet added to
+ * the fleet, and where every node sits on the canvas.
+ *
+ * This file is deliberately invisible to `loadConfig`. An incomplete agent in
+ * `roles:` would be started by `ours-fleet up`, and an incomplete watchdog or
+ * loop is a hard `ConfigError` that makes the entire fleet unloadable — so a
+ * draft cannot live in fleet.yaml at all. Being outside the config also makes
+ * "visible but not launchable" true at the daemon level rather than in the UI.
+ *
+ * Nothing here is authoritative and nothing here is a secret: the schema admits
+ * only presentational coordinates and a small allowlist of plain draft fields,
+ * so `env:`/`vars:` values can never reach it.
+ */
+export declare const TOPOLOGY_DRAFT_VERSION = 1;
+export type DraftFieldValue = string | number | boolean;
+export interface DraftPosition {
+    x: number;
+    y: number;
+}
+export interface DraftNode {
+    id: string;
+    kind: TopologyNodeKind;
+    fields: Record<string, DraftFieldValue>;
+}
+export interface DraftEdge {
+    kind: 'oversees' | 'watches' | 'targets';
+    from: string;
+    to: string;
+}
+export interface DraftTutorial {
+    step: number;
+    dismissed: boolean;
+}
+export interface TopologyDraft {
+    version: number;
+    positions: Record<string, DraftPosition>;
+    drafts: {
+        nodes: DraftNode[];
+        edges: DraftEdge[];
+    };
+    tutorial: DraftTutorial;
+}
+export interface TopologyDraftRead {
+    draft: TopologyDraft;
+    revision: string;
+    /** Set when the stored file was unusable and an empty draft is being served. */
+    problem?: Problem;
+    /** False when the file was written by a newer console and must not be clobbered. */
+    writable: boolean;
+}
+export interface TopologyDraftWriteResult {
+    draft: TopologyDraft;
+    revision: string;
+}
+export declare const emptyDraft: () => TopologyDraft;
+export interface TopologyDraftStoreOptions {
+    dir?: string;
+}
+export declare class TopologyDraftStore {
+    readonly path: string;
+    private readonly dir;
+    constructor(options?: TopologyDraftStoreOptions);
+    /**
+     * Never throws. A missing, unreadable, oversized, malformed or future-version
+     * sidecar degrades to an empty draft plus a `problem` the console can show as
+     * a banner — losing sketches is bad, but blocking the console on them is worse.
+     */
+    read(): TopologyDraftRead;
+    /**
+     * Revision-guarded, atomic, 0600. Strict on the way in: an out-of-bounds
+     * coordinate, an unknown field or an unparseable id is refused with a reason
+     * rather than silently dropped, because the caller is the console's own
+     * editor and a silent drop would look like data loss.
+     */
+    write(baseRevision: string, next: unknown): Promise<TopologyDraftWriteResult>;
+    private readRaw;
+}

package/dist/web/topology-draft-store.js

@@ -0,0 +1,337 @@
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { replaceFileAtomically, withFileLock } from '../atomic-file.js';
+import { stateRoot } from '../paths.js';
+import { FleetError } from '../application/errors.js';
+/**
+ * Durable storage for *sketches*: nodes the owner has drawn but not yet added to
+ * the fleet, and where every node sits on the canvas.
+ *
+ * This file is deliberately invisible to `loadConfig`. An incomplete agent in
+ * `roles:` would be started by `ours-fleet up`, and an incomplete watchdog or
+ * loop is a hard `ConfigError` that makes the entire fleet unloadable — so a
+ * draft cannot live in fleet.yaml at all. Being outside the config also makes
+ * "visible but not launchable" true at the daemon level rather than in the UI.
+ *
+ * Nothing here is authoritative and nothing here is a secret: the schema admits
+ * only presentational coordinates and a small allowlist of plain draft fields,
+ * so `env:`/`vars:` values can never reach it.
+ */
+export const TOPOLOGY_DRAFT_VERSION = 1;
+const MAX_FILE_BYTES = 256 * 1024;
+const MAX_NODES = 500;
+const MAX_EDGES = 2000;
+const MAX_POSITIONS = 2000;
+const MAX_COORDINATE = 100_000;
+const MAX_FIELDS_PER_NODE = 32;
+const MAX_FIELD_LENGTH = 16 * 1024;
+const MAX_TUTORIAL_STEP = 32;
+const NODE_ID_RE = /^(agent|watchdog|loop):[A-Za-z0-9_-]{1,64}$/;
+const NODE_KINDS = ['agent', 'watchdog', 'loop'];
+/** `spawned` is runtime provenance, never a drawn edge. */
+const EDGE_KINDS = ['oversees', 'watches', 'targets'];
+/**
+ * Draft fields the console may persist. An allowlist rather than a denylist so
+ * secret-bearing keys (`env`, `vars`, `harness_options`) are excluded by
+ * construction; extend it deliberately when the inspector grows a field.
+ *
+ * Every entry is a plain scalar that promotion can write straight into a role,
+ * watchdog or loop mapping. Nested settings (`permissions:`, `harness_options:`,
+ * `isolation:`) are deliberately absent: they are edited through the reviewed
+ * configuration editor once the node is real, not sketched.
+ */
+const FIELD_KEYS = [
+    'mission', 'bio', 'persona', 'coordinator', 'prompt',
+    'interval', 'initial_delay', 'jitter', 'enabled',
+    'harness', 'session', 'model', 'identity', 'cwd',
+];
+export const emptyDraft = () => ({
+    version: TOPOLOGY_DRAFT_VERSION,
+    positions: {},
+    drafts: { nodes: [], edges: [] },
+    tutorial: { step: 0, dismissed: false },
+});
+export class TopologyDraftStore {
+    path;
+    dir;
+    constructor(options = {}) {
+        this.dir = options.dir ?? join(stateRoot(), 'web');
+        this.path = join(this.dir, 'topology.json');
+    }
+    /**
+     * Never throws. A missing, unreadable, oversized, malformed or future-version
+     * sidecar degrades to an empty draft plus a `problem` the console can show as
+     * a banner — losing sketches is bad, but blocking the console on them is worse.
+     */
+    read() {
+        const raw = this.readRaw();
+        const revision = digest(raw.text);
+        if (raw.problem)
+            return { draft: emptyDraft(), revision, problem: raw.problem, writable: true };
+        if (raw.text === '')
+            return { draft: emptyDraft(), revision, writable: true };
+        let parsed;
+        try {
+            parsed = JSON.parse(raw.text);
+        }
+        catch (error) {
+            return {
+                draft: emptyDraft(), revision, writable: true,
+                problem: problem('draft_corrupt', `topology drafts are unreadable and were ignored: ${error.message}`),
+            };
+        }
+        const version = parsed?.version;
+        if (typeof version === 'number' && version > TOPOLOGY_DRAFT_VERSION)
+            return {
+                draft: emptyDraft(), revision, writable: false,
+                problem: problem('draft_version_unsupported', `topology drafts were written by a newer console (version ${version}); update ours-fleet to edit them`),
+            };
+        return { draft: coerceDraft(parsed), revision, writable: true };
+    }
+    /**
+     * Revision-guarded, atomic, 0600. Strict on the way in: an out-of-bounds
+     * coordinate, an unknown field or an unparseable id is refused with a reason
+     * rather than silently dropped, because the caller is the console's own
+     * editor and a silent drop would look like data loss.
+     */
+    async write(baseRevision, next) {
+        const draft = validateDraft(next);
+        const text = `${JSON.stringify(draft, null, 2)}\n`;
+        if (Buffer.byteLength(text) > MAX_FILE_BYTES)
+            throw new FleetError('invalid_request', `topology drafts exceed ${MAX_FILE_BYTES} bytes`);
+        return withFileLock(`${this.path}.lock`, () => {
+            const current = this.read();
+            if (!current.writable)
+                throw new FleetError('incompatible_version', current.problem?.detail ?? 'topology drafts are not writable');
+            if (!baseRevision || baseRevision !== current.revision)
+                throw new FleetError('stale_state', 'topology drafts changed since they were opened; reload before saving');
+            mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+            chmodSync(this.dir, 0o700);
+            replaceFileAtomically(this.path, text, 0o600);
+            return { draft, revision: digest(text) };
+        });
+    }
+    readRaw() {
+        if (!existsSync(this.path))
+            return { text: '' };
+        try {
+            const stat = lstatSync(this.path);
+            if (!stat.isFile() || stat.isSymbolicLink())
+                return { text: '', problem: problem('draft_unreadable', 'topology drafts must be a regular non-symlink file') };
+            if (stat.size > MAX_FILE_BYTES)
+                return { text: '', problem: problem('draft_unreadable', `topology drafts exceed ${MAX_FILE_BYTES} bytes and were ignored`) };
+            const uid = process.getuid?.();
+            if (uid !== undefined && stat.uid !== uid)
+                return { text: '', problem: problem('draft_unreadable', 'topology drafts are not owned by the current user') };
+            return { text: readFileSync(this.path, 'utf8') };
+        }
+        catch (error) {
+            return { text: '', problem: problem('draft_unreadable', `topology drafts could not be read: ${error.message}`) };
+        }
+    }
+}
+const problem = (code, detail) => ({ code, severity: 'warning', detail, source: 'topology.json' });
+const digest = (text) => createHash('sha256').update(text).digest('hex');
+/* ------------------------------------------------------------------ *
+ * Lenient read coercion — drop what does not fit, keep the rest.
+ * ------------------------------------------------------------------ */
+function coerceDraft(value) {
+    const draft = emptyDraft();
+    if (!isRecord(value))
+        return draft;
+    const positions = value.positions;
+    if (isRecord(positions))
+        for (const [id, raw] of Object.entries(positions).slice(0, MAX_POSITIONS)) {
+            if (!NODE_ID_RE.test(id) || !isRecord(raw))
+                continue;
+            if (!isCoordinate(raw.x) || !isCoordinate(raw.y))
+                continue;
+            draft.positions[id] = { x: raw.x, y: raw.y };
+        }
+    const drafts = isRecord(value.drafts) ? value.drafts : {};
+    const seenNodes = new Set();
+    if (Array.isArray(drafts.nodes))
+        for (const raw of drafts.nodes) {
+            if (draft.drafts.nodes.length >= MAX_NODES)
+                break;
+            const node = coerceNode(raw);
+            if (!node || seenNodes.has(node.id))
+                continue;
+            seenNodes.add(node.id);
+            draft.drafts.nodes.push(node);
+        }
+    const seenEdges = new Set();
+    if (Array.isArray(drafts.edges))
+        for (const raw of drafts.edges) {
+            if (draft.drafts.edges.length >= MAX_EDGES)
+                break;
+            const edge = coerceEdge(raw);
+            if (!edge)
+                continue;
+            const key = `${edge.kind}:${edge.from}:${edge.to}`;
+            if (seenEdges.has(key))
+                continue;
+            seenEdges.add(key);
+            draft.drafts.edges.push(edge);
+        }
+    if (isRecord(value.tutorial)) {
+        const { step, dismissed } = value.tutorial;
+        if (typeof step === 'number' && Number.isInteger(step) && step >= 0 && step <= MAX_TUTORIAL_STEP)
+            draft.tutorial.step = step;
+        draft.tutorial.dismissed = dismissed === true;
+    }
+    return draft;
+}
+function coerceNode(value) {
+    if (!isRecord(value))
+        return undefined;
+    const { id, kind } = value;
+    if (typeof id !== 'string' || !NODE_ID_RE.test(id))
+        return undefined;
+    if (typeof kind !== 'string' || !NODE_KINDS.includes(kind))
+        return undefined;
+    if (!id.startsWith(`${kind}:`))
+        return undefined;
+    const fields = {};
+    if (isRecord(value.fields))
+        for (const [key, raw] of Object.entries(value.fields)) {
+            if (Object.keys(fields).length >= MAX_FIELDS_PER_NODE)
+                break;
+            if (!FIELD_KEYS.includes(key) || !isFieldValue(raw))
+                continue;
+            fields[key] = raw;
+        }
+    return { id, kind: kind, fields };
+}
+function coerceEdge(value) {
+    if (!isRecord(value))
+        return undefined;
+    const { kind, from, to } = value;
+    if (typeof kind !== 'string' || !EDGE_KINDS.includes(kind))
+        return undefined;
+    if (typeof from !== 'string' || !NODE_ID_RE.test(from))
+        return undefined;
+    if (typeof to !== 'string' || !NODE_ID_RE.test(to) || from === to)
+        return undefined;
+    return { kind: kind, from, to };
+}
+/* ------------------------------------------------------------------ *
+ * Strict write validation — refuse with a reason.
+ * ------------------------------------------------------------------ */
+function validateDraft(value) {
+    if (!isRecord(value))
+        throw invalid('topology draft must be a JSON object');
+    const version = value.version ?? TOPOLOGY_DRAFT_VERSION;
+    if (version !== TOPOLOGY_DRAFT_VERSION)
+        throw invalid(`unsupported topology draft version ${String(version)}`);
+    const draft = emptyDraft();
+    const positions = value.positions ?? {};
+    if (!isRecord(positions))
+        throw invalid('positions must be an object');
+    const positionIds = Object.keys(positions);
+    if (positionIds.length > MAX_POSITIONS)
+        throw invalid(`at most ${MAX_POSITIONS} node positions are supported`);
+    for (const id of positionIds) {
+        if (!NODE_ID_RE.test(id))
+            throw invalid(`invalid node id in positions: ${id}`);
+        const raw = positions[id];
+        if (!isRecord(raw) || !isCoordinate(raw.x) || !isCoordinate(raw.y))
+            throw invalid(`position for ${id} must be finite x/y within ±${MAX_COORDINATE}`);
+        draft.positions[id] = { x: raw.x, y: raw.y };
+    }
+    const drafts = value.drafts ?? {};
+    if (!isRecord(drafts))
+        throw invalid('drafts must be an object');
+    const nodes = drafts.nodes ?? [];
+    const edges = drafts.edges ?? [];
+    if (!Array.isArray(nodes))
+        throw invalid('drafts.nodes must be an array');
+    if (!Array.isArray(edges))
+        throw invalid('drafts.edges must be an array');
+    if (nodes.length > MAX_NODES)
+        throw invalid(`at most ${MAX_NODES} draft nodes are supported`);
+    if (edges.length > MAX_EDGES)
+        throw invalid(`at most ${MAX_EDGES} draft edges are supported`);
+    const seenNodes = new Set();
+    for (const raw of nodes) {
+        const node = validateNode(raw);
+        if (seenNodes.has(node.id))
+            throw invalid(`duplicate draft node ${node.id}`);
+        seenNodes.add(node.id);
+        draft.drafts.nodes.push(node);
+    }
+    const seenEdges = new Set();
+    for (const raw of edges) {
+        const edge = validateEdge(raw);
+        const key = `${edge.kind}:${edge.from}:${edge.to}`;
+        if (seenEdges.has(key))
+            continue;
+        seenEdges.add(key);
+        draft.drafts.edges.push(edge);
+    }
+    const tutorial = value.tutorial ?? {};
+    if (!isRecord(tutorial))
+        throw invalid('tutorial must be an object');
+    const step = tutorial.step ?? 0;
+    if (typeof step !== 'number' || !Number.isInteger(step) || step < 0 || step > MAX_TUTORIAL_STEP)
+        throw invalid(`tutorial.step must be an integer between 0 and ${MAX_TUTORIAL_STEP}`);
+    draft.tutorial = { step, dismissed: tutorial.dismissed === true };
+    return draft;
+}
+function validateNode(value) {
+    if (!isRecord(value))
+        throw invalid('each draft node must be an object');
+    const { id, kind } = value;
+    if (typeof id !== 'string' || !NODE_ID_RE.test(id))
+        throw invalid(`draft node id must look like agent:<Name>: ${JSON.stringify(id)}`);
+    if (typeof kind !== 'string' || !NODE_KINDS.includes(kind))
+        throw invalid(`draft node ${id} has an unknown kind ${JSON.stringify(kind)}`);
+    if (!id.startsWith(`${kind}:`))
+        throw invalid(`draft node ${id} does not match kind ${kind}`);
+    const rawFields = value.fields ?? {};
+    if (!isRecord(rawFields))
+        throw invalid(`draft node ${id} fields must be an object`);
+    const keys = Object.keys(rawFields);
+    if (keys.length > MAX_FIELDS_PER_NODE)
+        throw invalid(`draft node ${id} has more than ${MAX_FIELDS_PER_NODE} fields`);
+    const fields = {};
+    for (const key of keys) {
+        if (!FIELD_KEYS.includes(key))
+            throw invalid(`draft node ${id} may not store field ${JSON.stringify(key)}`);
+        const raw = rawFields[key];
+        if (!isFieldValue(raw))
+            throw invalid(`draft node ${id} field ${key} must be a string under ${MAX_FIELD_LENGTH} characters, a finite number, or a boolean`);
+        fields[key] = raw;
+    }
+    return { id, kind: kind, fields };
+}
+function validateEdge(value) {
+    if (!isRecord(value))
+        throw invalid('each draft edge must be an object');
+    const { kind, from, to } = value;
+    if (typeof kind !== 'string' || !EDGE_KINDS.includes(kind))
+        throw invalid(`draft edge has an unknown kind ${JSON.stringify(kind)}`);
+    if (typeof from !== 'string' || !NODE_ID_RE.test(from))
+        throw invalid(`invalid draft edge source ${JSON.stringify(from)}`);
+    if (typeof to !== 'string' || !NODE_ID_RE.test(to))
+        throw invalid(`invalid draft edge target ${JSON.stringify(to)}`);
+    if (from === to)
+        throw invalid(`draft edge ${from} cannot point at itself`);
+    return { kind: kind, from, to };
+}
+const invalid = (message) => new FleetError('invalid_request', message);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isCoordinate(value) {
+    return typeof value === 'number' && Number.isFinite(value)
+        && value >= -MAX_COORDINATE && value <= MAX_COORDINATE;
+}
+function isFieldValue(value) {
+    if (typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    return typeof value === 'string' && value.length <= MAX_FIELD_LENGTH;
+}