@dotdrelle/wiki-manager 0.9.3 → 0.10.4

package/README.md

@@ -527,13 +527,17 @@ The shared `docker-compose.yml` starts one workspace stack:
 
 | Service | Role | Port variable |
 | --- | --- | --- |
-| `serve` | Wiki web UI and browser chat | `WIKI_SERVE_PORT` |
-| `mcp-http` | llm-wiki MCP endpoint | `WIKI_MCP_PORT` |
-| `production-mcp` | Production job MCP endpoint | `PRODUCTION_MCP_PORT` |
+| `serve` | Wiki web UI and browser chat, container port `3000` | `WIKI_SERVE_PORT` |
+| `mcp-http` | llm-wiki MCP endpoint, container port `3333` | `WIKI_MCP_PORT` |
+| `production-mcp` | Production job MCP endpoint, container port `8080` | `PRODUCTION_MCP_PORT` |
 
 Use `wiki-workspace` whenever possible so Compose receives the right project
 name, env file, ports, and volume mounts.
 
+Runtime split: the host manager/runtime uses Node.js 22+ for `node:sqlite`; the
+interactive OpenTUI shell uses Bun 1.2+; workspace Docker services run from the
+published images and do not depend on host `node_modules`.
+
 ```bash
 wiki-workspace list
 wiki-workspace agents up
@@ -799,12 +803,23 @@ Files matching `docker-compose*.local.yml` are ignored by Git.
 ```bash
 pnpm install
 pnpm start
