orizu 0.5.20 → 0.5.21

package/src/index.ts

@@ -66,11 +66,15 @@ import {
   workspaceExists,
 } from './workspace.js'
 import { connectorsCommand } from './connectors-cli.js'
+import { modelConfigsCommand } from './model-configs-cli.js'
 import { ARTIFACT_MAX_BYTES, runnerOptimizerCommand } from './artifact-pull.js'
 import { killSwitchCommand } from './kill-switch-cli.js'
 import { egressAllowlistCommand } from './egress-allowlist-cli.js'
 import { acceptScoreRunCommand } from './scores-accept-cli.js'
 import { listOptimizationRunsCommand } from './optimizations-list-cli.js'
+import { promoteOptimizationCommand } from './optimizations-promote-cli.js'
+import { scorersCommand } from './scorers-cli.js'
+import { verifyScorerParityCommand } from './scorers-verify-parity.js'
 import {
   archiveArtifactCommand,
   listAssignmentsCommand,
@@ -85,9 +89,12 @@ import { workbenchCommand } from './workbench-cli.js'
 import { hostedCommand } from './hosted-session-cli.js'
 import { workspaceSyncCommand } from './workspace-sync.js'
 import { runGitCredentialInvocation } from './git-credential.js'
+import { instructionSetsCommand, syncToDisk } from './instruction-sets-cli.js'; export { loadInstructionSet } from './instruction-set-loader.js'
+import { runnerInputInstructionSet, runnerInputPrompt, runnerInstructionSetSyncSet, type RunnerInstructionSet } from './runner-instruction-set-contract.js'
 import { pushPromptDraft } from './prompt-draft-push.js'
 import { readMarkdownReportInput } from './markdown-report-input.js'
 import { promptPushErrorMessage, promptReportCommand } from './prompt-report-cli.js'
+import { setPromptLabel } from './prompt-label-cli.js'
 import { printPromptSummaryTable } from './prompt-summary-table.js'
 import type {
   CliLengthMeasurementUnavailableReason,
@@ -107,8 +114,10 @@ import {
 import { diffCommentsCommand } from './diff-comments-cli.js'
 import { exportOptimizationRunCommand } from './optimization-export-cli.js'
 import { dispatchGepaEngine } from './gepa-engine-dispatch.js'
+import { resolveGepaInstructionSetProfileVersion } from './instruction-set-gepa-launch.js'
 import { getGepaPythonCommand } from './gepa-python-command.js'
 import { getGepaPythonPathEntries } from './gepa-python-paths.js'
+import { prepareSkilledProposerLaunch } from './skilled-proposer-launch.js'
 
 export { parseJsonResponse, sanitizeTerminalText } from './json-response.js'
 
@@ -195,6 +204,10 @@ interface PromptSummary {
   lengthStatsUnavailableReason?: CliLengthMeasurementUnavailableReason
   lengthStatsVersionId?: string
   lengthStatsVersionNumber?: number
+  owner?: {
+    instructionSetSlug: string
+    componentKey: string
+  } | null
 }
 
 interface TaskReportPayload {
@@ -229,7 +242,7 @@ interface ScoreSubmitInput {
 
 interface RunnerExecContext {
   prompt: {
-    body: string | null
+    body?: string | null
     bodyKind: string
     providerSettings: Record<string, unknown>
     promptId?: string
@@ -241,6 +254,7 @@ interface RunnerExecContext {
     metricKey: string
     higherIsBetter: boolean
   } | null
+  instructionSet?: RunnerInstructionSet
   rows: Array<{
     id: string
     row: Record<string, unknown>
@@ -1634,6 +1648,10 @@ async function pullPromptArtifact(kind: 'prompt' | 'judge') {
       metricKey: string
       higherIsBetter: boolean
     }>
+    owner?: {
+      instructionSetSlug: string
+      componentKey: string
+    } | null
   }>(response, `${kind} pull`)
 
   const targetDir = expandHomePath(outDir)
@@ -1720,6 +1738,7 @@ async function pullPromptArtifact(kind: 'prompt' | 'judge') {
       scorer_version_id: data.scorerVersionId || undefined,
       scorer_version_ids: scorerVersions.map(item => item.id),
       path: targetDir,
+      owner: data.owner || undefined,
     })
     return
   }
@@ -1735,73 +1754,17 @@ async function pullPromptArtifact(kind: 'prompt' | 'judge') {
       `Warning: prompt version ${sanitizeTerminalText(data.version.id)} does not map to an executable scorer version.`
     )
   }
-}
-
-async function setPromptLabel() {
-  const promptName = getPositionalArg(3)
-  const label = getPositionalArg(4)
-  const project = getArg('--project') || await resolveProjectSlug(null)
-  const promptVersionId = getArg('--version')
-
-  if (!promptName || !label || !promptVersionId) {
-    throw new Error('Usage: orizu prompts labels set <prompt-name> <label> --version <prompt-version-id> [--project <team/project>] [--json]')
-  }
-
-  const response = await authedFetch(`/api/cli/prompts/labels?project=${encodeURIComponent(project)}`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      promptName,
-      label,
-      promptVersionId,
-    }),
-  })
-
-  if (!response.ok) {
-    throw new Error(`Failed to set prompt label: ${await response.text()}`)
-  }
-
-  const data = await parseJsonResponse<Record<string, unknown>>(response, 'Prompt label set')
-  if (hasJsonFlag()) {
-    printJson(data)
-    return
+  if (kind === 'prompt' && data.owner) {
+    printLine(
+      `Owner: ${sanitizeTerminalText(data.prompt.name)} (${sanitizeTerminalText(data.prompt.id)}) -> ` +
+      `${sanitizeTerminalText(data.owner.instructionSetSlug)} / ${sanitizeTerminalText(data.owner.componentKey)}`
+    )
   }
-
-  printLine(`Moved ${sanitizeTerminalText(label)} to ${sanitizeTerminalText(promptVersionId)}`)
 }
 
-async function setPromptArchivedState(archived: boolean) {
-  const promptRef = getPositionalArg(2)
-  const project = getArg('--project') || await resolveProjectSlug(null)
-  const command = archived ? 'archive' : 'restore'
-
-  if (!promptRef) {
-    throw new Error(`Usage: orizu prompts ${command} <prompt-id-or-name> --project <team/project> [--json]`)
-  }
-
-  const response = await authedFetch(`/api/cli/prompts/${encodeURIComponent(promptRef)}?project=${encodeURIComponent(project)}`, {
-    method: 'PATCH',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ archived }),
-  })
-
-  if (!response.ok) {
-    throw new Error(`Failed to ${command} prompt: ${await response.text()}`)
-  }
-
-  const data = await parseJsonResponse<{
-    prompt: {
-      id: string
-      name: string
-      status: string
-    }
-  }>(response, `Prompt ${command}`)
-  if (hasJsonFlag()) {
-    printJson(data)
-    return
-  }
-
-  printLine(`${archived ? 'Archived' : 'Restored'} prompt ${sanitizeTerminalText(data.prompt.name)} (${sanitizeTerminalText(data.prompt.id)})`)
+function refusePromptMutation(replacement: string): never {
+  process.exitCode = 1
+  throw new Error(`Use: orizu instructions ${replacement}`)
 }
 
 async function bindPromptScorer(role: 'headline' | 'tracked') {
@@ -1830,13 +1793,25 @@ async function bindPromptScorer(role: 'headline' | 'tracked') {
     throw new Error(`Failed to bind prompt scorer: ${await response.text()}`)
   }
 
-  const data = await parseJsonResponse<Record<string, unknown>>(response, 'Prompt scorer bind')
+  const data = await parseJsonResponse<{
+    promptScorer: Record<string, unknown>
+    owner?: {
+      instructionSetSlug: string
+      componentKey: string
+    }
+  }>(response, 'Prompt scorer bind')
   if (hasJsonFlag()) {
     printJson(data)
     return
   }
 
   printLine(`${role === 'headline' ? 'Set headline' : 'Added'} scorer ${sanitizeTerminalText(scorerVersionId)} for ${sanitizeTerminalText(promptId)}`)
+  if (data.owner) {
+    printLine(
+      `Owner: ${sanitizeTerminalText(promptId)} -> ` +
+      `${sanitizeTerminalText(data.owner.instructionSetSlug)} / ${sanitizeTerminalText(data.owner.componentKey)}`
+    )
+  }
 }
 
 function getPositionalArg(index: number): string | null {
@@ -2522,14 +2497,12 @@ async function updateOptimizationRunLifecycle(action: OptimizationLifecycleActio
 
 // ALI-1073 list moved to optimizations-list-cli.ts (line ratchet, ALI-976);
 // ALI-1175 labels its best scores as agent-reported evidence there.
-
 async function runGepaOptimization() {
   const project = getArg('--project') || await resolveProjectSlug(null)
   const baseUrl = getBaseUrl()
   const runGepa = getGepaPythonCommand(cliArgs.slice(2), process.env)
   const python = runGepa.python
   let forwardedArgs = runGepa.args
-
   // ALI-1159 (ADR-007): GEPA executes ad-hoc local runner dirs while
   // attributing records to registered runner version ids — verify the bytes
   // ARE those versions before the optimizer spawns. Scans the forwarded argv
@@ -2538,7 +2511,6 @@ async function runGepaOptimization() {
   // so a post-hash mutation of the original dirs cannot change what runs.
   const verified = await verifyGepaRunnerDirsFromArgs(forwardedArgs)
   forwardedArgs = verified.args
-
   let result
   let selectedEngine = 'official'
   try {
@@ -2548,11 +2520,9 @@ async function runGepaOptimization() {
     // rotation crossing the hash + lookup round-trips cannot hand the child a
     // stale bearer.
     const token = resolveAuthTokenForBaseUrl(baseUrl)
-
     if (!forwardedArgs.includes('--project')) {
       forwardedArgs = ['--project', project, ...forwardedArgs]
     }
-
     const dispatch = dispatchGepaEngine(forwardedArgs, project, {
       ...process.env,
       ORIZU_API_URL: baseUrl,
@@ -2562,16 +2532,17 @@ async function runGepaOptimization() {
       PYTHONPATH: getGepaPythonPathEntries(process.env.PYTHONPATH).join(delimiter),
       PYTHONUNBUFFERED: process.env.PYTHONUNBUFFERED || '1',
     })
+    const instructionSetName = dispatch.environment.ORIZU_INSTRUCTION_SET_NAME
+    const modelConfigIdentity = dispatch.environment.ORIZU_MODEL_CONFIG_IDENTITY
+    const instructionSetProfileVersionId = instructionSetName && modelConfigIdentity
+      ? await resolveGepaInstructionSetProfileVersion(instructionSetName, modelConfigIdentity, project) : undefined
+    if (instructionSetProfileVersionId) dispatch.environment.ORIZU_INSTRUCTION_SET_PROFILE_VERSION_ID = instructionSetProfileVersionId
     selectedEngine = dispatch.engine
-
-    result = spawnSync(python, ['-m', dispatch.module, ...dispatch.args], {
-      stdio: 'inherit',
-      env: dispatch.environment,
-    })
+    const launch = prepareSkilledProposerLaunch(python, dispatch.engine, dispatch.environment)
+    result = spawnSync(launch.python, ['-m', dispatch.module, ...dispatch.args], { stdio: 'inherit', env: launch.environment })
   } finally {
     verified.cleanup()
   }
-
   if (result.error) {
     throw new Error(`${selectedEngine} GEPA engine failed: ${result.error.message}`, { cause: result.error })
   }
@@ -5777,7 +5748,7 @@ async function downloadAnnotations() {
   printLine(`Saved ${format.toUpperCase()} export to ${sanitizeTerminalText(filename)}`)
 }
 
-function readRunnerManifest(runnerDir: string): { command: string[]; supports_body_kind?: string[] } {
+export function readRunnerManifest(runnerDir: string): { command: string[]; supports_body_kind?: string[] } {
   const manifestPath = join(runnerDir, 'manifest.json')
   const raw = readSourceFile(manifestPath)
   const manifest = JSON.parse(raw) as {
@@ -5805,9 +5776,9 @@ function readRunnerManifest(runnerDir: string): { command: string[]; supports_bo
   }
 }
 
-const RUNNER_TIMEOUT_MS = 120_000
-const RUNNER_OUTPUT_MAX_BYTES = 2 * 1024 * 1024
-const RUNNER_ENV_ALLOWLIST = new Set([
+export const RUNNER_TIMEOUT_MS = 120_000
+export const RUNNER_OUTPUT_MAX_BYTES = 2 * 1024 * 1024
+export const RUNNER_ENV_ALLOWLIST = new Set([
   'PATH',
   'SystemRoot',
   'WINDIR',
@@ -5825,7 +5796,7 @@ const RUNNER_ENV_ALLOWLIST = new Set([
   'GOOGLE_API_KEY',
 ])
 
-function runnerSubprocessEnv(inputPath: string, outputPath: string): NodeJS.ProcessEnv {
+export function runnerSubprocessEnv(inputPath: string, outputPath: string, instructionSetDir?: string): NodeJS.ProcessEnv {
   const env = {} as NodeJS.ProcessEnv
   for (const key of RUNNER_ENV_ALLOWLIST) {
     const value = process.env[key]
@@ -5835,6 +5806,8 @@ function runnerSubprocessEnv(inputPath: string, outputPath: string): NodeJS.Proc
   }
   env.ORIZU_RUNNER_INPUT_PATH = inputPath
   env.ORIZU_RUNNER_OUTPUT_PATH = outputPath
+  delete env.ORIZU_INSTRUCTION_SET_DIR
+  if (instructionSetDir) env.ORIZU_INSTRUCTION_SET_DIR = instructionSetDir
   return env
 }
 
@@ -5847,7 +5820,7 @@ function boundedRunnerOutput(value: string | Buffer | null | undefined): string
   return `${buffer.subarray(0, RUNNER_OUTPUT_MAX_BYTES).toString('utf8')}\n[truncated]`
 }
 
-async function materializeRunnerVersion(runnerVersionId: string): Promise<{ runnerDir: string; cleanup: () => void }> {
+export async function materializeRunnerVersion(runnerVersionId: string): Promise<{ runnerDir: string; cleanup: () => void }> {
   const response = await authedFetch(`/api/cli/runner-versions/${encodeURIComponent(runnerVersionId)}/download`)
   if (!response.ok) {
     throw new Error(`Failed to download runner version: ${await response.text()}`)
@@ -5941,7 +5914,6 @@ async function runnersExec() {
       })()
     : await materializeRunnerVersion(resolvedRunnerVersionId)
   const runnerDir = materializedRunner.runnerDir
-
   try {
     assertSnapshotManifestConfined(runnerDir, runnerDirArg ? '--runner-dir' : '--runner-version')
     // Inside the try (codex round-6 P3): a bad manifest must not leak the dir.
@@ -5951,22 +5923,19 @@ async function runnersExec() {
         `Runner does not support prompt body kind '${context.prompt.bodyKind}'. Supported kinds: ${manifest.supports_body_kind.join(', ')}`
       )
     }
-
     const resultLines: string[] = []
     for (const row of context.rows) {
       const tempDir = mkdtempSync(join(tmpdir(), 'orizu-runner-'))
       const inputPath = join(tempDir, 'input.json')
       const outputPath = join(tempDir, 'output.json')
-
+      const instructionSetDir = context.instructionSet ? join(tempDir, 'instruction-set') : undefined
       try {
         const modelOutput = row.row.model_output ?? row.row.modelOutput ?? row.row.output ?? null
+        if (instructionSetDir && context.instructionSet) syncToDisk(instructionSetDir, runnerInstructionSetSyncSet(context.instructionSet))
         writeFileSync(inputPath, JSON.stringify({
           row: row.row,
-          prompt: {
-            body: context.prompt.body,
-            body_kind: context.prompt.bodyKind,
-            provider_settings: context.prompt.providerSettings,
-          },
+          prompt: runnerInputPrompt(context.prompt),
+          ...(context.instructionSet ? { instruction_set: runnerInputInstructionSet(context.instructionSet) } : {}),
           subject: scorerVersion
             ? {
                 type: 'scorer_row',
@@ -5994,7 +5963,7 @@ async function runnersExec() {
 
         const result = spawnSync(manifest.command[0], manifest.command.slice(1), {
           cwd: runnerDir,
-          env: runnerSubprocessEnv(inputPath, outputPath),
+          env: runnerSubprocessEnv(inputPath, outputPath, instructionSetDir),
           encoding: 'utf8',
           maxBuffer: RUNNER_OUTPUT_MAX_BYTES,
           timeout: RUNNER_TIMEOUT_MS,
@@ -6226,8 +6195,11 @@ export async function main(rawArgs = process.argv.slice(2)) {
   }
 
   if (command === 'prompts' && subcommand === 'push') {
-    await pushPromptArtifact('prompt')
-    return
+    if (getArg('--session')) {
+      await pushPromptArtifact('prompt')
+      return
+    }
+    refusePromptMutation('push <manifest> --project <team/project>')
   }
 
   if (
@@ -6241,17 +6213,25 @@ export async function main(rawArgs = process.argv.slice(2)) {
   }
 
   if (command === 'prompts' && subcommand === 'archive') {
-    await setPromptArchivedState(true)
-    return
+    refusePromptMutation('archive <slug-or-exact-name> --project <team/project>')
   }
 
   if (command === 'prompts' && subcommand === 'restore') {
-    await setPromptArchivedState(false)
-    return
+    refusePromptMutation('restore <slug-or-exact-name> --project <team/project>')
   }
 
   if (command === 'prompts' && subcommand === 'labels' && cliArgs[2] === 'set') {
-    await setPromptLabel()
+    if (getPositionalArg(4) === 'production') {
+      refusePromptMutation('profiles promote <set> --project <team/project> --model-config <identity> --version <n>')
+    }
+    await setPromptLabel({
+      getArg,
+      getPositionalArg,
+      json: hasJsonFlag(),
+      printJson,
+      printLine,
+      resolveProjectSlug,
+    })
     return
   }
 
@@ -6302,29 +6282,17 @@ export async function main(rawArgs = process.argv.slice(2)) {
     return
   }
 
-  if (command === 'scorers' && subcommand === 'list') {
-    await listScorers()
-    return
-  }
-
-  if (command === 'scorers' && subcommand === 'register') {
-    await registerScorer()
-    return
-  }
-
-  if (command === 'scorers' && subcommand === 'detail') {
-    await showScorerDetail()
-    return
-  }
-
-  if (command === 'scorers' && subcommand === 'labels' && cliArgs[2] === 'set') {
-    await setScorerLabel()
-    return
-  }
-
-  if (command === 'scorers' && subcommand === 'exec') {
-    await execScorer()
-    return
+  if (command === 'scorers') {
+    const scorersExit = await scorersCommand(cliArgs, {
+      list: listScorers, register: registerScorer, detail: showScorerDetail,
+      labelsSet: setScorerLabel, exec: execScorer,
+      verifyParity: args => verifyScorerParityCommand(args, {
+        json: hasJsonFlag(), print: printLine, printErr: printError,
+        materializeRunnerVersion, readRunnerManifest, runnerSubprocessEnv,
+        timeoutMs: RUNNER_TIMEOUT_MS, maxOutputBytes: RUNNER_OUTPUT_MAX_BYTES,
+      }),
+    })
+    if (scorersExit !== null) { process.exitCode = scorersExit; return }
   }
 
   if ((command === 'runners' || command === 'optimizers') && subcommand === 'push') {
@@ -6385,7 +6353,12 @@ export async function main(rawArgs = process.argv.slice(2)) {
     await listOptimizationRunsCommand(cliArgs.slice(2), { json: hasJsonFlag(), print: printLine, resolveProjectSlug })
     return
   }
-
+  if (command === 'optimizations' && subcommand === 'promote') {
+    await promoteOptimizationCommand(cliArgs.slice(2), {
+      json: hasJsonFlag(), print: printLine, resolveProjectSlug, fetcher: authedFetch,
+    })
+    return
+  }
   if (
     command === 'optimizations' &&
     (
@@ -6549,11 +6522,11 @@ export async function main(rawArgs = process.argv.slice(2)) {
   }
   if (command === 'git-credential') { process.exitCode = await runGitCredentialInvocation(cliArgs.slice(1), { stdin: readFileSync(0, 'utf8'), cwd: process.cwd(), print: printLine, printErr: printError }); return }
   if (command === 'github' && subcommand === 'link') { const noInput = hasArg('--no-input') || hasArg('--non-interactive') || !isInteractiveTerminal(); const team = getOptionalArgValue('--team') || (await resolveSetupTeam(null, noInput, false)).slug; await runGithubLink(team, { print: printLine, fetcher: authedFetch, openUrl: openInBrowser, confirm: (org) => askYesNo(`Connect this team to GitHub org '${org}'?`, true) }); return }
-  if (command === 'connectors' || command === 'manifests') {
-    const moduleCommand = command === 'connectors' ? connectorsCommand : manifestsCommand
-    process.exitCode = await moduleCommand(cliArgs.slice(1), { json: hasJsonFlag(), print: printLine, resolveProjectSlug })
+  if (command === 'connectors' || command === 'manifests' || command === 'model-configs') {
+    process.exitCode = await (command === 'connectors' ? connectorsCommand : command === 'manifests' ? manifestsCommand : modelConfigsCommand)(cliArgs.slice(1), { json: hasJsonFlag(), print: printLine, resolveProjectSlug })
     return
   }
+  if (command === 'instructions' || command === 'instruction-sets') { process.exitCode = await instructionSetsCommand(cliArgs.slice(1), { json: hasJsonFlag(), print: printLine, resolveProjectSlug }); return }
   if (command === 'team' && (subcommand === 'kill-agents' || subcommand === 'release-agents')) {
     process.exitCode = await killSwitchCommand(cliArgs.slice(1), { json: hasJsonFlag(), print: printLine, printErr: printError })
     return

package/src/instruction-set-gepa-launch.ts

@@ -0,0 +1,28 @@
+import { authedFetch } from './http.js'
+import { parseJsonResponse } from './json-response.js'
+
+interface InstructionSetResolution {
+  instructionSet?: {
+    default?: { profileVersionId?: string } | null
+    profiles?: Array<{
+      modelConfigIdentity?: string | null
+      production?: { profileVersionId?: string } | null
+    }>
+  }
+}
+
+/** Resolve the same production-or-default tuple served for a model identity. */
+export async function resolveGepaInstructionSetProfileVersion(
+  instructionSetName: string,
+  modelConfigIdentity: string,
+  project: string,
+): Promise<string> {
+  const response = await authedFetch(`/api/cli/instruction-sets/${encodeURIComponent(instructionSetName)}?project=${encodeURIComponent(project)}`)
+  if (!response.ok) throw new Error(`Instruction set resolution failed: ${await response.text()}`)
+  const payload = await parseJsonResponse<InstructionSetResolution>(response, 'Instruction set resolution')
+  const instructionSet = payload.instructionSet
+  const profile = instructionSet?.profiles?.find(candidate => candidate.modelConfigIdentity === modelConfigIdentity)
+  const profileVersionId = profile?.production?.profileVersionId || instructionSet?.default?.profileVersionId
+  if (!profileVersionId) throw new Error('instruction_set_profile_version_unresolvable')
+  return profileVersionId
+}

package/src/instruction-set-loader.ts

@@ -0,0 +1,37 @@
+import { existsSync, realpathSync, readFileSync, statSync } from 'node:fs'
+import { resolve, sep } from 'node:path'
+
+export class InstructionSetLoaderError extends Error {
+  constructor(readonly code: string) { super(code); this.name = 'InstructionSetLoaderError' }
+}
+
+interface Material { files: Record<string, string>; pinnedComponents?: Record<string, unknown> }
+interface Manifest { manifestVersion: number; name: string; shape: string[]; default: Material; profiles: Array<{ modelConfigIdentity: string; production: Material | null }>; filteredTo?: string[] }
+
+function inside(root: string, candidate: string) { return candidate === root || candidate.startsWith(`${root}${sep}`) }
+
+export function loadInstructionSet(directory: string, name: string, modelConfigIdentity: string): Record<string, string> {
+  const unresolvedRoot = resolve(directory, name)
+  if (!existsSync(unresolvedRoot) || !statSync(unresolvedRoot).isDirectory()) throw new InstructionSetLoaderError('instruction_set_not_synced')
+  const setRoot = realpathSync(unresolvedRoot)
+  const manifestPath = resolve(setRoot, 'manifest.json')
+  if (!existsSync(manifestPath)) throw new InstructionSetLoaderError('instruction_set_manifest_missing')
+  let manifest: Manifest
+  try { manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as Manifest } catch { throw new InstructionSetLoaderError('instruction_set_manifest_missing') }
+  if (manifest.manifestVersion !== 1) throw new InstructionSetLoaderError('instruction_set_manifest_version_unsupported')
+  if (manifest.filteredTo && !manifest.filteredTo.includes(modelConfigIdentity)) throw new InstructionSetLoaderError('instruction_set_profile_not_synced')
+  const selected = manifest.profiles.find(profile => profile.modelConfigIdentity === modelConfigIdentity)?.production || manifest.default
+  const result: Record<string, string> = {}
+  for (const key of manifest.shape) {
+    if (selected.pinnedComponents?.[key]) throw new InstructionSetLoaderError('instruction_set_component_unavailable')
+    const relativePath = selected.files?.[key]
+    if (!relativePath) throw new InstructionSetLoaderError('instruction_set_profile_key_missing')
+    const unresolvedPath = resolve(setRoot, relativePath)
+    if (!inside(setRoot, unresolvedPath)) throw new InstructionSetLoaderError('instruction_set_path_unsafe')
+    let path: string
+    try { path = realpathSync(unresolvedPath) } catch { throw new InstructionSetLoaderError('instruction_set_component_unreadable') }
+    if (!inside(setRoot, path)) throw new InstructionSetLoaderError('instruction_set_path_unsafe')
+    try { result[key] = readFileSync(path, 'utf8') } catch { throw new InstructionSetLoaderError('instruction_set_component_unreadable') }
+  }
+  return result
+}

package/src/instruction-set-manifest.ts

@@ -0,0 +1,120 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import { dirname, isAbsolute, relative, resolve } from 'node:path'
+import { createHash } from 'node:crypto'
+
+export interface InstructionSetComponent { key: string; modelConfig?: string; text: string }
+export interface InstructionSetManifest { name: string; description?: string | null; shape: string[]; components: InstructionSetComponent[] }
+
+// Keep file-backed component reads within the same text budget used by prompt
+// tooling; request assembly never asks Node to allocate an unbounded body.
+export const MAX_INSTRUCTION_SET_COMPONENT_BYTES = 512 * 1024
+
+const fail = (code: string): never => { throw new Error(code) }
+const sha256 = (value: string) => createHash('sha256').update(value, 'utf8').digest('hex')
+
+function hasPinnedComponents(material: unknown): boolean {
+  if (!material || typeof material !== 'object') return false
+  const pinned = (material as Record<string, unknown>).pinnedComponents
+  return Boolean(pinned && typeof pinned === 'object' && Object.keys(pinned).length > 0)
+}
+
+export function loadInstructionSetManifest(path: string): InstructionSetManifest {
+  let value: unknown
+  let source: string
+  try { source = readFileSync(path, 'utf8') } catch { return fail('instruction_set_path_not_found') }
+  try { value = JSON.parse(source) } catch { return fail('instruction_set_manifest_invalid_json') }
+  if (!value || typeof value !== 'object') return fail('instruction_set_manifest_invalid')
+  const input = value as Record<string, unknown>
+  if (typeof input.name !== 'string' || input.name.trim() === '') return fail('instruction_set_manifest_invalid_name')
+  const hasDescription = Object.hasOwn(input, 'description')
+  if (hasDescription && input.description !== null && typeof input.description !== 'string') return fail('instruction_set_manifest_invalid_description')
+  const description = hasDescription
+    ? input.description === '' ? null : input.description as string | null
+    : undefined
+  if (hasPinnedComponents(input.default)) return fail('instruction_set_component_unavailable')
+  if (!Array.isArray(input.shape) || input.shape.length === 0 || input.shape.some(key => typeof key !== 'string' || key === '') || new Set(input.shape).size !== input.shape.length) return fail('instruction_set_manifest_invalid_shape')
+  if (!Array.isArray(input.components)) return fail('instruction_set_manifest_invalid_components')
+  let root: string
+  try { root = realpathSync(dirname(path)) } catch { return fail('instruction_set_path_not_found') }
+  const seen = new Set<string>()
+  const loadedComponents: Array<InstructionSetComponent & { changedSinceSync: boolean; hasSyncBaseline: boolean }> = []
+  for (const raw of input.components) {
+    if (!raw || typeof raw !== 'object') return fail('instruction_set_manifest_invalid_component')
+    const component = raw as Record<string, unknown>
+    if (typeof component.key !== 'string' || component.key === '' || !input.shape.includes(component.key)) return fail(component.key && !input.shape.includes(component.key) ? 'instruction_set_key_outside_shape' : 'instruction_set_manifest_invalid_component')
+    const modelConfig = component.modelConfig === undefined ? undefined : component.modelConfig
+    if (modelConfig !== undefined && (typeof modelConfig !== 'string' || modelConfig === '')) return fail('instruction_set_manifest_invalid_component')
+    const identity = `${component.key}\u0000${modelConfig ?? ''}`; if (seen.has(identity)) return fail('instruction_set_duplicate_component'); seen.add(identity)
+    let text: string
+    if (typeof component.text === 'string' && component.path === undefined) text = component.text
+    else if (typeof component.path === 'string' && component.text === undefined) {
+      if (isAbsolute(component.path)) return fail('instruction_set_path_escape')
+      const candidate = resolve(root, component.path)
+      if (relative(root, candidate).startsWith('..')) return fail('instruction_set_path_escape')
+      if (!existsSync(candidate)) return fail('instruction_set_path_not_found')
+      let target: string; try { target = realpathSync(candidate) } catch { return fail('instruction_set_path_not_found') }
+      if (relative(root, target).startsWith('..')) return fail('instruction_set_path_escape')
+      try { text = readFileSync(target, 'utf8') } catch { return fail('instruction_set_path_not_found') }
+      if (Buffer.byteLength(text, 'utf8') > MAX_INSTRUCTION_SET_COMPONENT_BYTES) return fail('instruction_set_component_too_large')
+    } else return fail('instruction_set_manifest_invalid_component')
+    if (Buffer.byteLength(text, 'utf8') > MAX_INSTRUCTION_SET_COMPONENT_BYTES) return fail('instruction_set_component_too_large')
+    const hasSyncBaseline = typeof component.syncedContentSha256 === 'string'
+    if (component.syncedContentSha256 !== undefined && (!hasSyncBaseline || !/^[a-f0-9]{64}$/u.test(component.syncedContentSha256 as string))) return fail('instruction_set_manifest_invalid_component')
+    loadedComponents.push({
+      key: component.key,
+      ...(modelConfig === undefined ? {} : { modelConfig }),
+      text,
+      hasSyncBaseline,
+      changedSinceSync: hasSyncBaseline && sha256(text) !== component.syncedContentSha256,
+    })
+  }
+  for (const key of input.shape) if (!loadedComponents.some(component => component.key === key)) return fail('instruction_set_missing_shape_key')
+  const defaultIdentity = input.default && typeof input.default === 'object'
+    && typeof (input.default as Record<string, unknown>).modelConfigIdentity === 'string'
+    ? (input.default as Record<string, unknown>).modelConfigIdentity as string
+    : null
+  let components = loadedComponents
+  if (defaultIdentity) {
+    if (input.manifestVersion === 1 && (input.shape as string[]).some(key => {
+      const bare = loadedComponents.find(component => component.key === key && component.modelConfig === undefined)
+      const tagged = loadedComponents.find(component => component.key === key && component.modelConfig === defaultIdentity)
+      return bare && tagged && (!bare.hasSyncBaseline || !tagged.hasSyncBaseline)
+    })) return fail('instruction_set_sync_baseline_missing')
+    const changedDefaultKeys = new Set(loadedComponents.flatMap(component => (
+      component.modelConfig === undefined && component.hasSyncBaseline && component.changedSinceSync
+        ? [component.key]
+        : []
+    )))
+    const changedSameIdentityKeys = new Set(loadedComponents.flatMap(component => (
+      component.modelConfig === defaultIdentity && component.hasSyncBaseline && component.changedSinceSync
+        ? [component.key]
+        : []
+    )))
+    if ([...changedDefaultKeys].some(key => changedSameIdentityKeys.has(key))) return fail('instruction_set_conflicting_synced_edits')
+    if (changedDefaultKeys.size > 0) {
+      components = loadedComponents.filter(component => (
+        component.modelConfig !== defaultIdentity || !changedDefaultKeys.has(component.key)
+      ))
+    }
+  }
+  const namedProfiles = new Set([
+    ...(components.some(component => component.modelConfig === undefined) && defaultIdentity
+      ? [defaultIdentity]
+      : []),
+    ...components.flatMap(component => component.modelConfig ? [component.modelConfig] : []),
+  ])
+  const namedProfileHasPins = Array.isArray(input.profiles) && input.profiles.some(profile => {
+    if (!profile || typeof profile !== 'object') return false
+    const value = profile as Record<string, unknown>
+    return typeof value.modelConfigIdentity === 'string'
+      && namedProfiles.has(value.modelConfigIdentity)
+      && hasPinnedComponents(value.production)
+  })
+  if (namedProfileHasPins) return fail('instruction_set_component_unavailable')
+  return {
+    name: input.name,
+    ...(hasDescription ? { description } : {}),
+    shape: input.shape as string[],
+    components: components.map(({ key, modelConfig, text }) => ({ key, ...(modelConfig === undefined ? {} : { modelConfig }), text })),
+  }
+}