weir-harness 1.2.0 → 1.2.2

package/src/capabilities/preset-library.js

@@ -3,6 +3,8 @@
 import { createHash } from 'node:crypto'
 import { realpathSync } from 'node:fs'
 import { isSegment } from './store/paths.js'
+import { createSkillIdentity, skillIdentityKey } from './skill-identity.js'
+import { createMcpRegistry } from './mcp-registry.js'
 
 export const PRESET_SCHEMA_VERSION = 1
 
@@ -166,3 +168,248 @@ export function createPresetLibrary({ store }) {
   }
   return { load, create, edit, rename, resave, remove, exportPreset, withNamespace, unitOf }
 }
+
+// ---- /capabilities preset verbs (capabilities-deepening D2) -----------------
+// The seven preset-verb bodies of the /capabilities command, moved verbatim
+// out of the handler into the module that owns the preset contract (the CAS
+// read-modify-write and the created/edited/deleted/revision-conflict/
+// name-conflict status values above). Per-invocation state arrives through
+// the `call` argument ({ agent, options }); everything the handler used to
+// close over is injected in `wiring` — including the payload builders and the
+// v2 packer, so this module keeps its import graph acyclic (read-payloads.js
+// and preset-package.js both import from here, never the reverse).
+
+/** Shared scope validation for the preset verbs (command-surface text). */
+export const presetScopeError = spec => (spec?.scope !== 'global' && spec?.scope !== 'workspace')
+  ? { kind: 'error', text: `capabilities: scope must be "global" | "workspace", got ${JSON.stringify(spec?.scope ?? null)}` }
+  : null
+
+/** The shared no-workspace command result (the historical shape: kind error). */
+export const noWorkspaceError = () => ({ kind: 'error', text: JSON.stringify({ status: 'no-workspace' }) })
+
+/**
+ * The draft branch of the save-time set resolution: the client-supplied
+ * arrays, normalized. (from:'applied' never takes this branch — its sets are
+ * server-authoritative.)
+ */
+export const draftSelectionSets = spec => ({
+  skills: Array.isArray(spec.skills) ? spec.skills : [],
+  mcpServers: Array.isArray(spec.mcpServers) ? spec.mcpServers : [],
+  unresolvedRefs: Array.isArray(spec.unresolvedRefs) ? spec.unresolvedRefs : [],
+})
+
+const message = error => (error instanceof Error ? error.message : String(error))
+
+/**
+ * The /capabilities preset verb bodies. `wiring` is the handler's former
+ * closure surface, injected explicitly:
+ * @param {{
+ *   openStore: () => any,
+ *   provider: any,
+ *   inventory: (options: any) => Promise<any>,
+ *   lifecycle: any,
+ *   builders: { buildPresetsPayload: Function, buildReceiptPayload: Function },
+ *   packPresetPackage: Function,
+ * }} wiring
+ */
+export function createPresetVerbs(wiring) {
+  /**
+   * Applied preset writers share one locked source proof. The library
+   * enters this callback only under its namespace guard, and holds the
+   * selection lock until the target unit CAS has finished.
+   */
+  const appliedPresetSource = (spec, sets, store, agent, options) => commit => store.withSelectionSnapshot(agent.id, async current => {
+    if (!Number.isSafeInteger(spec.expectedSelectionRevision) || spec.expectedSelectionRevision < 0
+      || typeof spec.expectedSelectionDigest !== 'string' || !/^[a-f0-9]{64}$/.test(spec.expectedSelectionDigest)
+      || current.revision !== spec.expectedSelectionRevision) return { status: 'source-changed', revision: current.revision }
+    const receipt = await wiring.builders.buildReceiptPayload({ provider: wiring.provider, lifecycle: wiring.lifecycle, store }, options)
+    const effective = receipt.effective
+    const selected = effective.skillIdentities
+    const raw = current.kind === 'ok' ? current.payload?.skills : null
+    if (current.kind === 'ok') {
+      const rawKeys = new Set()
+      const effectiveKeys = new Set(selected.map(skillIdentityKey))
+      const missing = []
+      for (const identity of Array.isArray(raw) ? raw : []) {
+        try {
+          const key = skillIdentityKey(createSkillIdentity(identity))
+          rawKeys.add(key)
+          if (!effectiveKeys.has(key)) missing.push(identity.name)
+        } catch { missing.push(String(identity?.name ?? identity ?? 'unknown')) }
+      }
+      if (!Array.isArray(raw) || missing.length || rawKeys.size !== selected.length || receipt.warnings.length) {
+        return { status: 'source-unavailable', missing, reason: receipt.warnings[0] ?? 'Selected Skills are not completely available' }
+      }
+      if (!Array.isArray(current.payload?.mcpServers)
+        || JSON.stringify(current.payload.mcpServers) !== JSON.stringify(effective.mcpServers)) {
+        return { status: 'source-unavailable', missing: [], reason: 'Applied MCP snapshot is unavailable' }
+      }
+    } else if (receipt.warnings.length) return { status: 'source-unavailable', missing: [], reason: receipt.warnings[0] }
+    // Provider enumeration can short-circuit an empty selection.
+    const observed = await wiring.inventory(options)
+    if (observed?.complete !== true) return { status: 'source-unavailable', missing: [], reason: 'Skill inventory is incomplete' }
+    if (effective.digest !== spec.expectedSelectionDigest || receipt.revision !== current.revision) {
+      return { status: 'source-changed', revision: current.revision }
+    }
+    sets.skills.push(...selected)
+    sets.mcpServers.push(...effective.mcpServers)
+    return commit()
+  })
+
+  /** presets: thin shell over the shared builder. */
+  async function presets(_spec, call) {
+    // Thin shell over the shared builder (read-payloads.js): domain failures
+    // stay JSON status text (the panel categorizes them); the remote resolves
+    // the same object as a plain value.
+    try {
+      const payload = await wiring.builders.buildPresetsPayload({ store: wiring.openStore() }, call.options)
+      if (typeof payload.status === 'string') return { kind: 'error', text: JSON.stringify(payload) }
+      return { kind: 'success', text: JSON.stringify(payload) }
+    } catch (cause) {
+      return { kind: 'error', text: `capabilities presets failed: ${message(cause)}` }
+    }
+  }
+
+  /** preset-save / preset-rename / preset-resave (one shared body, per action). */
+  async function presetSaveLike(action, spec, call) {
+    try {
+      const scopeError = presetScopeError(spec)
+      if (scopeError) return scopeError
+      const workspaceKey = workspaceKeyOf(call.options)
+      if (spec.scope === 'workspace' && !isSegment(workspaceKey)) return noWorkspaceError()
+      const library = createPresetLibrary({ store: wiring.openStore() })
+      if (action === 'preset-rename' || action === 'preset-resave') {
+        if (!isSegment(spec.presetId)) return { kind: 'error', text: `${action}: invalid presetId` }
+        if (!Number.isSafeInteger(spec.expectedRevision) || spec.expectedRevision < 1) return { kind: 'error', text: `${action}: expectedRevision must be positive` }
+        if (action === 'preset-rename') {
+          const result = await library.rename({ scope: spec.scope, presetId: spec.presetId, workspaceKey, expectedRevision: spec.expectedRevision, name: spec.name })
+          return { kind: 'success', text: JSON.stringify(result) }
+        }
+        if (spec.from !== 'draft' && spec.from !== 'applied') return { kind: 'error', text: 'preset-resave: from must be draft or applied' }
+        if (spec.from === 'draft' && ![spec.skills, spec.mcpServers, spec.unresolvedRefs].every(Array.isArray)) {
+          return { kind: 'error', text: JSON.stringify({ status: 'invalid-selection' }) }
+        }
+        const store = wiring.openStore()
+        const sets = spec.from === 'applied' ? { skills: [], mcpServers: [], unresolvedRefs: [] } : draftSelectionSets(spec)
+        const withSource = spec.from === 'applied' ? appliedPresetSource(spec, sets, store, call.agent, call.options) : undefined
+        const result = await library.resave({
+          scope: spec.scope, presetId: spec.presetId, workspaceKey, expectedRevision: spec.expectedRevision,
+          selection: sets, withSource,
+        })
+        return { kind: 'success', text: JSON.stringify(result) }
+      }
+      if (spec.from !== 'draft' && spec.from !== 'applied') return { kind: 'error', text: 'preset-save: from must be draft or applied' }
+      if (typeof spec.name !== 'string' || !spec.name.length) return { kind: 'error', text: 'preset-save: name must be non-empty' }
+      if (spec.expectedRevision !== undefined && spec.from === 'draft' && ![spec.skills, spec.mcpServers, spec.unresolvedRefs].every(Array.isArray)) {
+        return { kind: 'error', text: JSON.stringify({ status: 'invalid-selection' }) }
+      }
+      const store = wiring.openStore()
+      const sets = spec.from === 'applied' ? { skills: [], mcpServers: [], unresolvedRefs: [] } : draftSelectionSets(spec)
+      const selection = { skills: sets.skills, mcpServers: sets.mcpServers, unresolvedRefs: sets.unresolvedRefs }
+      const withSource = spec.from === 'applied' ? appliedPresetSource(spec, sets, store, call.agent, call.options) : undefined
+      if (spec.expectedRevision !== undefined) {
+        if (!isSegment(spec.presetId)) return { kind: 'error', text: 'preset-save: edit needs presetId' }
+        const result = await library.edit({ scope: spec.scope, presetId: spec.presetId, workspaceKey,
+          expectedRevision: spec.expectedRevision, mutate: () => ({ name: spec.name, selection }), withSource })
+        return { kind: 'success', text: JSON.stringify(result) }
+      }
+      const result = await library.create({ scope: spec.scope, presetId: spec.presetId, workspaceKey,
+        document: { name: spec.name, selection }, onNameConflict: spec.onNameConflict ?? 'cancel', replaceTarget: spec.replaceTarget, withSource })
+      return { kind: 'success', text: JSON.stringify(result) }
+    } catch (cause) {
+      return { kind: 'error', text: `capabilities ${action} failed: ${message(cause)}` }
+    }
+  }
+
+  /** preset-load: load one preset document; the client stages its selection. */
+  async function presetLoad(spec, call) {
+    try {
+      const scopeError = presetScopeError(spec)
+      if (scopeError) return scopeError
+      if (!isSegment(spec.presetId)) return { kind: 'error', text: 'capabilities preset-load: presetId must be a valid store segment' }
+      const workspaceKey = workspaceKeyOf(call.options)
+      if (spec.scope === 'workspace' && !isSegment(workspaceKey)) return noWorkspaceError()
+      const library = createPresetLibrary({ store: wiring.openStore() })
+      const loaded = await library.load(spec.scope, spec.presetId, workspaceKey)
+      if (loaded.kind !== 'ok') return { kind: 'success', text: JSON.stringify({ status: loaded.kind }) }
+      return { kind: 'success', text: JSON.stringify({ status: 'ok', revision: loaded.revision, document: loaded.document }) }
+    } catch (cause) {
+      return { kind: 'error', text: `capabilities preset-load failed: ${message(cause)}` }
+    }
+  }
+
+  /** preset-delete: delete under CAS; a stale revision conflicts. */
+  async function presetDelete(spec, call) {
+    try {
+      const scopeError = presetScopeError(spec)
+      if (scopeError) return scopeError
+      if (!isSegment(spec.presetId)) return { kind: 'error', text: 'capabilities preset-delete: presetId must be a valid store segment' }
+      if (!Number.isSafeInteger(spec.expectedRevision) || spec.expectedRevision < 0) {
+        return { kind: 'error', text: 'capabilities preset-delete: expectedRevision must be a non-negative integer' }
+      }
+      const workspaceKey = workspaceKeyOf(call.options)
+      if (spec.scope === 'workspace' && !isSegment(workspaceKey)) return noWorkspaceError()
+      const library = createPresetLibrary({ store: wiring.openStore() })
+      const result = await library.remove({ scope: spec.scope, presetId: spec.presetId, workspaceKey, expectedRevision: spec.expectedRevision })
+      return { kind: 'success', text: JSON.stringify(result) }
+    } catch (cause) {
+      return { kind: 'error', text: `capabilities preset-delete failed: ${message(cause)}` }
+    }
+  }
+
+  /**
+   * preset-export: format:'document' is the v1 portable document (verbatim
+   * via library.exportPreset — inspect/backup); the default 'package' is the
+   * D6 version-2 package: remote Skills as portable refs, workspace/local
+   * Skills as bundled content, builtin Skills by name, managed MCP as
+   * {identity,label}.
+   */
+  async function presetExport(spec, call) {
+    try {
+      const scopeError = presetScopeError(spec)
+      if (scopeError) return scopeError
+      if (!isSegment(spec.presetId)) return { kind: 'error', text: 'capabilities preset-export: presetId must be a valid store segment' }
+      const format = spec.format ?? 'package'
+      if (format !== 'package' && format !== 'document') {
+        return { kind: 'error', text: 'capabilities preset-export: format must be "package" | "document"' }
+      }
+      const workspaceKey = workspaceKeyOf(call.options)
+      if (spec.scope === 'workspace' && !isSegment(workspaceKey)) return noWorkspaceError()
+      const library = createPresetLibrary({ store: wiring.openStore() })
+      if (format === 'document') {
+        const exported = await library.exportPreset(spec.scope, spec.presetId, workspaceKey)
+        return { kind: 'success', text: JSON.stringify(exported) }
+      }
+      const loaded = await library.load(spec.scope, spec.presetId, workspaceKey)
+      if (loaded.kind !== 'ok') return { kind: 'success', text: JSON.stringify({ status: loaded.kind }) }
+      // Pack against the live inventory (Skill file content comes from the
+      // matched candidates' locators) and the managed registry (MCP labels).
+      const inventoryResult = await wiring.inventory(call.options)
+      const candidates = Array.isArray(inventoryResult?.candidates) ? inventoryResult.candidates : []
+      const registry = createMcpRegistry({ store: wiring.openStore() })
+      const record = await registry.read()
+      /** @type {Record<string, string>} */
+      const labels = {}
+      if (record.kind === 'ok') for (const entry of Object.values(record.servers)) labels[entry.identity] = entry.label
+      const source = /** @type {Record<string, unknown>} */ (loaded.document ?? {})
+      const packed = await wiring.packPresetPackage({ name: source.name, selection: source.selection }, {
+        candidates,
+        mcpLabels: identity => labels[identity],
+      })
+      if (!packed.ok) return { kind: 'error', text: JSON.stringify({ status: 'rejected', reason: packed.reason }) }
+      return { kind: 'success', text: JSON.stringify({ status: 'ok', format: 'package', document: packed.package }) }
+    } catch (cause) {
+      return { kind: 'error', text: `capabilities preset-export failed: ${message(cause)}` }
+    }
+  }
+
+  return {
+    presets,
+    'preset-save': (spec, call) => presetSaveLike('preset-save', spec, call),
+    'preset-rename': (spec, call) => presetSaveLike('preset-rename', spec, call),
+    'preset-resave': (spec, call) => presetSaveLike('preset-resave', spec, call),
+    'preset-load': presetLoad,
+    'preset-delete': presetDelete,
+    'preset-export': presetExport,
+  }
+}

