WS1 — The pack interface: one manifest per domain, score as a field of a pack

.github/workflows/ci.yml

@@ -61,6 +61,9 @@ jobs:
           # the non-filename schemas (AC5: all five) via --schema
           $V packages/schema/test/fixtures/valid/solvespec.toml --schema solvespec
           $V packages/schema/test/fixtures/valid/catalog-entry.toml --schema catalog-entry
+          # the shipped pack manifest (WS1 #369) — kinded by filename (PACK.toml),
+          # so this also exercises the kindForFilename mapping.
+          $V packages/extension/packs/quantum-control/PACK.toml
           # ledger-record (Plan 3 / L1 Task 9): oneOf-on-`type`, JSON on disk (JSONL
           # lines in the real ~/.amico/ledger/runs.jsonl) — validateFile parses by
           # .json extension, not TOML.

packages/extension/packs/quantum-control/PACK.toml

@@ -0,0 +1,71 @@
+# The quantum-control pack — the bundled default domain pack (WS1, #369).
+# One manifest per domain; the score is one FIELD of this pack. Paths are
+# relative to this pack dir. Scores still live at the extension root (scores/)
+# for WS1 byte-parity; WS2 folds them into this dir physically.
+#
+# tier "open" = ships in the open repo. An entitlement bundle id (e.g. the
+# -issimo codes) names the tier gating an entry; flowing a feature back to
+# open-source is a manifest edit plus a content move.
+schema_version = "1"
+id = "quantum-control"
+name = "Quantum Control"
+version = 1
+
+# Order matters: it reproduces today's effective repertoire order (the router
+# renders cards in the order handed to it).
+scores = [
+  "../../scores/overture",
+  "../../scores/pasqal-mis",
+  "../../scores/pulse-designer",
+]
+catalog_schema = "catalog-entry"
+eval_corpus = "prova://corpora/pulse-design"
+
+[onboarding]
+primary = "pulse-designer"
+head = "overture"
+
+# Declarative in WS1 (staging still flows through the existing skill-index
+# seam); WS2's runtime-instruction rewrite makes this the source of truth.
+[[skills]]
+path = "../../skills/transmon"
+tier = "open"
+
+[[skills]]
+path = "../../skills/atoms"
+tier = "open"
+
+[[skills]]
+path = "../../skills/bosonic"
+tier = "open"
+
+[[skills]]
+path = "../../skills/fluxonium"
+tier = "open"
+
+[[skills]]
+path = "../../skills/ions"
+tier = "open"
+
+[[skills]]
+path = "../../skills/pasqal"
+tier = "open"
+
+[templates.solve]
+path = "../../scores/pulse-designer/templates/solve.jl"
+tier = "open"
+
+# The corrector: the gate contract the runner (amico-run) enforces — the
+# vetted template's FILL-IN block and the composed exemplar index
+# (masked-baseline). Integrity is a LOAD-TIME property (#369): the loader
+# verifies these sha256s and that the paths resolve outside agent-editable
+# trees. Deeper independence (the separate-repo gate pattern the QEC pack
+# uses) lands with WS3.
+[corrector]
+name = "amico-run gate (vetted template + exemplar baseline)"
+paths = [
+  "../../scores/pulse-designer/templates/solve.jl",
+  "../../exemplars/index.json",
+]
+integrity = "corrector/integrity.toml"
+tier = "open"

packages/extension/packs/quantum-control/corrector/integrity.toml

@@ -0,0 +1,7 @@
+# sha256 integrity manifest for the quantum-control pack's corrector paths
+# (relative to the pack dir). Verified at load time (WS1 #369): a mismatch
+# makes the pack BROKEN — reported, never silently trusted.
+# Regenerate: shasum -a 256 <path> from packages/extension/
+[files]
+"../../scores/pulse-designer/templates/solve.jl" = "b285f55f445bdfec7533cc8558b72cd262f3a2a84aa5d48147d58617c867ace8"
+"../../exemplars/index.json" = "0d187afd4d1efc0109b63740859eb8e3dc5c2eceafa163e3d63c487d3576d2af"