+pnpm run check-versions
 pnpm run check
 ```
 
-When bumping the package version, update both `package.json` and the Streamable
-HTTP MCP `clientInfo.version` in `src/core/mcp.js`. They are kept explicit so
-remote MCP server logs show the manager build that initiated the handshake.
+When bumping a coordinated release, keep `llm-wiki`, `llm-wiki-manager`, Python
+agent `_AGENT_VERSION` values, MCP `clientInfo.version` / server versions, Git
+tags, and Docker image tags aligned. Run:
+
+```bash
+pnpm run check-versions
+CHECK_GIT_TAG=1 pnpm run check-versions          # pre-release tag check
+CHECK_DOCKER_IMAGES=1 pnpm run check-versions    # after local image build
+```
+
+`build-and-push.sh` synchronizes the coordinated version, runs
+`pnpm run check-versions`, builds images tagged with that version, and can push
+the matching `latest` tags.
 
 `pnpm run check` verifies the CLI version, help output, and limited `--once` mode.
 For headless changes, also test a controlled error path, for example:

package/agents.docker-compose.yml

@@ -21,6 +21,7 @@
 #   MAILERSEND_API_KEY
 #   MAILERSEND_FROM_EMAIL
 #   MAILERSEND_FROM_NAME
+#   MAILERSEND_CA_CERT    — optional CA bundle path inside the container
 #
 # Set these variables in a .env file at the directory where you run wiki-workspace,
 # or export them in your shell before running wiki-workspace agents up.
@@ -90,7 +91,11 @@ services:
       - MAILERSEND_FROM_NAME=${MAILERSEND_FROM_NAME:-Mailer Agent}
       - MAILERSEND_USER_AGENT=${MAILERSEND_USER_AGENT:-curl/8.7.1}
       - MAILERSEND_VERIFY_SSL=${MAILERSEND_VERIFY_SSL:-true}
+      - MAILERSEND_CA_CERT=${MAILERSEND_CA_CERT:-}
       - MAILER_REQUIRE_CONFIRMATION=${MAILER_REQUIRE_CONFIRMATION:-true}
       - MAILER_DRY_RUN=${MAILER_DRY_RUN:-false}
       - MCP_AUTH_TOKEN=${MAILER_MCP_AUTH_TOKEN:-}
+    volumes:
+      # Optional: mount a CA bundle and set MAILERSEND_CA_CERT to its container path.
+      #- ${AGENTS_DATA_DIR:-./.agents-data}/certs:/certs:ro
     restart: unless-stopped

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdrelle/wiki-manager",
-  "version": "0.9.3",
+  "version": "0.10.4",
   "description": "Agentic shell and orchestration cockpit for llm-wiki workspaces.",
   "license": "PolyForm-Noncommercial-1.0.0",
   "author": "dotrelle",
@@ -11,7 +11,10 @@
   },
   "scripts": {
     "start": "bun ./bin/wiki-manager.js",
-    "test": "node --test src/agent/graph.test.js src/core/activity.test.js src/core/agentEvents.test.js src/core/agentLoop.test.js src/core/plan.test.js src/core/mcp.test.js src/core/documentIntake.test.js src/core/dockerCompose.test.js src/core/wikiWorkspace.test.js src/core/wikirc.test.js src/core/modelFetch.test.js src/core/startupCheck.test.js src/core/queueStore.test.js src/commands/slash.test.js src/shell/repl.test.js src/runtime/store.test.js src/runtime/server.test.js src/runtime/supervisor.test.js src/runtime/runner.test.js src/runtime/auth.test.js",
+    "test": "node --test src/agent/graph.test.js src/contracts/schemas.test.js src/core/activity.test.js src/core/agentEvents.test.js src/core/workflow.test.js src/core/planPatch.test.js src/core/agentLoop.test.js src/core/plan.test.js src/core/mcp.test.js src/core/documentIntake.test.js src/core/dockerCompose.test.js src/core/wikiWorkspace.test.js src/core/wikirc.test.js src/core/modelFetch.test.js src/core/startupCheck.test.js src/core/queueStore.test.js src/commands/slash.test.js src/shell/repl.test.js src/runtime/store.test.js src/runtime/server.test.js src/runtime/supervisor.test.js src/runtime/runner.test.js src/runtime/auth.test.js",
+    "check-versions": "node scripts/check-versions.js",
+    "prepack": "node scripts/check-versions.js",
+    "prepublishOnly": "node scripts/check-versions.js",
     "check": "bun ./bin/wiki-manager.js --version && bun ./bin/wiki-manager.js --help && bun ./bin/wiki-manager.js --once \"verifie le mode agent\""
   },
   "engines": {

package/src/agent/graph.js

@@ -66,8 +66,26 @@ const WIKI_PLAN_SET_TOOL = {
       properties: {
         steps: {
           type: 'array',
-          items: { type: 'string' },
-          description: 'Ordered step descriptions, e.g. ["CME export", "Production ingest", "Build", "Polish", "Email report"].',
+          items: {
+            anyOf: [
+              { type: 'string' },
+              {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                  id: { type: 'string' },
+                  description: { type: 'string' },
+                  status: { type: 'string', enum: ['pending', 'queued', 'running', 'waiting', 'pending_approval', 'done', 'failed', 'cancelled', 'stalled', 'added_during_run'] },
+                  dependsOn: { type: 'array', items: { type: 'string' } },
+                  executor: { type: ['string', 'null'] },
+                  executorQuery: { type: ['object', 'null'], additionalProperties: true },
+                  outputRefs: { type: 'array', items: { type: 'string' } },
+                },
+                required: ['description'],
+              },
+            ],
+          },
+          description: 'Ordered steps. Backward-compatible strings are accepted; structured steps may include id, dependsOn, executor, executorQuery, outputRefs.',
         },
       },
       required: ['steps'],
@@ -344,11 +362,7 @@ function handleWikiTool(session, tool, args) {
   if (tool === 'plan_set') {
     const steps = Array.isArray(args.steps) ? args.steps : [];
     emitAgentEvent(session, 'plan_set', 'tool', {
-      steps: steps.map((description, i) => ({
-        step: i + 1,
-        description: String(description),
-        status: 'pending',
-      })),
+      steps: steps.map((raw, i) => normalizeDeclaredPlanStep(raw, i, session)),
     });
     return `Plan registered: ${steps.length} step${steps.length !== 1 ? 's' : ''}.`;
   }
@@ -364,6 +378,51 @@ function handleWikiTool(session, tool, args) {
   return `Unknown wiki tool: ${tool}`;
 }
 
+function normalizeDeclaredPlanStep(raw, index, session) {
+  const item = raw && typeof raw === 'object' && !Array.isArray(raw)
+    ? raw
+    : { description: String(raw) };
+  const description = String(item.description ?? item.label ?? item.name ?? item.id ?? `Step ${index + 1}`);
+  return {
+    step: Number(item.step ?? index + 1),
+    id: item.id ? String(item.id) : slugStepId(description, index),
+    description,
+    status: item.status ?? 'pending',
+    dependsOn: Array.isArray(item.dependsOn) ? item.dependsOn.map(String) : [],
+    executor: item.executor ?? selectExecutorForStep(description, session),
+    executorQuery: item.executorQuery ?? null,
+    outputRefs: Array.isArray(item.outputRefs) ? item.outputRefs.map(String) : [],
+  };
+}
+
+function slugStepId(description, index) {
+  const slug = String(description)
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48);
+  return slug || `task-${index + 1}`;
+}
+
+function selectExecutorForStep(description, session) {
+  const text = String(description ?? '').toLowerCase();
+  let fallback = null;
+  for (const [serverName, value] of Object.entries(session.mcp ?? {})) {
+    if (value.status !== 'connected') continue;
+    for (const tool of value.tools ?? []) {
+      const executor = `${serverName}.${tool.name}`;
+      fallback ??= executor;
+      const haystack = `${serverName} ${tool.name} ${tool.description ?? ''}`.toLowerCase();
+      if (text.split(/[^a-z0-9]+/).filter((token) => token.length >= 4).some((token) => haystack.includes(token))) {
+        return executor;
+      }
+    }
+  }
+  return fallback;
+}
+
 export function buildAgentSystemPrompt(state) {
   const workspace = state.session.workspace ?? 'no workspace selected';
   const wikirc = state.session.wikirc?.profile ?? 'no profile loaded';
@@ -401,8 +460,8 @@ export function buildAgentSystemPrompt(state) {
       '',
       'Task startup:',
       '  1. If the next MCP tool returns _activity.plan.steps, call that tool directly; the shell will create the visible plan from the returned activity.',
-      '  2. If the tool cannot declare its own plan, call wiki__plan_set(steps=["Step description", ...]) before executing the first step.',
-      '     Multi-tool example: wiki__plan_set(steps=["CME export", "Production pipeline", "Email report"])',
+      '  2. If the tool cannot declare its own plan, call wiki__plan_set before executing the first step. Prefer structured steps: {id, description, dependsOn, executor, executorQuery, outputRefs}; a legacy list of strings is still accepted.',
+      '     Multi-tool example: wiki__plan_set(steps=[{id:"cme-export",description:"CME export",dependsOn:[],executor:"cme.cme_export_run",outputRefs:["raw/untracked"]},{id:"production",description:"Production pipeline",dependsOn:["cme-export"],executor:"production.production_start_job",outputRefs:["deliverables"]}])',
       '  3. Immediately execute the first step using the appropriate MCP tool. Do not start step 2 in the same turn unless one async pipeline tool owns and declares the whole sequence.',
       '  For synchronous steps (result is immediate, no _activity polling), call wiki__plan_done(step=1) after confirming success.',
       '  For async MCP jobs (returns _activity with poll), the orchestrator tracks completion automatically.',

package/src/agent/graph.test.js

@@ -143,3 +143,67 @@ test('agent graph waits for tool-level approval configured on endpoint', async (
   }
 });
 
+test('agent graph accepts structured wiki plan steps and selects MCP executors', async () => {
+  let calls = 0;
+  const session = sessionBase({
+    mcp: {
+      cme: {
+        status: 'connected',
+        url: 'http://127.0.0.1:3001/mcp/',
+        tools: [{
+          name: 'cme_export_run',
+          description: 'Export CME pages',
+          inputSchema: { type: 'object', properties: {} },
+        }],
+      },
+      production: {
+        status: 'connected',
+        url: 'http://127.0.0.1:3000/mcp/',
+        tools: [{
+          name: 'production_start_job',
+          description: 'Start production job',
+          inputSchema: { type: 'object', properties: { type: { type: 'string' } } },
+        }],
+      },
+    },
+    llm: {
+      async completeWithTools() {
+        calls += 1;
+        if (calls === 1) {
+          return {
+            content: null,
+            message: { role: 'assistant', content: null },
+            tool_calls: [{
+              id: 'plan-call',
+              type: 'function',
+              function: {
+                name: 'wiki__plan_set',
+                arguments: JSON.stringify({
+                  steps: [
+                    { id: 'cme-export', description: 'Export CME pages', outputRefs: ['raw/untracked'] },
+                    { id: 'build', description: 'Run production build', dependsOn: ['cme-export'] },
+                  ],
+                }),
+              },
+            }],
+          };
+        }
+        return {
+          content: 'Plan ready.',
+          message: { role: 'assistant', content: 'Plan ready.' },
+          tool_calls: null,
+        };
+      },
+    },
+  });
+
+  const agent = createAgentGraph();
+  const result = await agent.invoke({ input: 'Plan export then build', session });
+
+  assert.equal(result.response, 'Plan ready.');
+  assert.deepEqual(session.headlessPlan.map((step) => step.id), ['cme-export', 'build']);
+  assert.equal(session.headlessPlan[0].executor, 'cme.cme_export_run');
+  assert.equal(session.headlessPlan[1].executor, 'production.production_start_job');
+  assert.deepEqual(session.headlessPlan[1].dependsOn, ['cme-export']);
+  assert.deepEqual(session.headlessPlan[0].outputRefs, ['raw/untracked']);
+});

package/src/cli/wiki-manager.js

@@ -163,7 +163,7 @@ async function runHeadlessAgenticLoop(agent, session, initialInput, log, { timeo
       console.log(response);
     },
     onPlanExtracted: ({ steps }) => {
-      log.push(`agentic-loop: plan extracted from text (${steps.length} steps, fallback)`);
+      log.push(`agentic-loop: plan extracted from text (${steps.length} steps, deprecated fallback)`);
     },
     onPlanAlreadySet: ({ steps }) => {
       log.push(`agentic-loop: plan set via tool (${steps.length} steps)`);

package/src/commands/slash.js

@@ -615,8 +615,8 @@ ${helpPair('/workspace list', 'Workspaces', '/new <n> [path]', 'New workspace')}
 ${helpPair('/use <workspace>', 'Use workspace', '/status', 'Session status')}
 ${helpPair('/config list', 'Config profiles', '/config use <n>', 'Use config')}
 ${helpPair('/config edit <n>', 'Edit config', '/workspace delete <n>', 'Delete workspace')}
-${helpPair('/services', 'Services', '/start [service|agents]', 'Start service(s)')}
-${helpPair('/stop [service|agents]', 'Stop service(s)', '/logs <service>', 'Service logs')}
+${helpPair('/services', 'Services', '/start [all|service|agents]', 'Start service(s)')}
+${helpPair('/stop [all|service|agents]', 'Stop service(s)', '/logs <service>', 'Service logs')}
 ${helpPair('/skills', 'List skills', '/skills show <n>', 'Show skill')}
 ${helpPair('/skills run <n>', 'Run skill guide', '/skills edit <n>', 'Edit skill')}
 ${helpPair('/mcp status', 'MCP status', '/mcp endpoints', 'MCP endpoints')}
@@ -810,6 +810,10 @@ export async function handleSlashCommand(line, context) {
       }
     }
     case 'start': {
+      // 'all' already resolves correctly through serviceAliases() (DEFAULT_SERVICE_ALIASES.all
+      // = COMPOSE_SERVICES, overridable via docker-compose.yml's service-aliases.all.targets) —
+      // do not remap it to undefined, that bypasses any custom "all" target list and always
+      // falls back to the hardcoded COMPOSE_SERVICES constant instead.
       const service = args[1];
       if (service === 'agents') return runAgentCommand(startAgents, 'start');
       try {

package/src/contracts/README.md

@@ -0,0 +1,16 @@
+# Runtime Contracts
+
+Versioned JSON Schema-like contracts live in `schemas.js`.
+
+Current schema version: `1`.
+
+Validated boundaries:
+
+- `_activity` after normalization in `core/activity.js`
+- `AgentRunEvent` creation and dispatch in `core/agentEvents.js`
+- structured plan and plan patch normalization
+- runtime `/run` and `/control` request payloads
+
+Validation is enabled when `WIKI_MANAGER_VALIDATE_CONTRACTS=1`, `CI=true`, or
+`NODE_ENV` is set to a non-production value. Schemas tolerate additional fields
+so agents can extend payloads without breaking older consumers.

package/src/contracts/schemas.js

@@ -0,0 +1,302 @@
+const STATUS_VALUES = [
+  'pending',
+  'queued',
+  'running',
+  'waiting',
+  'pending_approval',
+  'done',
+  'failed',
+  'cancelled',
+  'canceled',
+  'stalled',
+  'added_during_run',
+  'error',
+  'complete',
+  'completed',
+  'success',
+];
+
+const nullableString = { type: ['string', 'null'] };
+const nullableObject = { type: ['object', 'null'], additionalProperties: true };
+const outputReferenceSchema = {
+  $id: 'https://dotdrelle.dev/wiki-manager/contracts/output-reference/v1',
+  title: 'OutputReference',
+  schemaVersion: '1',
+  oneOf: [
+    { type: 'string' },
+    {
+      type: 'object',
+      required: ['type', 'ref'],
+      additionalProperties: true,
+      properties: {
+        type: { type: 'string' },
+        ref: { type: 'string' },
+        label: nullableString,
+        workspace: nullableString,
+      },
+    },
+  ],
+};
+
+const planStepSchema = {
+  type: 'object',
+  required: ['description', 'status', 'dependsOn', 'outputRefs'],
+  additionalProperties: true,
+  properties: {
+    step: { type: 'number' },
+    id: nullableString,
+    description: { type: 'string' },
+    status: { type: 'string' },
+    dependsOn: { type: 'array', items: { type: 'string' } },
+    executor: nullableString,
+    executorQuery: nullableObject,
+    outputRefs: { type: 'array', items: outputReferenceSchema },
+  },
+};
+
+const patchTaskSchema = {
+  type: 'object',
+  required: ['id', 'description'],
+  additionalProperties: true,
+  properties: {
+    id: { type: 'string' },
+    description: { type: 'string' },
+    status: { type: 'string' },
+    dependsOn: { type: 'array', items: { type: 'string' } },
+    executor: nullableString,
+    executorQuery: nullableObject,
+    outputRefs: { type: 'array', items: outputReferenceSchema },
+  },
+};
+
+export const contractSchemas = {
+  activity: {
+    $id: 'https://dotdrelle.dev/wiki-manager/contracts/activity/v1',
+    title: '_activity',
+    schemaVersion: '1',
+    type: 'object',
+    required: ['schemaVersion', 'id', 'source', 'kind', 'label', 'status', 'progress', 'poll', 'outputRefs'],
+    additionalProperties: true,
+    properties: {
+      schemaVersion: { const: '1' },
+      id: { type: 'string' },
+      source: { type: 'string' },
+      kind: { type: 'string' },
+      label: { type: 'string' },
+      status: { type: 'string' },
+      progress: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          percent: { type: 'number', minimum: 0, maximum: 100 },
+          stepId: { type: 'string' },
+          parentActivityKey: { type: 'string' },
+          detail: { type: 'string' },
+        },
+      },
+      poll: nullableObject,
+      outputRefs: { type: 'array', items: outputReferenceSchema },
+    },
+  },
+  agentRunEvent: {
+    $id: 'https://dotdrelle.dev/wiki-manager/contracts/agent-run-event/v1',
+    title: 'AgentRunEvent',
+    schemaVersion: '1',
+    type: 'object',
+    required: ['id', 'ts', 'type', 'origin', 'payload'],
+    additionalProperties: true,
+    properties: {
+      id: { type: 'string' },
+      ts: { type: 'string' },
+      type: { type: 'string' },
+      origin: { type: 'string' },
+      runId: nullableString,
+      turnId: nullableString,
+      taskId: nullableString,
+      workspace: nullableString,
+      payload: { type: 'object', additionalProperties: true },
+    },
+  },
+  runRequest: {
+    $id: 'https://dotdrelle.dev/wiki-manager/contracts/run-request/v1',
+    title: 'RuntimeRunRequest',
+    schemaVersion: '1',
+    type: 'object',
+    required: ['input'],
+    additionalProperties: true,
+    properties: {
+      input: { type: 'string', minLength: 1 },
+      prompt: { type: 'string' },
+      workspace: nullableString,
+      runId: nullableString,
+      turnId: nullableString,
+    },
+  },
+  controlMessage: {
+    $id: 'https://dotdrelle.dev/wiki-manager/contracts/control-message/v1',
+    title: 'RuntimeControlMessage',
+    schemaVersion: '1',
+    type: 'object',
+    required: ['action'],
+    additionalProperties: true,
+    properties: {
+      action: { type: 'string', enum: ['status', 'explain', 'message', 'enqueue', 'approve_patch', 'reject_patch'] },
+      input: { type: 'string' },
+      message: { type: 'string' },
+      prompt: { type: 'string' },
+      request: { type: 'string' },
+      intent: { type: 'string', enum: ['observe', 'converse', 'mutate', 'enqueue'] },
+      workspace: nullableString,
+      patchId: { type: 'string' },
+      id: { type: 'string' },
+      reason: { type: 'string' },
+    },
+  },
+  plan: {
+    $id: 'https://dotdrelle.dev/wiki-manager/contracts/plan/v1',
+    title: 'StructuredPlan',
+    schemaVersion: '1',
+    type: 'array',
+    items: planStepSchema,
+  },
+  planPatch: {
+    $id: 'https://dotdrelle.dev/wiki-manager/contracts/plan-patch/v1',
+    title: 'PlanPatch',
+    schemaVersion: '1',
+    type: 'object',
+    required: ['basePlanRevision', 'operations'],
+    additionalProperties: true,
+    properties: {
+      id: nullableString,
+      targetRunId: nullableString,
+      basePlanRevision: { type: 'number', minimum: 0 },
+      reason: nullableString,
+      operations: {
+        type: 'array',
+        items: {
+          type: 'object',
+          required: ['op'],
+          additionalProperties: true,
+          properties: {
+            op: { type: 'string', enum: ['add_task', 'add_dependency', 'remove_dependency', 'cancel_task', 'replace_executor', 'request_approval'] },
+            task: patchTaskSchema,
+            taskId: { type: 'string' },
+            targetTaskId: { type: 'string' },
+            dependencyId: { type: 'string' },
+            dependsOn: { type: 'string' },
+            executor: nullableString,
+            executorQuery: nullableObject,
+            reason: { type: 'string' },
+          },
+        },
+      },
+    },
+  },
+  outputReference: outputReferenceSchema,
+};
+
+export function validateContract(name, value) {
+  const schema = contractSchemas[name];
+  if (!schema) {
+    throw new Error(`Unknown contract schema: ${name}`);
+  }
+  const errors = [];
+  validateSchema(schema, value, name, errors);
+  return {
+    ok: errors.length === 0,
+    errors,
+  };
+}
+
+export function assertContract(name, value) {
+  const result = validateContract(name, value);
+  if (!result.ok) {
+    throw new Error(`Contract ${name} invalid: ${result.errors.join('; ')}`);
+  }
+  return value;
+}
+
+export function validateContractInDev(name, value) {
+  if (!contractValidationEnabled()) return value;
+  return assertContract(name, value);
+}
+
+export function contractValidationEnabled() {
+  return process.env.WIKI_MANAGER_VALIDATE_CONTRACTS === '1'
+    || process.env.CI === 'true'
+    || (process.env.NODE_ENV && process.env.NODE_ENV !== 'production');
+}
+
+function validateSchema(schema, value, path, errors) {
+  if (schema.oneOf) {
+    const matches = schema.oneOf.filter((candidate) => validateCandidate(candidate, value, path));
+    if (matches.length !== 1) errors.push(`${path} must match exactly one schema`);
+    return;
+  }
+  if (schema.anyOf) {
+    const matches = schema.anyOf.filter((candidate) => validateCandidate(candidate, value, path));
+    if (matches.length < 1) errors.push(`${path} must match at least one schema`);
+    return;
+  }
+  if (schema.const !== undefined && value !== schema.const) {
+    errors.push(`${path} must equal ${JSON.stringify(schema.const)}`);
+    return;
+  }
+  if (schema.enum && !schema.enum.includes(value)) {
+    errors.push(`${path} must be one of ${schema.enum.join(', ')}`);
+    return;
+  }
+  if (schema.type && !typeMatches(schema.type, value)) {
+    errors.push(`${path} must be ${formatType(schema.type)}`);
+    return;
+  }
+  if (typeof value === 'string' && schema.minLength != null && value.length < schema.minLength) {
+    errors.push(`${path} must have length >= ${schema.minLength}`);
+  }
+  if (typeof value === 'number') {
+    if (schema.minimum != null && value < schema.minimum) errors.push(`${path} must be >= ${schema.minimum}`);
+    if (schema.maximum != null && value > schema.maximum) errors.push(`${path} must be <= ${schema.maximum}`);
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => validateSchema(schema.items ?? {}, item, `${path}[${index}]`, errors));
+    return;
+  }
+  if (value && typeof value === 'object') {
+    for (const key of schema.required ?? []) {
+      if (!Object.hasOwn(value, key)) errors.push(`${path}.${key} is required`);
+    }
+    for (const [key, childSchema] of Object.entries(schema.properties ?? {})) {
+      if (Object.hasOwn(value, key)) validateSchema(childSchema, value[key], `${path}.${key}`, errors);
+    }
+    if (schema.additionalProperties === false) {
+      const allowed = new Set(Object.keys(schema.properties ?? {}));
+      for (const key of Object.keys(value)) {
+        if (!allowed.has(key)) errors.push(`${path}.${key} is not allowed`);
+      }
+    }
+  }
+}
+
+function validateCandidate(schema, value, path) {
+  const errors = [];
+  validateSchema(schema, value, path, errors);
+  return errors.length === 0;
+}
+
+function typeMatches(type, value) {
+  const types = Array.isArray(type) ? type : [type];
+  return types.some((candidate) => {
+    if (candidate === 'array') return Array.isArray(value);
+    if (candidate === 'null') return value === null;
+    if (candidate === 'integer') return Number.isInteger(value);
+    if (candidate === 'number') return typeof value === 'number' && Number.isFinite(value);
+    if (candidate === 'object') return value !== null && typeof value === 'object' && !Array.isArray(value);
+    return typeof value === candidate;
+  });
+}
+
+function formatType(type) {
+  return Array.isArray(type) ? type.join('|') : type;
+}
+
+export { STATUS_VALUES };