package/src/capabilities/preset-package.js

@@ -29,7 +29,13 @@
 import { readFile, readdir, realpath, stat } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
 import { createSkillIdentity, skillIdentityKey } from './skill-identity.js'
-import { validateMcpRef, validateSkillRef } from './portable-refs.js'
+import { validateMcpRef, validateSkillRef, bindImportedSelection, validatePortableDocument } from './portable-refs.js'
+import { createPresetLibrary, workspaceKeyOf, presetScopeError, noWorkspaceError } from './preset-library.js'
+import { installBundledSkills } from './preset-package-install.js'
+import { inspectPresetNamespace } from './store/enumerate.js'
+import { createMcpRegistry } from './mcp-registry.js'
+import { isSegment } from './store/paths.js'
+import { AUDIT_TYPES } from '../shared/audit.js'
 
 export const PACKAGE_VERSION = 2
 export const PACKAGE_LIMITS = Object.freeze({ documentBytes: 8 * 1024 * 1024, fileBytes: 512 * 1024, filesPerSkill: 256 })
@@ -485,3 +491,208 @@ export async function packPresetPackage(input, deps = {}) {
   if (!verdict.ok) return { ok: false, reason: verdict.reason }
   return { ok: true, package: pkg }
 }
+
+// ---- /capabilities preset-import verb (capabilities-deepening D2) -----------
+// The preset-import verb body and its D6 version-2 orchestration, moved
+// verbatim out of the handler into the module that owns the package contract
+// (validatePresetPackage/bindPackageSelection/planPackageInstall/
+// packPresetPackage above). Per-invocation state arrives through the `call`
+// argument ({ agent, options }); the handler's former closures are injected in
+// `wiring`. The install target roots still resolve through the injected
+// skillRootsFor.
+
+/**
+ * The /capabilities preset-import verb body. `wiring`:
+ * @param {{
+ *   openStore: () => any,
+ *   inventory: (options: any) => Promise<any>,
+ *   skillRootsFor: (options: any) => Promise<any>,
+ *   audit: (session: any, type: string, data?: unknown) => void,
+ * }} wiring
+ */
+export function createPackageVerbs(wiring) {
+  /**
+   * D6 version-2 package import (tasks 6.2/6.3). Phase one (dryRun:true) is
+   * a read-only summary — the exact install targets, file counts, unresolved
+   * refs and collisions, ZERO writes. Phase two (confirmed, onCollision
+   * default 'cancel') installs the bundled Skills into the resolved roots
+   * and then commits the preset record by CAS. A poison package is rejected
+   * atomically: nothing is written, no preset is created, the reason is
+   * named. Installed Skills stay UNSELECTED in every established set —
+   * selection remains a later draft + Apply.
+   */
+  const importPresetPackage = async (spec, call) => {
+    const verdict = validatePresetPackage(spec.document)
+    if (!verdict.ok) return { kind: 'error', text: JSON.stringify({ status: 'rejected', reason: verdict.reason }) }
+    if (spec.dryRun !== undefined && typeof spec.dryRun !== 'boolean') {
+      return { kind: 'error', text: 'capabilities preset-import: dryRun must be a boolean' }
+    }
+    const onCollision = spec.onCollision ?? 'cancel'
+    if (onCollision !== 'cancel' && onCollision !== 'replace' && onCollision !== 'coexist') {
+      return { kind: 'error', text: 'capabilities preset-import: onCollision must be "cancel" | "replace" | "coexist"' }
+    }
+    const workspaceKey = workspaceKeyOf(call.options)
+    if (spec.scope === 'workspace' && !isSegment(workspaceKey)) return noWorkspaceError()
+    const pkg = /** @type {any} */ (spec.document)
+    const store = wiring.openStore()
+    // Local binding context: the managed MCP identities this machine
+    // configured, the builtin names it actually has, and the D6 install roots
+    // (project = this workspace, user = user root) via the existing
+    // skill-inventory root resolution.
+    const registry = createMcpRegistry({ store })
+    const record = await registry.read()
+    const localMcpIdentities = record.kind === 'ok' ? Object.keys(record.servers) : []
+    const bound = bindPackageSelection(pkg, { localMcpIdentities })
+    const inventoryResult = await wiring.inventory(call.options)
+    const candidates = Array.isArray(inventoryResult?.candidates) ? inventoryResult.candidates : []
+    const builtinNames = new Set()
+    for (const candidate of candidates) {
+      const identity = /** @type {Record<string, any>} */ (candidate)?.identity
+      if (identity?.scope === 'weir-builtin' && typeof identity.name === 'string') builtinNames.add(identity.name)
+    }
+    const missingBuiltin = pkg.builtin.filter(name => !builtinNames.has(name))
+    const roots = await wiring.skillRootsFor(call.options)
+    const targetRoots = {
+      project: roots.find(root => root.source === 'project-dsh')?.path ?? null,
+      user: roots.find(root => root.source === 'user-dsh')?.path ?? null,
+    }
+    const plan = await planPackageInstall(pkg, { roots: targetRoots })
+    const carried = [
+      ...bound.unresolvedRefs,
+      ...missingBuiltin.map(name => ({ kind: 'skill', ref: { name, source: 'builtin' } })),
+    ]
+    if (spec.dryRun === true) {
+      const view = await inspectPresetNamespace(store, spec.scope, workspaceKey)
+      if (view.status !== 'ok') return { kind: 'error', text: JSON.stringify(view) }
+      const name = typeof spec.name === 'string' && spec.name.length ? spec.name : pkg.name
+      const conflicts = view.names.get(name) ?? []
+      const presetConflict = conflicts.length ? { with: conflicts[0], withRevision: view.activeById.get(conflicts[0]).revision, duplicates: conflicts.length > 1 } : null
+      return { kind: 'success', text: JSON.stringify({ status: 'dry-run', install: plan.install, unresolved: carried, collisions: plan.collisions, presetConflict }) }
+    }
+    // Confirmed: the install is this import's explicit main effect.
+    const neededScopes = [...new Set(pkg.bundled.map(entry => entry.targetScope))]
+    const missingRoot = neededScopes.find(scope => targetRoots[scope] === null)
+    if (missingRoot !== undefined) {
+      return { kind: 'error', text: JSON.stringify({ status: 'no-target-root', targetScope: missingRoot }) }
+    }
+    const name = typeof spec.name === 'string' && spec.name.length ? spec.name : pkg.name
+    const requestedId = spec.presetId
+    if (requestedId !== undefined && requestedId !== null && !isSegment(requestedId)) return { kind: 'error', text: `capabilities preset-import: invalid presetId ${JSON.stringify(requestedId)}` }
+    const library = createPresetLibrary({ store })
+    const guardedResult = await library.withNamespace(spec.scope, workspaceKey, async guarded => {
+      const request = { scope: spec.scope, presetId: requestedId, workspaceKey,
+        document: { name, selection: { skills: [], mcpServers: [], unresolvedRefs: [] } },
+        onNameConflict: spec.onNameConflict ?? 'cancel', replaceTarget: spec.replaceTarget }
+      const admission = await guarded.checkCreate(request)
+      if (admission.status !== 'ready') return { kind: 'success', text: JSON.stringify(admission) }
+      let install
+      try {
+        install = await installBundledSkills(pkg.bundled, { roots: targetRoots, onCollision }, {
+          audit: data => wiring.audit(call.agent.session, AUDIT_TYPES.capabilityPresetImport, data),
+        })
+        if (!install.ok) {
+          // installBundledSkills already rolled back what it wrote.
+          return { kind: 'error', text: JSON.stringify({ status: 'install-failed', reason: install.reason, rolledBack: install.rolledBack }) }
+        }
+        // Resolve what is now local (installed bundled Skills, present builtin
+        // names) against a FRESH inventory: the preset record names real
+        // identities; everything else stays unresolved.
+        const afterResult = await wiring.inventory(call.options)
+        const afterCandidates = Array.isArray(afterResult?.candidates) ? afterResult.candidates : []
+        const resolveLocal = (scope, name) => {
+          const matches = []
+          for (const candidate of afterCandidates) {
+            const identity = /** @type {Record<string, any>} */ (candidate)?.identity
+            if (identity?.scope === scope && identity.name === name) matches.push(identity)
+          }
+          // An ambiguous name stays unresolved rather than guessing.
+          return matches.length === 1 ? matches[0] : null
+        }
+        const resolvedSkills = []
+        const unresolvedRefs = [...carried]
+        for (const entry of install.installed) {
+          const identity = resolveLocal(entry.targetScope === 'project' ? 'project' : 'user', entry.target)
+          if (identity) resolvedSkills.push(identity)
+          else unresolvedRefs.push({ kind: 'skill', ref: { name: entry.target, targetScope: entry.targetScope, source: 'bundled' } })
+        }
+        for (const entry of install.collisions) {
+          unresolvedRefs.push({ kind: 'skill', ref: { name: entry.name, targetScope: entry.targetScope, source: 'bundled', collision: entry.decision } })
+        }
+        for (const name of pkg.builtin) {
+          if (missingBuiltin.includes(name)) continue
+          const identity = resolveLocal('weir-builtin', name)
+          if (identity) resolvedSkills.push(identity)
+          else unresolvedRefs.push({ kind: 'skill', ref: { name, source: 'builtin' } })
+        }
+        const document = { name, selection: { skills: resolvedSkills, mcpServers: bound.mcpServers, unresolvedRefs } }
+        const result = await guarded.create({ ...request, document })
+        return { kind: 'success', text: JSON.stringify({
+          ...result,
+          bound: { mcpServers: bound.mcpServers.length, unresolvedRefs: unresolvedRefs.length },
+          installed: install.installed,
+          collisions: install.collisions,
+          unresolved: unresolvedRefs,
+          ...(result.status !== 'created' && result.status !== 'edited' ? { presetStatus: 'unconfirmed' } : {}),
+        }) }
+      } catch (cause) {
+        return { kind: 'error', text: JSON.stringify({ status: 'preset-unconfirmed',
+          presetStatus: 'unconfirmed', installed: install?.installed ?? [], reason: cause instanceof Error ? cause.message : String(cause) }) }
+      }
+    })
+    return guardedResult?.kind === 'success' || guardedResult?.kind === 'error'
+      ? guardedResult : { kind: 'success', text: JSON.stringify(guardedResult) }
+  }
+
+  /**
+   * Import a portable document: validate atomically first (a poison document
+   * is rejected with zero writes), then bind only the identities the local
+   * MCP registry already configured — everything else stays an unresolved
+   * ref. Nothing is installed, started or connected here.
+   */
+  async function presetImport(spec, call) {
+    try {
+      const scopeError = presetScopeError(spec)
+      if (scopeError) return scopeError
+      // Version dispatch (D6): a version-2 package takes the two-phase path
+      // (dryRun summary → confirmed install + CAS preset create). Everything
+      // else keeps the v1 portable path, whose own gate rejects unknown
+      // versions atomically.
+      if (spec.document !== null && typeof spec.document === 'object' && !Array.isArray(spec.document)
+        && /** @type {Record<string, unknown>} */ (spec.document).version === 2) {
+        return await importPresetPackage(spec, call)
+      }
+      const verdict = validatePortableDocument(spec.document)
+      if (!verdict.ok) return { kind: 'error', text: JSON.stringify({ status: 'rejected', reason: verdict.reason }) }
+      const workspaceKey = workspaceKeyOf(call.options)
+      if (spec.scope === 'workspace' && !isSegment(workspaceKey)) return noWorkspaceError()
+      const presetId = spec.presetId ?? /** @type {Record<string, unknown>} */ (spec.document).presetId
+      if (!isSegment(presetId)) return { kind: 'error', text: 'capabilities preset-import: presetId must be a valid store segment' }
+      const name = typeof spec.name === 'string' && spec.name.length ? spec.name : /** @type {Record<string, unknown>} */ (spec.document).name
+      const store = wiring.openStore()
+      const registry = createMcpRegistry({ store })
+      const record = await registry.read()
+      const localMcpIdentities = record.kind === 'ok' ? Object.keys(record.servers) : []
+      const selection = /** @type {Record<string, unknown>} */ (/** @type {Record<string, unknown>} */ (spec.document).selection ?? {})
+      const bound = bindImportedSelection(selection, { localMcpIdentities })
+      const document = {
+        name,
+        selection: {
+          skills: [],
+          mcpServers: bound.mcpServers,
+          unresolvedRefs: [
+            ...(Array.isArray(selection.unresolvedRefs) ? selection.unresolvedRefs : []),
+            ...bound.unresolvedRefs,
+          ],
+        },
+      }
+      const library = createPresetLibrary({ store })
+      const result = await library.create({ scope: spec.scope, presetId, workspaceKey, document,
+        onNameConflict: spec.onNameConflict ?? 'cancel', replaceTarget: spec.replaceTarget })
+      return { kind: 'success', text: JSON.stringify({ ...result, bound: { mcpServers: bound.mcpServers.length, unresolvedRefs: bound.unresolvedRefs.length } }) }
+    } catch (cause) {
+      return { kind: 'error', text: `capabilities preset-import failed: ${cause instanceof Error ? cause.message : String(cause)}` }
+    }
+  }
+
+  return { 'preset-import': presetImport }
+}

