ultra-builder-pro-cli 0.24.2 → 0.25.0

package/adapters/opencode.js

@@ -6,6 +6,8 @@ const fs = require('node:fs');
 const crypto = require('node:crypto');
 const os = require('node:os');
 const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { isDeepStrictEqual } = require('node:util');
 
 const {
   copyTree,
@@ -64,6 +66,79 @@ function resolveRepoRoot(ctx = {}) {
   return ctx.repoRoot || path.resolve(__dirname, '..');
 }
 
+function shouldRunHostCli(ctx = {}) {
+  if (typeof ctx.runHostCli === 'boolean') return ctx.runHostCli;
+  return ctx.scope === 'global' && !ctx.configDir;
+}
+
+function runOpenCodeCli(args, ctx = {}) {
+  const target = resolveTarget(ctx);
+  const result = spawnSync(ctx.opencodeBin || 'opencode', args, {
+    cwd: ctx.cwd || process.cwd(),
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    killSignal: 'SIGKILL',
+    env: {
+      ...process.env,
+      OPENCODE_CONFIG_DIR: target,
+    },
+    timeout: ctx.hostCliTimeoutMs || 30000,
+  });
+  if (result.error) {
+    if (result.error.code === 'ETIMEDOUT') {
+      const error = new Error(`opencode ${args.join(' ')} timed out`);
+      error.code = 'HOST_CLI_TIMEOUT';
+      throw error;
+    }
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    const detail = (result.stderr || result.stdout || '').trim();
+    throw new Error(`opencode ${args.join(' ')} failed${detail ? `: ${detail}` : ''}`);
+  }
+  return result.stdout;
+}
+
+function openCodeMcpRow(output, serverName) {
+  for (const rawLine of output.split(/\r?\n/)) {
+    const tokens = rawLine.trim().split(/\s+/);
+    if (tokens.some((token) => token === serverName)) return rawLine;
+  }
+  return '';
+}
+
+function inspectOpenCodeHost(ctx = {}) {
+  const target = resolveTarget(ctx);
+  const expectedLauncher = path.join(target, BUNDLE_DIR, 'runtime', 'launch.cjs');
+  const expected = managedMcpEntry(target);
+  const config = JSON.parse(runOpenCodeCli(['debug', 'config'], ctx));
+  const entry = config?.mcp?.[MCP_SERVER_NAME];
+  const configOk = isDeepStrictEqual(entry, expected);
+  const mcpOutput = runOpenCodeCli(['mcp', 'list'], ctx)
+    .replace(/\u001b\[[0-9;]*m/g, '');
+  const mcpLine = openCodeMcpRow(mcpOutput, MCP_SERVER_NAME);
+  const mcpOk = /\bconnected\b/i.test(mcpLine);
+  return { config, configOk, mcpOutput, mcpOk };
+}
+
+function managedMcpEntry(target) {
+  const command = mcpCommand(path.join(target, BUNDLE_DIR, 'runtime', 'launch.cjs'));
+  return {
+    type: 'local',
+    enabled: true,
+    command: [command.command, ...command.args],
+  };
+}
+
+function hasManagedMcpIdentity(entry, target) {
+  return Boolean(
+    entry
+    && typeof entry === 'object'
+    && !Array.isArray(entry)
+    && isDeepStrictEqual(entry.command, managedMcpEntry(target).command),
+  );
+}
+
 function lowercaseFrontmatterTransform(buf, relPath) {
   if (!relPath.endsWith('.md')) return buf;
   const text = buf.toString('utf8');
@@ -550,12 +625,7 @@ function buildStaging(repoRoot, staging, target) {
   const configFile = path.join(target, 'opencode.json');
   const existing = readJsonSafe(configFile, { rescue: true });
   const mcp = { ...(existing.mcp || {}) };
-  const command = mcpCommand(path.join(target, BUNDLE_DIR, 'runtime', 'launch.cjs'));
-  mcp[MCP_SERVER_NAME] = {
-    type: 'local',
-    enabled: true,
-    command: [command.command, ...command.args],
-  };
+  mcp[MCP_SERVER_NAME] = managedMcpEntry(target);
   const next = { ...existing, mcp };
   delete next[LEGACY_SENTINEL_KEY];
   writeAtomic(path.join(staging, 'opencode.json'), JSON.stringify(next, null, 2) + '\n');
@@ -720,12 +790,45 @@ function doctor(ctx = {}) {
     });
   }
   report.checks.registration = { status: registrationOk ? 'pass' : 'fail' };
+  if (shouldRunHostCli(ctx)) {
+    try {
+      const host = inspectOpenCodeHost(ctx);
+      report.checks.host_config = { status: host.configOk ? 'pass' : 'fail' };
+      report.checks.host_mcp = { status: host.mcpOk ? 'pass' : 'fail' };
+      if (!host.configOk) {
+        report.issues.push({
+          code: 'HOST_CONFIG_NOT_CONSUMED',
+          path: configFile,
+        });
+      }
+      if (!host.mcpOk) {
+        report.issues.push({
+          code: 'HOST_MCP_NOT_CONNECTED',
+          server: MCP_SERVER_NAME,
+        });
+      }
+    } catch (error) {
+      report.checks.host_config = { status: 'fail' };
+      report.checks.host_mcp = { status: 'fail' };
+      report.issues.push({
+        code: error.code === 'HOST_CLI_TIMEOUT'
+          ? 'HOST_CLI_TIMEOUT'
+          : 'HOST_CLI_INSPECTION_FAILED',
+        message: error.message,
+      });
+    }
+  }
   return applyNativeDoctor(report, path.join(target, BUNDLE_DIR, 'runtime'));
 }
 
 function uninstall(ctx = {}) {
   const target = resolveTarget(ctx);
-  const report = { target, removed: {}, config: { updated: false } };
+  const report = {
+    target,
+    removed: {},
+    config: { updated: false },
+    issues: [],
+  };
   const pluginFile = path.join(target, 'plugins', 'ultra-builder-pro.js');
   const bundleRoot = path.join(target, BUNDLE_DIR);
   const pluginOwned = fs.existsSync(pluginFile)
@@ -734,14 +837,31 @@ function uninstall(ctx = {}) {
   const configFile = path.join(target, 'opencode.json');
   if (fs.existsSync(configFile)) {
     const existing = readJsonSafe(configFile);
-    if (pluginOwned || bundleOwned || existing[LEGACY_SENTINEL_KEY]) {
+    const currentMcp = existing.mcp?.[MCP_SERVER_NAME];
+    const expectedMcp = managedMcpEntry(target);
+    const mcpOwned = hasManagedMcpIdentity(currentMcp, target);
+    if (currentMcp !== undefined && !mcpOwned) {
+      report.config.skipped = true;
+      report.config.reason = 'ownership-conflict';
+      report.issues.push({
+        code: 'MCP_OWNERSHIP_CONFLICT',
+        path: configFile,
+        server: MCP_SERVER_NAME,
+        expected: expectedMcp,
+        actual: currentMcp,
+      });
+      return report;
+    }
+    if (mcpOwned || existing[LEGACY_SENTINEL_KEY]) {
       const mcp = { ...(existing.mcp || {}) };
-      delete mcp[MCP_SERVER_NAME];
+      if (mcpOwned) delete mcp[MCP_SERVER_NAME];
       const next = { ...existing, mcp };
       delete next[LEGACY_SENTINEL_KEY];
       if (Object.keys(next.mcp || {}).length === 0) delete next.mcp;
-      writeAtomic(configFile, JSON.stringify(next, null, 2) + '\n');
-      report.config.updated = true;
+      if (!isDeepStrictEqual(next, existing)) {
+        writeAtomic(configFile, JSON.stringify(next, null, 2) + '\n');
+        report.config.updated = true;
+      }
     }
   }
   if (pluginOwned) {
@@ -792,6 +912,7 @@ module.exports = {
   SOURCE_TAG,
   BUNDLE_DIR,
   pluginSource,
+  inspectOpenCodeHost,
   resolveTarget,
   install,
   uninstall,

package/docs/AGENT-CONTEXT.md

@@ -58,6 +58,20 @@ digest. It never creates the rejected semantic row or claims that authority was
 committed. `_ultra.projection_commit` reports only the post-call generated-view cycle;
 it is not a semantic acceptance receipt.
 
+Every public input has one exact kind/action contract. Unknown fields, wrong scalar or
+container types, invalid enums, malformed digests, and mismatched scopes are diagnosed
+before SQLite affinity, filesystem writers, or host adapters can coerce them. A
+correctable rejection returns `accepted: false`, `mutable: true`, typed diagnostics,
+and bounded audit history; it is not an MCP transport failure. Reusing an idempotency
+key for a different request follows that same repairable path, while retrying the exact
+request returns the original result.
+
+Every accepted mutation and its idempotency receipt are one logical commit. DB-only
+writes share one immediate transaction. A write that also owns a managed file, team
+checkpoint, worktree, Worker Packet, or archive journal either publishes both sides or
+restores the prior bytes and rows. If compensation itself cannot be proven, the kernel
+returns a typed recovery requirement instead of reporting partial success.
+
 ## Context Envelope
 
 Every Skill begins by reading `ultra.context` for the relevant stage and scope. The

package/docs/ARTIFACT-AUTHORITY.md

@@ -88,6 +88,19 @@ durable effects, typed applied references, Stage Checkpoint evidence, artifact h
 verification commands and results, provenance, events, and recovery state. It must not
 include chain-of-thought, UI-click proof, raw prompts, or conversation transcripts.
 
+Public kernel inputs are exact at their owning kind/action boundary. SQLite constraints
+remain defense in depth, not the first definition of a business vocabulary: wrong
+types, unsupported enums, unknown fields, malformed references, and invalid digests
+are rejected as typed mutable diagnostics before any row or file write. The rejected
+attempt is retained as audit evidence but never becomes semantic authority.
+
+An accepted mutation and its durable idempotency receipt form one logical transaction.
+DB-only operations commit them together. Operations that also publish managed files,
+the Git team checkpoint, a Session worktree/Worker Packet, or an archive packet use a
+recoverable journal or verified compensation. Failure restores the exact prior file
+bytes, rows, ledger generation, lease, packet, and worktree where applicable; an
+unprovable rollback becomes an explicit recovery condition rather than false success.
+
 Verified conclusions from `.ultra/.runtime/collab/` or other scratch locations must be promoted
 into the invoking DB-bound workflow artifact or report. Keeping a file in the scratch
 directory is not promotion.

package/docs/COMMIT-HASH-BACKFILL.md

@@ -11,27 +11,34 @@ longer changes any tracked file.
 
 After implementation, verification, and review are current:
 
-1. Update the task to `completed`. The MCP publishes its durable status and contract to
-   `.ultra/tasks/tasks.json`.
-2. Create one local task commit containing the implementation, semantic Ultra
-   artifacts, and the team ledger checkpoint.
-3. Read the resulting `HEAD` and update only `completion_commit` through `task.update`.
-4. Verify the task worktree `HEAD`, integration ancestry, review evidence, and public
-   seam; then close the session and complete the dev workflow.
-
-The third step changes only ignored runtime state. Repeating it with the same hash is
-byte-idempotent and leaves Git clean.
-
-If the commit fails after step 1, transition the still-session-owned task from
-`completed` to `blocked`, preserve the worktree, and record the failure. This recovery
-transition is accepted only while `completion_commit` is absent. A task with a recorded
-completion commit remains terminal.
+1. Record `task_outcome / complete { id, packet_digest }`. Completion validates the
+   assigned Worker Packet and durable output, and accepts neither an arbitrary `patch`
+   nor any commit hash.
+2. Publish the completed durable status and Task contract with `ultra.sync`.
+3. Create one local integration commit containing the implementation, semantic Ultra
+   artifacts, and `.ultra/tasks/tasks.json`.
+4. Read the resulting full `HEAD` and record
+   `task_outcome / attest_commit { id, completion_commit }`.
+5. Verify the task worktree head, integration ancestry, review evidence, and public
+   seam; then release the session.
+
+Attestation requires an already completed Task and a real commit integrated into the
+current checkout. It changes only ignored runtime state, does not republish team
+authority, and is idempotent for the same hash. Git remains clean, so no bookkeeping
+commit is permitted.
+
+If sync or the integration commit fails after completion, record
+`task_outcome / block { id }`, preserve the still-session-owned worktree, and record the
+failure. This recovery transition is accepted only while `completion_commit` is absent.
+An attested Task cannot use this block recovery; an explicit later reopen records the
+prior attestation in event history before clearing the current local proof.
 
 ## Parent-supervised workers
 
-A worker records evidence and exits without finalizing the parent-owned task. The
-primary host verifies and integrates the worker commit, publishes the task completion
-checkpoint, records the integrated commit hash locally, and settles the lease.
+A worker records evidence and exits without finalizing the parent-owned Task. The
+primary host validates and stages the worker result, records durable completion,
+publishes the team checkpoint, creates the single authoritative integration commit,
+attests that integrated hash locally, and settles the lease.
 
 ## Why the hash is local
 

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -106,6 +106,8 @@ instructions, project `.ultra`, unrelated plugins, and unrelated host configurat
 | Global flag | `--claude` | `--opencode` | `--codex` | `--kimi` | `--grok` |
 | Staging + atomic swap | FULL | FULL | FULL | FULL | FULL |
 | Exact-host preflight | FULL | FULL | FULL | FULL | FULL |
+| Native registration truth | host manifest | host config | plugin manifest/cache | installed registry | `grok plugin list/details` |
+| Active MCP truth | host MCP config | host MCP config | plugin cache | managed plugin config | `grok inspect` + `grok mcp doctor` |
 | Managed uninstall guard | FULL | FULL | FULL | FULL | FULL |
 | Preserve unrelated config | FULL | FULL | FULL | FULL | FULL |
 | Read-only Doctor | FULL | FULL | FULL | FULL | FULL |
@@ -114,6 +116,20 @@ Preflight uses the final manifest command and verifies initialize, `tools/list =
 public write/read, Doctor backup, close/reopen consistency, native provenance, and
 lazy project initialization.
 
+The Grok adapter probes the installed CLI's command and flag capabilities rather
+than branching on a Grok version number. Global installation uses Grok's native
+plugin registry, keeps a durable managed local source for native refresh, and
+resolves the MCP launcher through `${GROK_PLUGIN_ROOT}` after Grok copies the plugin
+under its dynamic `installed-plugins/<repo-key>` path. An older raw
+`$GROK_HOME/plugins/ultra-builder-pro` installation is backed up and migrated; a
+failed native install restores the prior source and registration.
+
+`grok mcp list` is not the plugin-MCP inventory surface in current Grok releases;
+it reports explicit user/project MCP configuration. Ultra therefore does not add a
+second `[mcp_servers]` entry merely to make that command display the plugin. The
+authoritative plugin consumer checks are the native plugin registry, merged
+`grok inspect` MCP source, and the live `grok mcp doctor` handshake.
+
 ## Durable compatibility
 
 | Capability | Contract |
@@ -138,5 +154,5 @@ are reconstructed only from verified authority.
   preservation.
 - `tests/package-smoke.test.cjs` installs the npm tarball and performs five real
   launcher write/read/backup/reopen round trips.
-- Grok acceptance also runs the available native plugin validate/inspect command and
-  camelCase Hook fixtures.
+- Grok acceptance runs capability probing, native install/list/details/enable,
+  merged inspect, MCP Doctor, migration rollback, and camelCase Hook fixtures.

package/mcp-server/lib/artifact-registry.cjs

@@ -17,6 +17,12 @@ const ENDPOINT_TYPES = new Set([
 ]);
 const OWNER_TYPES = new Set(['project', 'baseline', 'change', 'task', 'workflow']);
 const STATUSES = new Set(['current', 'stale', 'terminal', 'archived']);
+const ARTIFACT_INPUT_FIELDS = new Set([
+  'id', 'owner_type', 'owner_id', 'change_id', 'task_id', 'kind', 'path',
+  'content_digest', 'expected_before_digest', 'source_refs', 'consumer_refs',
+  'provenance', 'metadata', 'status',
+]);
+const DIGEST = /^[0-9a-f]{64}$/;
 const OWNER_TABLES = Object.freeze({
   baseline: 'baselines',
   change: 'changes',
@@ -48,6 +54,70 @@ class ArtifactRegistryError extends Error {
   }
 }
 
+function artifactText(value, field, { optional = false, nullable = false } = {}) {
+  if (value === undefined && optional) return undefined;
+  if (value === null && nullable) return null;
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new ArtifactRegistryError(
+      'VALIDATION_ERROR',
+      `${field} must be a non-empty string${nullable ? ' or null' : ''}`,
+    );
+  }
+  return value.trim();
+}
+
+function artifactDigest(value, field, { nullable = false } = {}) {
+  if (value === undefined) return undefined;
+  if (value === null && nullable) return null;
+  if (typeof value !== 'string' || !DIGEST.test(value)) {
+    throw new ArtifactRegistryError(
+      'VALIDATION_ERROR',
+      `${field} must be a lowercase SHA-256 digest${nullable ? ' or null' : ''}`,
+    );
+  }
+  return value;
+}
+
+function assertJsonValue(value, field, seen = new Set()) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
+  if (typeof value === 'number') {
+    if (Number.isFinite(value)) return;
+    throw new ArtifactRegistryError('VALIDATION_ERROR', `${field} must contain valid JSON values`);
+  }
+  if (typeof value !== 'object') {
+    throw new ArtifactRegistryError('VALIDATION_ERROR', `${field} must contain valid JSON values`);
+  }
+  if (seen.has(value)) {
+    throw new ArtifactRegistryError('VALIDATION_ERROR', `${field} must not contain circular references`);
+  }
+  if (!Array.isArray(value)) {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new ArtifactRegistryError(
+        'VALIDATION_ERROR', `${field} must contain only JSON objects`,
+      );
+    }
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertJsonValue(item, `${field}[${index}]`, seen));
+  } else {
+    Object.entries(value).forEach(([key, item]) => (
+      assertJsonValue(item, `${field}.${key}`, seen)
+    ));
+  }
+  seen.delete(value);
+}
+
+function normalizeJsonObject(value, field) {
+  if (value === undefined) return {};
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new ArtifactRegistryError('VALIDATION_ERROR', `${field} must be a JSON object`);
+  }
+  assertJsonValue(value, field);
+  return JSON.parse(JSON.stringify(value));
+}
+
 function parseJson(value, fallback) {
   if (value == null || value === '') return fallback;
   try { return JSON.parse(value); } catch { return fallback; }
@@ -302,6 +372,13 @@ function normalizeEndpoint(endpoint, field) {
   if (!endpoint || typeof endpoint !== 'object' || Array.isArray(endpoint)) {
     throw new ArtifactRegistryError('VALIDATION_ERROR', `${field} must be an object`);
   }
+  const unknown = Object.keys(endpoint)
+    .filter((key) => !['type', 'id', 'relation'].includes(key));
+  if (unknown.length > 0) {
+    throw new ArtifactRegistryError(
+      'VALIDATION_ERROR', `${field}.${unknown[0]} is not allowed`,
+    );
+  }
   const type = typeof endpoint.type === 'string' ? endpoint.type.trim() : '';
   const id = typeof endpoint.id === 'string' ? endpoint.id.trim() : '';
   const relation = typeof endpoint.relation === 'string' ? endpoint.relation.trim() : '';
@@ -313,6 +390,59 @@ function normalizeEndpoint(endpoint, field) {
   return { type, id, relation };
 }
 
+function normalizeArtifactInput(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw new ArtifactRegistryError('VALIDATION_ERROR', 'artifact input is required');
+  }
+  const unknown = Object.keys(input).filter((field) => !ARTIFACT_INPUT_FIELDS.has(field));
+  if (unknown.length > 0) {
+    throw new ArtifactRegistryError(
+      'VALIDATION_ERROR', `artifact.${unknown[0]} is not allowed`,
+    );
+  }
+  const status = input.status === undefined
+    ? 'current'
+    : artifactText(input.status, 'artifact.status');
+  if (!STATUSES.has(status)) {
+    throw new ArtifactRegistryError('VALIDATION_ERROR', `invalid artifact status: ${status}`);
+  }
+  const normalizeRefs = (value, field) => {
+    if (value === undefined) return [];
+    if (!Array.isArray(value)) {
+      throw new ArtifactRegistryError('VALIDATION_ERROR', `${field} must be an array`);
+    }
+    return value.map((item, index) => normalizeEndpoint(item, `${field}[${index}]`));
+  };
+  return {
+    id: artifactText(input.id, 'artifact.id', { optional: true }),
+    ownerType: artifactText(input.owner_type, 'artifact.owner_type'),
+    ownerId: artifactText(input.owner_id, 'artifact.owner_id'),
+    changeId: artifactText(
+      input.change_id,
+      'artifact.change_id',
+      { optional: true, nullable: true },
+    ),
+    taskId: artifactText(
+      input.task_id,
+      'artifact.task_id',
+      { optional: true, nullable: true },
+    ),
+    kind: artifactText(input.kind, 'artifact.kind'),
+    path: artifactText(input.path, 'artifact.path'),
+    status,
+    contentDigest: artifactDigest(input.content_digest, 'artifact.content_digest'),
+    expectedBeforeDigest: artifactDigest(
+      input.expected_before_digest,
+      'artifact.expected_before_digest',
+      { nullable: true },
+    ),
+    sourceRefs: normalizeRefs(input.source_refs, 'artifact.source_refs'),
+    consumerRefs: normalizeRefs(input.consumer_refs, 'artifact.consumer_refs'),
+    provenance: normalizeJsonObject(input.provenance, 'artifact.provenance'),
+    metadata: normalizeJsonObject(input.metadata, 'artifact.metadata'),
+  };
+}
+
 function assertEndpoint(db, endpoint, field) {
   const normalized = normalizeEndpoint(endpoint, field);
   const { type, id } = normalized;
@@ -339,6 +469,34 @@ function assertOwner(db, ownerType, ownerId) {
   }
 }
 
+function assertArtifactOwner(db, ownerType, ownerId) {
+  assertOwner(db, ownerType, ownerId);
+}
+
+function assertDeclaredOwnerRefs(db, normalized) {
+  const expectedTaskId = normalized.ownerType === 'task' ? normalized.ownerId : null;
+  const expectedChangeId = normalized.ownerType === 'change'
+    ? normalized.ownerId
+    : normalized.ownerType === 'task'
+      ? db.prepare('SELECT change_id FROM tasks WHERE id = ?').get(normalized.ownerId)?.change_id || null
+      : normalized.ownerType === 'workflow'
+        ? db.prepare('SELECT change_id FROM workflow_runs WHERE id = ?').get(normalized.ownerId)?.change_id || null
+        : null;
+  for (const [field, supplied, expected] of [
+    ['change_id', normalized.changeId, expectedChangeId],
+    ['task_id', normalized.taskId, expectedTaskId],
+  ]) {
+    if (supplied !== undefined && supplied !== expected) {
+      throw new ArtifactRegistryError(
+        'ARTIFACT_AUTHORITY_CONFLICT',
+        `artifact ${field} does not match its owner authority`,
+        { field, supplied, expected },
+      );
+    }
+  }
+  return { changeId: expectedChangeId, taskId: expectedTaskId };
+}
+
 function edgesForArtifact(db, artifactId) {
   const sources = db.prepare(
     `SELECT source_type AS type, source_id AS id, relation
@@ -527,28 +685,20 @@ function invalidateDownstreamInTx(db, artifactId, priorConsumers = []) {
 }
 
 function preflightArtifactPublication(db, input, { rootDir = process.cwd() } = {}) {
-  if (!input || typeof input !== 'object' || Array.isArray(input)) {
-    throw new ArtifactRegistryError('VALIDATION_ERROR', 'artifact input is required');
-  }
-  const ownerType = typeof input.owner_type === 'string' ? input.owner_type.trim() : '';
-  const ownerId = typeof input.owner_id === 'string' ? input.owner_id.trim() : '';
-  const kind = typeof input.kind === 'string' ? input.kind.trim() : '';
-  const status = input.status || 'current';
-  if (!kind || !STATUSES.has(status)) {
-    throw new ArtifactRegistryError(
-      'VALIDATION_ERROR', 'artifact kind and valid status are required',
-    );
-  }
+  const normalized = normalizeArtifactInput(input);
+  const {
+    ownerType, ownerId, kind, status,
+  } = normalized;
   assertOwner(db, ownerType, ownerId);
-  const resolved = resolveArtifactFile(rootDir, input.path);
+  assertDeclaredOwnerRefs(db, normalized);
+  const resolved = resolveArtifactFile(rootDir, normalized.path);
   if (isExemptArtifactPath(resolved.relative) || isGeneratedProjectionPath(resolved.relative)) {
     throw new ArtifactRegistryError(
       'ARTIFACT_PATH_EXEMPT',
       `runtime, scratch, and generated projection paths are not registry authority: ${resolved.relative}`,
     );
   }
-  const explicitId = typeof input.id === 'string' && input.id.trim() !== ''
-    ? input.id.trim() : null;
+  const explicitId = normalized.id || null;
   const existingById = explicitId
     ? db.prepare('SELECT * FROM artifacts WHERE id = ?').get(explicitId)
     : null;
@@ -625,18 +775,14 @@ function preflightArtifactPublication(db, input, { rootDir = process.cwd() } = {
 }
 
 function recordArtifactInTx(db, input, { rootDir = process.cwd() } = {}) {
-  if (!input || typeof input !== 'object' || Array.isArray(input)) {
-    throw new ArtifactRegistryError('VALIDATION_ERROR', 'artifact input is required');
-  }
-  const ownerType = typeof input.owner_type === 'string' ? input.owner_type.trim() : '';
-  const ownerId = typeof input.owner_id === 'string' ? input.owner_id.trim() : '';
-  const kind = typeof input.kind === 'string' ? input.kind.trim() : '';
-  const status = input.status || 'current';
-  if (!kind || !STATUSES.has(status)) {
-    throw new ArtifactRegistryError('VALIDATION_ERROR', 'artifact kind and valid status are required');
-  }
+  const normalized = normalizeArtifactInput(input);
+  const {
+    ownerType, ownerId, kind, status,
+    sourceRefs, consumerRefs, provenance, metadata,
+  } = normalized;
   assertOwner(db, ownerType, ownerId);
-  const resolved = resolveArtifactFile(rootDir, input.path);
+  const ownerRefs = assertDeclaredOwnerRefs(db, normalized);
+  const resolved = resolveArtifactFile(rootDir, normalized.path);
   if (isExemptArtifactPath(resolved.relative) || isGeneratedProjectionPath(resolved.relative)) {
     throw new ArtifactRegistryError(
       'ARTIFACT_PATH_EXEMPT',
@@ -645,18 +791,7 @@ function recordArtifactInTx(db, input, { rootDir = process.cwd() } = {}) {
   }
   const stableRead = openStableArtifactRead(resolved);
   try {
-  const sourceRefs = Array.isArray(input.source_refs)
-    ? input.source_refs.map((item, index) => normalizeEndpoint(item, `source_refs[${index}]`))
-    : [];
-  const consumerRefs = Array.isArray(input.consumer_refs)
-    ? input.consumer_refs.map((item, index) => normalizeEndpoint(item, `consumer_refs[${index}]`))
-    : [];
-  const provenance = input.provenance && typeof input.provenance === 'object'
-    && !Array.isArray(input.provenance) ? input.provenance : {};
-  const metadata = input.metadata && typeof input.metadata === 'object'
-    && !Array.isArray(input.metadata) ? input.metadata : {};
-  const explicitId = typeof input.id === 'string' && input.id.trim() !== ''
-    ? input.id.trim() : null;
+  const explicitId = normalized.id || null;
   const existingById = explicitId
     ? db.prepare('SELECT * FROM artifacts WHERE id = ?').get(explicitId)
     : null;
@@ -710,31 +845,25 @@ function recordArtifactInTx(db, input, { rootDir = process.cwd() } = {}) {
     });
   }
   const beforeDigest = existing?.digest || existing?.content_hash || null;
-  if (input.expected_before_digest !== undefined
-    && input.expected_before_digest !== beforeDigest) {
+  if (normalized.expectedBeforeDigest !== undefined
+    && normalized.expectedBeforeDigest !== beforeDigest) {
     throw new ArtifactRegistryError(
       'ARTIFACT_DIGEST_CONFLICT',
       `artifact ${artifactId} changed since it was read`,
-      { expected: input.expected_before_digest, actual: beforeDigest },
+      { expected: normalized.expectedBeforeDigest, actual: beforeDigest },
     );
   }
   const afterDigest = stableRead.digest;
-  if (input.content_digest !== undefined && input.content_digest !== afterDigest) {
+  if (normalized.contentDigest !== undefined && normalized.contentDigest !== afterDigest) {
     throw new ArtifactRegistryError(
       'ARTIFACT_DIGEST_CONFLICT',
       `artifact bytes do not match the supplied digest: ${resolved.relative}`,
-      { expected: input.content_digest, actual: afterDigest },
+      { expected: normalized.contentDigest, actual: afterDigest },
     );
   }
   const changed = beforeDigest !== afterDigest;
   const priorConsumers = existing ? edgesForArtifact(db, artifactId).consumers : [];
-  const ownerChangeId = ownerType === 'change'
-    ? ownerId
-    : ownerType === 'task'
-      ? db.prepare('SELECT change_id FROM tasks WHERE id = ?').get(ownerId)?.change_id || null
-      : ownerType === 'workflow'
-        ? db.prepare('SELECT change_id FROM workflow_runs WHERE id = ?').get(ownerId)?.change_id || null
-        : null;
+  const ownerChangeId = ownerRefs.changeId;
   const now = new Date().toISOString();
   let invalidated = [];
   db.prepare(
@@ -754,7 +883,7 @@ function recordArtifactInTx(db, input, { rootDir = process.cwd() } = {}) {
   ).run(
     artifactId, ownerType, ownerId,
     ownerChangeId,
-    ownerType === 'task' ? ownerId : null,
+    ownerRefs.taskId,
     kind, resolved.relative, afterDigest, afterDigest, beforeDigest, afterDigest,
     JSON.stringify(provenance), JSON.stringify(metadata), status,
     existing?.created_at || now, now,
@@ -1085,6 +1214,7 @@ module.exports = {
   ENDPOINT_TYPES,
   OWNER_TYPES,
   STATUSES,
+  assertArtifactOwner,
   digestFile,
   getArtifact,
   inspectArtifactHealth,