packages/extension/src/opencode_config.ts

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import * as os from "node:os";
 import { parse as parseToml } from "smol-toml";
 import { loadRepertoire } from "./scores/loader";
+import { loadPacks } from "./scores/packs";
 import { readLocalEntitlements, filterRepertoire, packageAllowlist } from "./scores/entitlements";
 import { buildRouterSection } from "./scores/router";
 import { compileScore, spliceIntoAgentsMd, compileChainedScore, chainManifest } from "./scores/compiler";
@@ -140,6 +141,11 @@ const DEFAULT_PLUGIN_PATH = path.resolve(__dirname, "..", "opencode-plugin", "am
 /** Default scores repertoire root — same sibling-of-src-and-dist trick as the
  *  plugin path. Holds SCORE.md manifests, score-local templates, memory hooks. */
 export const DEFAULT_SCORES_ROOT = path.resolve(__dirname, "..", "scores");
+// Pack-manifest repertoire (WS1 #369): the bundled packs root + the default
+// pack id. The pack's manifest is the source of the repertoire; the legacy
+// scores-dir scan remains the fallback until WS2 folds scores/ into the pack.
+export const DEFAULT_PACKS_ROOT = path.resolve(__dirname, "..", "packs");
+export const DEFAULT_PACK_ID = "quantum-control";
 
 /** Skill-index roots (spec-20260704-113005 §3). Package skills are co-located
  *  in the workspace package repos; library (public) skills ship IN this repo
@@ -465,8 +471,12 @@ export interface OpencodeConfigOptions {
   /** Julia project (--project) the agent should use; already resolved (see
    *  resolveJuliaProject). Substituted into AGENTS.md as {{JULIA_PROJECT}}. */
   juliaProject: string | undefined;
-  /** Scores repertoire root (SCORE.md manifests). Default: the bundled scores/. */
+  /** Scores repertoire root (SCORE.md manifests). Legacy fallback when no
+   *  pack loads (WS1 #369); default: the bundled scores/. */
   scoresRoot?: string;
+  /** Packs root (PACK.toml manifests, precedence order). Default: the
+   *  bundled packs/. The default pack's manifest drives the repertoire. */
+  packsRoot?: string;
   /** Dir holding the user's entitlements.toml (access-code stub). Default: ~/.amico/amicode. */
   entitlementsDir?: string;
   /** Roots to search for co-located package skills (spec §3). Default: DEFAULT_SKILL_ROOTS. */
@@ -557,12 +567,30 @@ export function prepareOpencodeProject(opts: OpencodeConfigOptions): OpencodePro
 
   let finalContent = filled;
   try {
-    const scoresRoot = opts.scoresRoot ?? DEFAULT_SCORES_ROOT;
-    const load = loadRepertoire(scoresRoot);
+    // Pack-manifest repertoire (WS1 #369): the default pack's manifest is the
+    // source — the score is one field of the pack. A missing or broken pack
+    // root falls back to the legacy scores-dir scan, so boot behaves exactly
+    // as today in every degenerate case (never brick).
+    const packsLoad = loadPacks([opts.packsRoot ?? DEFAULT_PACKS_ROOT], {
+      // The agent-editable trees at boot (#369): a corrector path resolving
+      // under any of these breaks the pack — the gate must live where the
+      // agent cannot write. The staging dir hosts the agent's own project.
+      agentTrees: [
+        problemsRoot(),
+        SCRATCH_DIR,
+        path.join(os.homedir(), ".amico", "server", "opencode-project-staging"),
+        ...(vaultDir ? [path.join(vaultDir, "amicode")] : []),
+      ],
+    });
+    const pack = packsLoad.packs.find((p) => p.manifest.id === DEFAULT_PACK_ID) ?? packsLoad.packs[0];
+    if (!pack && packsLoad.errors.length > 0) {
+      console.warn(`amicode: pack load failed, falling back to scores root: ${JSON.stringify(packsLoad.errors)}`);
+    }
     const ents = readLocalEntitlements(opts.entitlementsDir ?? path.join(os.homedir(), ".amico", "amicode"));
-    const visible = filterRepertoire(load.scores, ents.entitlements);
-    const score0 = visible.find((s) => s.manifest.id === "pulse-designer");
-    const overture = visible.find((s) => s.manifest.id === "overture");
+    const repertoire = pack ? pack.scores : loadRepertoire(opts.scoresRoot ?? DEFAULT_SCORES_ROOT).scores;
+    const visible = filterRepertoire(repertoire, ents.entitlements);
+    const score0 = visible.find((s) => s.manifest.id === (pack?.manifest.onboarding.primary ?? "pulse-designer"));
+    const overture = visible.find((s) => s.manifest.id === (pack?.manifest.onboarding.head ?? "overture"));
     // Routing predicate (spec §3): onboard (chain overture → pulse-designer)
     // ONLY when there is a vault to remember into AND the user has neither a
     // materialized profile NOR a completion marker (the second disjunct closes

packages/extension/src/scores/packs.ts

@@ -0,0 +1,148 @@
+// Pack loader (autoresearch studio WS1, #369) — a pack is the unit of
+// generality: one manifest per domain, the score a FIELD of the pack. Packs
+// resolve from an ordered root list (precedence top→bottom, the mount-stack
+// grammar): the bundled packs dir first, an external root appended later as
+// the second-pack seam (WS3). The manifest is validated through the ONE
+// shared validator (@amicode/schema kind "pack"); score dirs load through the
+// existing parseScoreMd so a pack's scores are byte-identical Score objects.
+// A broken pack is REPORTED, never thrown — pack trouble must not brick the
+// boot (the same isolation property loadRepertoire carries).
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { validateFile } from "@amicode/schema";
+import { parse as parseToml } from "smol-toml";
+import { parseScoreMd, Score } from "./loader";
+
+/** The pack manifest shape (schema package kind "pack" is the contract —
+ *  this interface mirrors it for typed consumers; validate() is the arbiter). */
+export interface PackManifest {
+  schema_version: string;
+  id: string;
+  name: string;
+  version?: number;
+  scores: string[];
+  onboarding: { primary: string; head?: string };
+  skills?: { path: string; tier?: string }[];
+  templates?: Record<string, { path: string; tier?: string }>;
+  corrector: { name: string; paths: string[]; integrity: string; tier?: string };
+  catalog_schema?: string;
+  eval_corpus?: string;
+}
+
+export interface Pack {
+  manifest: PackManifest;
+  dir: string;
+  scores: Score[];
+}
+
+export interface PacksLoad {
+  packs: Pack[];
+  errors: { path: string; errors: string[] }[];
+}
+
+const MANIFEST = "PACK.toml";
+
+export interface LoadPacksOptions {
+  /** Agent-editable trees (absolute). A corrector path resolving under any of
+   *  them breaks the pack: the threshold condition is a load-time property —
+   *  a gate living where the agent writes is below threshold by construction
+   *  (#369 Constraints). */
+  agentTrees?: string[];
+}
+
+/** Load every pack found under the ordered roots. Roots are scanned in
+ *  precedence order (earlier root shadows later on id collision); each dir
+ *  carrying a PACK.toml is a pack; everything else is skipped silently. */
+export function loadPacks(roots: string[], opts: LoadPacksOptions = {}): PacksLoad {
+  const out: PacksLoad = { packs: [], errors: [] };
+  const seen = new Set<string>();
+  for (const root of roots) {
+    if (!fs.existsSync(root)) continue;
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const dir = path.join(root, entry.name);
+      const manifestPath = path.join(dir, MANIFEST);
+      if (!fs.existsSync(manifestPath)) continue;
+      let manifest: PackManifest;
+      try {
+        manifest = parsePackManifest(manifestPath);
+        verifyCorrectorIntegrity(manifest, dir, opts.agentTrees ?? []);
+      } catch (e) {
+        out.errors.push({ path: manifestPath, errors: [String(e)] });
+        continue;
+      }
+      if (seen.has(manifest.id)) continue; // higher-precedence root shadows
+      seen.add(manifest.id);
+      // Scores are loaded eagerly: a pack with an unparseable score is a
+      // BROKEN pack (reported whole), keeping the all-or-nothing contract a
+      // consumer's boot fallback expects.
+      const scores: Score[] = [];
+      const scoreErrs: string[] = [];
+      for (const rel of manifest.scores) {
+        const scoreDir = path.resolve(dir, rel);
+        const scorePath = path.join(scoreDir, "SCORE.md");
+        try {
+          const { manifest: m, body } = parseScoreMd(fs.readFileSync(scorePath, "utf8"), scorePath);
+          scores.push({ manifest: m, body, dir: scoreDir });
+        } catch (e) {
+          scoreErrs.push(String(e));
+        }
+      }
+      if (scoreErrs.length) {
+        out.errors.push({ path: manifestPath, errors: scoreErrs });
+        continue;
+      }
+      out.packs.push({ manifest, dir, scores });
+    }
+  }
+  return out;
+}
+
+/** Read + validate a PACK.toml through the ONE shared validator (the schema
+ *  package's file path: read → parse → field-precise errors), then parse the
+ *  value for typed consumers. */
+export function parsePackManifest(manifestPath: string): PackManifest {
+  const v = validateFile(manifestPath, "pack");
+  if (!v.ok) throw new Error(`${manifestPath}: invalid pack manifest:\n  ${v.errors.join("\n  ")}`);
+  return parseToml(fs.readFileSync(manifestPath, "utf8")) as unknown as PackManifest;
+}
+
+const sha256 = (file: string) => createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+
+/** The load-time corrector checks (#369): every named gate artifact must be
+ *  covered by the integrity manifest, hash-match it, and resolve OUTSIDE the
+ *  agent-editable trees. Any violation throws (the caller reports the pack
+ *  broken whole) — a corrector is never silently trusted. */
+export function verifyCorrectorIntegrity(
+  manifest: PackManifest,
+  packDir: string,
+  agentTrees: string[],
+): void {
+  const { corrector } = manifest;
+  const integrityPath = path.resolve(packDir, corrector.integrity);
+  if (!fs.existsSync(integrityPath))
+    throw new Error(`corrector integrity manifest missing: ${integrityPath}`);
+  let covered: Record<string, string>;
+  try {
+    covered = (parseToml(fs.readFileSync(integrityPath, "utf8")) as { files?: Record<string, string> }).files ?? {};
+  } catch (e) {
+    throw new Error(`corrector integrity manifest unreadable (${integrityPath}): ${e}`);
+  }
+  for (const rel of corrector.paths) {
+    const abs = path.resolve(packDir, rel);
+    if (!covered[rel])
+      throw new Error(`corrector path not covered by integrity manifest: ${rel}`);
+    if (!fs.existsSync(abs))
+      throw new Error(`corrector path missing on disk: ${abs}`);
+    const actual = sha256(abs);
+    if (actual !== covered[rel])
+      throw new Error(`corrector sha256 mismatch for ${rel}: expected ${covered[rel]}, got ${actual}`);
+    for (const tree of agentTrees) {
+      if (abs === tree || abs.startsWith(tree + path.sep))
+        throw new Error(
+          `corrector path lives inside an agent-editable tree (below threshold by construction): ${abs} is under ${tree}`,
+        );
+    }
+  }
+}