package/src/capabilities/same-name-policy.js

@@ -1,27 +1,6 @@
-// Task 10.3 of the session-capability-manager change: same-name listing and
-// the "no silent substitute / no silent overwrite" rules. Every same-name
-// entry is listed with its scope, provenance and discovery precedence —
-// informational only, never an authorization signal. A missing reference is
-// never satisfied by a same-named entry, and installing into an occupied
-// name writes ONLY after an explicit replace / coexist-distinct / cancel
-// decision.
-
-/**
- * Rank the entries for the informational listing (10.3): discovery
- * precedence is REPORTED, never interpreted as authorization.
- * @param {Array<{ name: string, scope?: string, rank?: number, provenance?: unknown }>} entries
- */
-export function sameNameListing(entries) {
-  return entries
-    .filter(entry => entry && typeof entry.name === 'string')
-    .map(entry => ({
-      name: entry.name,
-      scope: entry.scope ?? 'unknown',
-      provenance: entry.provenance ?? null,
-      precedence: Number.isSafeInteger(entry.rank) ? entry.rank : null,
-    }))
-    .sort((a, b) => (a.precedence ?? Number.MAX_SAFE_INTEGER) - (b.precedence ?? Number.MAX_SAFE_INTEGER) || a.scope.localeCompare(b.scope))
-}
+// Task 10.3 of the session-capability-manager change: the "no silent
+// overwrite" rule. Installing into an occupied name writes ONLY after an
+// explicit replace / coexist-distinct / cancel decision.
 
 /**
  * The install-into-occupied-name decision (10.3): the default is CANCEL —
@@ -42,20 +21,3 @@ export function installTargetFor({ name, occupied, decision = 'cancel', targetNa
   }
   return { write: false, target: null, status: 'cancelled' }
 }
-
-/**
- * A missing reference is never satisfied by a same-named entry (10.3): the
- * resolution of a ref matches by IDENTITY, and an identity mismatch is
- * always unresolved even when the display name matches.
- * @param {{ name?: string, identity?: unknown }} wanted @param {{ name?: string, identity?: unknown }} candidate
- * @param {(identity: unknown) => string} identityKeyOf
- */
-export function refSatisfiedBy(wanted, candidate, identityKeyOf) {
-  if (wanted?.identity === undefined || wanted.identity === null) return false
-  if (candidate?.identity === undefined || candidate.identity === null) return false
-  try {
-    return identityKeyOf(wanted.identity) === identityKeyOf(candidate.identity)
-  } catch {
-    return false
-  }
-}