@crewhaus/spec 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crewhaus/spec",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "User-facing spec schema (Zod) + YAML parser",
   "main": "src/index.ts",
@@ -12,15 +12,15 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.0.0",
+    "@crewhaus/errors": "0.1.2",
     "yaml": "^2.6.0",
     "zod": "^3.23.8"
   },
   "license": "Apache-2.0",
   "author": {
     "name": "Max Meier",
-    "email": "max@studiomax.io",
-    "url": "https://studiomax.io"
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
   },
   "repository": {
     "type": "git",
@@ -32,12 +32,7 @@
     "url": "https://github.com/crewhaus/factory/issues"
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE",
-    "NOTICE"
-  ]
+  "files": ["src", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -17,6 +17,28 @@ agent:
     expect(spec.agent.instructions).toBe("be helpful");
   });
 
+  // Codegen-injection backstop (#147/#148): names flow verbatim into generated
+  // comments, file paths, JSON manifests and frontmatter — reject the breakout
+  // characters at parse time so no emitter can be tricked downstream.
+  describe("name safe-charset backstop", () => {
+    const cli = (name: string) =>
+      `\ntarget: cli\nagent:\n  model: m\n  instructions: be helpful\nname: ${name}\n`;
+    test.each([
+      ["a newline (block/line-comment escape)", '"line one\\nglobalThis.x=1"'],
+      ["a block-comment terminator */", '"safe */ code /* x"'],
+      ["a slash (path traversal in plugin emitters)", '"../../etc/evil"'],
+      ["a double-quote (JSON manifest break-out)", '"a\\", \\"dependencies\\": {}"'],
+      ["a backtick (template-literal escape)", '"a`+code+`b"'],
+    ])("rejects a name containing %s", (_label, name) => {
+      expect(() => parseSpec(cli(name))).toThrow(SpecParseError);
+    });
+
+    test("accepts ordinary names (letters, digits, space, . _ - :)", () => {
+      const spec = parseSpec(cli('"My Agent v1.2 - prod:eu"'));
+      expect(spec.name).toBe("My Agent v1.2 - prod:eu");
+    });
+  });
+
   test("preserves multi-line block-scalar instructions", () => {
     const spec = parseSpec(`
 name: hello
@@ -138,6 +160,67 @@ tools:
   });
 });
 
+// SECURITY: the code-execution config blob is compiled verbatim into
+// `registerCodeExecutionConfig(...)` and the sandbox boundary validates
+// images/mounts against THIS same blob — so a spec must NOT be able to
+// supply its own sandbox allowlist/backend/mounts. Those keys are owned by
+// trusted operator config (CLI / CREWHAUS_SANDBOX* env), never a spec file.
+// The blob can arrive under codeExecution/code_execution OR the per-tool
+// keys python/javascript/shell (target-cli reads the per-tool key first),
+// so every one of those must be rejected.
+describe("tool_config code-execution sandbox-override hardening", () => {
+  const codeExecKeys = [
+    "codeExecution",
+    "code_execution",
+    "python",
+    "javascript",
+    "shell",
+  ] as const;
+  const overrideKeys = [
+    ["backend", "backend: noop"],
+    ["allowedImages", "allowedImages:\n      - evil/image:latest"],
+    ["allowed_images", "allowed_images:\n      - evil/image:latest"],
+    ["mountWhitelist", 'mountWhitelist:\n      - "/"'],
+    ["mount_whitelist", 'mount_whitelist:\n      - "/"'],
+    ["images", "images:\n      python: evil/image:latest"],
+    ["mounts", "mounts:\n      /etc: /host-etc"],
+    ["sandbox", "sandbox: noop"],
+  ] as const;
+
+  const specWith = (cfgKey: string, body: string) =>
+    `\nname: hello\ntarget: cli\nagent:\n  model: m\n  instructions: i\ntools:\n  - python\ntool_config:\n  ${cfgKey}:\n    ${body}\n`;
+
+  for (const cfgKey of codeExecKeys) {
+    for (const [label, body] of overrideKeys) {
+      test(`rejects sandbox-override key "${label}" under tool_config.${cfgKey}`, () => {
+        expect(() => parseSpec(specWith(cfgKey, body))).toThrow(SpecParseError);
+      });
+    }
+
+    test(`allows non-security knobs under tool_config.${cfgKey}`, () => {
+      const spec = parseSpec(specWith(cfgKey, "defaultTimeoutMs: 5000\n    warmPoolSize: 2"));
+      if (spec.target !== "cli") expect.unreachable();
+      expect(spec.tool_config?.[cfgKey]).toEqual({
+        defaultTimeoutMs: 5000,
+        warmPoolSize: 2,
+      });
+    });
+  }
+
+  test("does not constrain non-code-execution tool configs (fetch stays opaque)", () => {
+    const spec = parseSpec(
+      "\nname: hello\ntarget: cli\nagent:\n  model: m\n  instructions: i\ntools:\n  - fetch\ntool_config:\n  fetch:\n    allowedImages:\n      - anything\n    backend: whatever\n",
+    );
+    if (spec.target !== "cli") expect.unreachable();
+    // `fetch` is not a code-execution tool, so its config is forwarded
+    // verbatim — these keys are meaningless there and harmless.
+    expect(spec.tool_config?.["fetch"]).toEqual({
+      allowedImages: ["anything"],
+      backend: "whatever",
+    });
+  });
+});
+
 describe("Spec schema", () => {
   test("schema is exported as a runtime value (Zod)", () => {
     expect(typeof Spec.safeParse).toBe("function");
@@ -1009,3 +1092,327 @@ compaction:
     ).toThrow(SpecParseError);
   });
 });
+
+// FR-004 — Pillar 3 security block (intent-gate judge selection).
+describe("parseSpec security.justification", () => {
+  test("parses a cli spec with security.justification.judge=claude + model", () => {
+    const spec = parseSpec(`
+name: hello
+target: cli
+agent:
+  model: m
+  instructions: i
+security:
+  justification:
+    judge: claude
+    model: claude-haiku-4-5
+`);
+    if (spec.target !== "cli") expect.unreachable();
+    expect(spec.security?.justification?.judge).toBe("claude");
+    expect(spec.security?.justification?.model).toBe("claude-haiku-4-5");
+  });
+
+  test("judge defaults to rule-based when the justification block omits it", () => {
+    const spec = parseSpec(`
+name: hello
+target: cli
+agent:
+  model: m
+  instructions: i
+security:
+  justification: {}
+`);
+    if (spec.target !== "cli") expect.unreachable();
+    expect(spec.security?.justification?.judge).toBe("rule-based");
+  });
+
+  test("rejects an unknown judge enum value", () => {
+    expect(() =>
+      parseSpec(`
+name: hello
+target: cli
+agent:
+  model: m
+  instructions: i
+security:
+  justification:
+    judge: gpt-omniscient
+`),
+    ).toThrow(SpecParseError);
+  });
+
+  test("rejects unknown keys inside the security block (strict)", () => {
+    expect(() =>
+      parseSpec(`
+name: hello
+target: cli
+agent:
+  model: m
+  instructions: i
+security:
+  enableTelepathy: true
+`),
+    ).toThrow(SpecParseError);
+  });
+
+  test("security block is optional — a spec without it still parses", () => {
+    const spec = parseSpec(`
+name: hello
+target: cli
+agent:
+  model: m
+  instructions: i
+`);
+    if (spec.target !== "cli") expect.unreachable();
+    expect(spec.security).toBeUndefined();
+  });
+});
+
+// FR-006 — Pillar 3 sink-side fabric (egress matcher selector).
+describe("parseSpec security.egressMatcher", () => {
+  test("parses a cli spec with security.egressMatcher: semantic", () => {
+    const spec = parseSpec(`
+name: hello
+target: cli
+agent:
+  model: m
+  instructions: i
+security:
+  egressMatcher: semantic
+`);
+    if (spec.target !== "cli") expect.unreachable();
+    expect(spec.security?.egressMatcher).toBe("semantic");
+  });
+
+  test("parses security.egressMatcher: substring (the explicit default)", () => {
+    const spec = parseSpec(`
+name: hello
+target: cli
+agent:
+  model: m
+  instructions: i
+security:
+  egressMatcher: substring
+`);
+    if (spec.target !== "cli") expect.unreachable();
+    expect(spec.security?.egressMatcher).toBe("substring");
+  });
+
+  test("rejects an unknown egressMatcher enum value (strict)", () => {
+    expect(() =>
+      parseSpec(`
+name: hello
+target: cli
+agent:
+  model: m
+  instructions: i
+security:
+  egressMatcher: telepathic
+`),
+    ).toThrow(SpecParseError);
+  });
+
+  test("egressMatcher coexists with justification in the same security block", () => {
+    const spec = parseSpec(`
+name: hello
+target: cli
+agent:
+  model: m
+  instructions: i
+security:
+  justification:
+    judge: claude
+  egressMatcher: semantic
+`);
+    if (spec.target !== "cli") expect.unreachable();
+    expect(spec.security?.justification?.judge).toBe("claude");
+    expect(spec.security?.egressMatcher).toBe("semantic");
+  });
+
+  test("egressMatcher is optional — a security block without it still parses", () => {
+    const spec = parseSpec(`
+name: hello
+target: cli
+agent:
+  model: m
+  instructions: i
+security:
+  justification: {}
+`);
+    if (spec.target !== "cli") expect.unreachable();
+    expect(spec.security?.egressMatcher).toBeUndefined();
+  });
+});
+
+describe("parseSpec pipeline target — vector backend (Section 21)", () => {
+  const PIPELINE = (retrieve: string) => `
+name: doc-bot
+target: pipeline
+agent:
+  model: claude-sonnet-4-6
+  instructions: answer using Retrieve
+retrieve:
+${retrieve}
+indexing:
+  chunkStrategy: fixed
+  chunkSize: 200
+  chunkOverlap: 0
+  documents:
+    - id: doc-1
+      text: the quick brown fox
+`;
+
+  test("defaults vectorBackend to in-memory when omitted", () => {
+    const spec = parseSpec(PIPELINE("  embedderModel: mock/det"));
+    if (spec.target !== "pipeline") expect.unreachable();
+    expect(spec.retrieve.vectorBackend).toBe("in-memory");
+  });
+
+  test("accepts the file backend (lance) with no extra config", () => {
+    const spec = parseSpec(PIPELINE("  embedderModel: mock/det\n  vectorBackend: lance"));
+    if (spec.target !== "pipeline") expect.unreachable();
+    expect(spec.retrieve.vectorBackend).toBe("lance");
+  });
+
+  test("accepts an http backend with url + collection + apiKey", () => {
+    const spec = parseSpec(
+      PIPELINE(
+        [
+          "  embedderModel: mock/det",
+          "  vectorBackend: qdrant",
+          "  url: https://qdrant.example",
+          "  collection: docs",
+          "  apiKey: $QDRANT_API_KEY",
+        ].join("\n"),
+      ),
+    );
+    if (spec.target !== "pipeline") expect.unreachable();
+    expect(spec.retrieve.vectorBackend).toBe("qdrant");
+    expect(spec.retrieve.url).toBe("https://qdrant.example");
+    expect(spec.retrieve.collection).toBe("docs");
+    expect(spec.retrieve.apiKey).toBe("$QDRANT_API_KEY");
+  });
+
+  test("rejects an unknown backend id", () => {
+    expect(() => parseSpec(PIPELINE("  embedderModel: mock/det\n  vectorBackend: faiss"))).toThrow(
+      SpecParseError,
+    );
+  });
+
+  test("rejects an http backend missing url", () => {
+    expect(() =>
+      parseSpec(PIPELINE("  embedderModel: mock/det\n  vectorBackend: qdrant\n  collection: docs")),
+    ).toThrow(/requires retrieve\.url/);
+  });
+
+  test("rejects an http backend missing collection", () => {
+    expect(() =>
+      parseSpec(
+        PIPELINE(
+          "  embedderModel: mock/det\n  vectorBackend: pinecone\n  url: https://pinecone.example",
+        ),
+      ),
+    ).toThrow(/requires retrieve\.collection/);
+  });
+});
+
+describe("parseSpec crew target cross-field invariants (Section 22)", () => {
+  // Two-role crew with a configurable `entry:` line and an optional trailing
+  // routing block, so each post-parse invariant is exercised through a real
+  // Zod-valid spec (the cross-field checks run only after safeParse succeeds).
+  const CREW = (entry: string, routing = "") => `
+name: team
+target: crew
+model: m
+entry: ${entry}
+roles:
+  lead:
+    instructions: coordinate the crew
+  worker:
+    instructions: do the work
+${routing}`;
+
+  test("parses a valid crew with match routing and threads roles/entry/routing", () => {
+    const spec = parseSpec(
+      CREW(
+        "lead",
+        [
+          "routing:",
+          "  kind: match",
+          "  match:",
+          "    lead:",
+          "      - contains: help",
+          "        to: worker",
+        ].join("\n"),
+      ),
+    );
+    if (spec.target !== "crew") expect.unreachable();
+    expect(Object.keys(spec.roles)).toEqual(["lead", "worker"]);
+    expect(spec.entry).toBe("lead");
+    expect(spec.routing).toEqual({
+      kind: "match",
+      match: { lead: [{ contains: "help", to: "worker" }] },
+    });
+  });
+
+  test("accepts llm routing (no match block) — the match-validation loop is skipped", () => {
+    const spec = parseSpec(CREW("lead", ["routing:", "  kind: llm"].join("\n")));
+    if (spec.target !== "crew") expect.unreachable();
+    expect(spec.routing).toEqual({ kind: "llm" });
+  });
+
+  test("accepts a crew with no routing block at all", () => {
+    const spec = parseSpec(CREW("worker"));
+    if (spec.target !== "crew") expect.unreachable();
+    expect(spec.routing).toBeUndefined();
+    expect(spec.entry).toBe("worker");
+  });
+
+  test("rejects a crew whose roles record is empty", () => {
+    expect(() => parseSpec("name: t\ntarget: crew\nmodel: m\nentry: lead\nroles: {}\n")).toThrow(
+      /crew target requires at least one role/,
+    );
+  });
+
+  test("rejects a crew whose entry does not name a declared role", () => {
+    expect(() => parseSpec(CREW("ghost"))).toThrow(
+      /crew\.entry "ghost" must name one of crew\.roles \(got: lead, worker\)/,
+    );
+  });
+
+  test("rejects routing whose match source role is not a declared role", () => {
+    expect(() =>
+      parseSpec(
+        CREW(
+          "lead",
+          [
+            "routing:",
+            "  kind: match",
+            "  match:",
+            "    ghost:",
+            "      - contains: x",
+            "        to: worker",
+          ].join("\n"),
+        ),
+      ),
+    ).toThrow(/crew\.routing\.match\["ghost"\]: source role not in crew\.roles/);
+  });
+
+  test("rejects routing whose match target role is not a declared role", () => {
+    expect(() =>
+      parseSpec(
+        CREW(
+          "lead",
+          [
+            "routing:",
+            "  kind: match",
+            "  match:",
+            "    lead:",
+            "      - contains: x",
+            "        to: ghost",
+          ].join("\n"),
+        ),
+      ),
+    ).toThrow(/crew\.routing\.match\["lead"\]\.to = "ghost" — target role not in crew\.roles/);
+  });
+});

package/src/index.ts

@@ -2,6 +2,22 @@ import { SpecParseError } from "@crewhaus/errors";
 import { parse as parseYaml } from "yaml";
 import { z } from "zod";
 
+// SECURITY (codegen-injection backstop, #147/#148): spec/role/node/step names
+// flow verbatim into generated source across ~14 emitters — `//` and `/* */`
+// comments, template literals, JSON `package.json` manifests, YAML frontmatter,
+// and on-disk file paths (`skills/<name>/SKILL.md`). A raw newline, `*/`, quote,
+// backtick or `/` lets a crafted name break out of those contexts (RCE on
+// build/run, dependency injection, path traversal). The emitters escape per-site
+// as defense-in-depth, but this is the systemic floor: restrict names to a
+// single-line safe charset so the breakout characters can never enter the IR.
+const safeName = z
+  .string()
+  .min(1)
+  .regex(
+    /^[\w .:-]+$/,
+    "name may contain only letters, digits, spaces, and '_ . - :' (no newlines, quotes, slashes, or comment/template delimiters)",
+  );
+
 /**
  * v0 spec schema — a discriminated union over `target`.
  *
@@ -83,7 +99,7 @@ const subAgentDefinitionSchema = z
   })
   .strict();
 
-const subAgentsBlock = z.record(z.string().min(1), subAgentDefinitionSchema).optional();
+const subAgentsBlock = z.record(safeName, subAgentDefinitionSchema).optional();
 
 /**
  * Section 14 — per-tool runtime config map. Tool-specific schemas live
@@ -91,8 +107,80 @@ const subAgentsBlock = z.record(z.string().min(1), subAgentDefinitionSchema).opt
  * `unknown` and forwards it verbatim to the IR. The codegen layer emits
  * an init call (e.g. `registerFetchConfig({ ... })`) for tools whose
  * BUILTIN_TOOL_MAP entry declares an `initSymbol`.
+ *
+ * SECURITY (sandbox-override hardening): the code-execution config is the
+ * one exception to "opaque `unknown`". Its blob is compiled verbatim into
+ * `registerCodeExecutionConfig(...)` in the generated bundle, and the
+ * @crewhaus/sandbox boundary validates images/mounts against THIS same
+ * blob's allowlist (`allowedImages`, `mountWhitelist`). If a spec could set
+ * those — or `backend` (e.g. force `noop`, which is no isolation at all),
+ * `images`, or `mounts` — an untrusted marketplace/template spec would be
+ * supplying its own sandbox allowlist, making the controls self-defeating.
+ * The sandbox boundary must come only from trusted operator config (the CLI
+ * / `CREWHAUS_SANDBOX*` env vars), never from a spec file. So the
+ * code-execution config is constrained to a strict allowlist of non-security
+ * knobs; any sandbox-override key is rejected at parse time (defense in
+ * depth, mirroring `permissions.mode: bypass`).
+ *
+ * The code-execution config can arrive under any of the keys whose
+ * BUILTIN_TOOL_MAP entry maps to `registerCodeExecutionConfig` — the
+ * `codeExecution`/`code_execution` aliases AND the per-tool keys
+ * `python`/`javascript`/`shell` (target-cli `resolveTools` reads the
+ * per-tool key first, then the aliases). All of them must be constrained,
+ * or the guard is trivially bypassed by nesting the blob under `python`.
  */
-const toolConfigBlock = z.record(z.string().min(1), z.unknown()).optional();
+const SANDBOX_OVERRIDE_KEYS = [
+  "sandbox",
+  "backend",
+  "allowedImages",
+  "allowed_images",
+  "mountWhitelist",
+  "mount_whitelist",
+  "images",
+  "mounts",
+] as const;
+
+const CODE_EXECUTION_CONFIG_KEYS = [
+  "codeExecution",
+  "code_execution",
+  "python",
+  "javascript",
+  "shell",
+] as const;
+
+const codeExecutionConfigSchema = z
+  .object({
+    // Non-security knobs only. The sandbox boundary (backend, image
+    // allowlist, mount whitelist, per-language images, mounts) is owned by
+    // trusted operator config and is intentionally NOT settable from a spec.
+    defaultTimeoutMs: z.number().int().positive().optional(),
+    default_timeout_ms: z.number().int().positive().optional(),
+    warmPoolSize: z.number().int().nonnegative().optional(),
+    warm_pool_size: z.number().int().nonnegative().optional(),
+  })
+  .strict(
+    `code-execution config may only set non-security knobs (defaultTimeoutMs, warmPoolSize); sandbox-boundary keys (${SANDBOX_OVERRIDE_KEYS.join(", ")}) are owned by trusted operator config and rejected from specs`,
+  );
+
+const toolConfigBlock = z
+  .record(z.string().min(1), z.unknown())
+  .superRefine((cfg, ctx) => {
+    for (const key of CODE_EXECUTION_CONFIG_KEYS) {
+      const value = cfg[key];
+      if (value === undefined) continue;
+      const parsed = codeExecutionConfigSchema.safeParse(value);
+      if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: [key, ...issue.path],
+            message: issue.message,
+          });
+        }
+      }
+    }
+  })
+  .optional();
 
 /**
  * Section 17 — optional override for the model used by
@@ -122,6 +210,67 @@ const compactionBlock = z
   .strict()
   .optional();
 
+/**
+ * Pillar 3 (FR-004) — per-target security fabric block. Today it carries
+ * the intent-gate's judge selection; the optimizable path
+ * `["security", "justification"]` is already registered in
+ * `spec-patch`'s `OPTIMIZABLE_PATHS`, so this block MUST be named
+ * `security` with a `justification` sub-field to honour it.
+ *
+ * `justification.judge` selects which `JustificationJudge` the cli run
+ * path wires: `"rule-based"` (the deterministic default for tests/offline
+ * runs) or `"claude"` (the model-backed `@crewhaus/justification-judge-claude`,
+ * the documented production recommendation). `model` is the judge model
+ * id for the claude judge; the consumer defaults it to a haiku-class
+ * model when omitted.
+ *
+ * NOTE: `egressPolicy` is reserved — `OPTIMIZABLE_PATHS` also lists
+ * `["security", "egressPolicy"]`, owned by the egress-fabric FRs
+ * (FR-002/006). Do NOT add `egressPolicy` here; that would clobber their
+ * sub-field. FR-004 added `justification`; FR-006 added `egressMatcher`
+ * (the substring/semantic selector) alongside it — both are independent
+ * optional sub-fields of this same block.
+ */
+const securityBlock = z
+  .object({
+    justification: z
+      .object({
+        judge: z.enum(["rule-based", "claude"]).default("rule-based"),
+        model: z.string().min(1).optional(),
+      })
+      .strict()
+      .optional(),
+    /**
+     * Pillar 3 sink-side fabric (FR-006) — select the egress-matching
+     * strategy. `"substring"` (the default when omitted) is the
+     * behavior-preserving `SubstringEgressMatcher` with `MIN_MATCH_LENGTH`.
+     * `"semantic"` selects the optional embedding-backed
+     * `@crewhaus/egress-matcher-semantic`, which scores outbound payloads
+     * against tagged data-lineage by cosine similarity. Switching the
+     * matcher changes *how* lineage matches are detected; the per-origin/
+     * per-sink policy and the three audit outcomes are unaffected.
+     *
+     * This field is lowered to `IrSecurity.egressMatcher` (FR-006) and
+     * honoured by the `crewhaus run` path, which resolves the selector and
+     * threads the matcher into `runChatLoop({ egressMatcher })` — exactly
+     * how `security.justification.judge` selects the intent-gate judge on
+     * the same path. `"semantic"` constructs the optional
+     * `@crewhaus/egress-matcher-semantic` (with an injected embedder; see
+     * `--egress-embedder`). The runtime SEAM
+     * (`RunChatLoopOptions.egressMatcher`) underlies both.
+     *
+     * The *generated cli bundle* also honours this field: `@crewhaus/target-cli`
+     * emits the matcher construction (the semantic one with an injected
+     * `@crewhaus/embedder` embedder) into the bundle's
+     * `runChatLoop({ egressMatcher })`, so a compiled standalone artifact uses
+     * `semantic` WITHOUT the `crewhaus run` path. The substring default emits
+     * nothing, keeping the bundle free of any embedding dependency.
+     */
+    egressMatcher: z.enum(["substring", "semantic"]).optional(),
+  })
+  .strict()
+  .optional();
+
 /**
  * Section 55 (Track A) — named failure taxonomy. Cross-cutting block
  * available on every target shape. Each entry names a failure class and
@@ -202,6 +351,16 @@ const transactionPolicySchema = z
   .object({
     defaultWriteApproval: z.enum(["required", "policy", "none"]).default("required"),
     maxValueUsd: z.number().positive().optional(),
+    // Oracle-free native-token spend ceiling (wei). This is the ONLY value cap
+    // wallet-engine can actually enforce — maxValueUsd hard-throws without a
+    // price oracle. Decimal or 0x-hex string (parsed via BigInt downstream).
+    maxValueWei: z
+      .string()
+      .regex(
+        /^(0x[0-9a-fA-F]+|[0-9]+)$/,
+        "maxValueWei must be a wei amount as a decimal or 0x-hex string",
+      )
+      .optional(),
     allowedContracts: z.array(z.string().min(1)).default([]),
     simulationRequired: z.boolean().default(true),
   })
@@ -282,7 +441,7 @@ const channelGatewayBlock = z
 
 const cliSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("cli"),
     agent: z
       .object({
@@ -296,6 +455,7 @@ const cliSchema = z
     mcp_servers: mcpServersBlock,
     permissions: permissionsBlock,
     compaction: compactionBlock,
+    security: securityBlock,
     failure_taxonomy: failureTaxonomyBlock,
     cli: cliOptionsBlock,
     chains: chainsBlock,
@@ -307,7 +467,7 @@ const cliSchema = z
 
 const workflowStepSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     instructions: z.string().min(1),
     model: z.string().min(1).optional(),
     tools: z.array(z.string().min(1)).optional(),
@@ -317,7 +477,7 @@ const workflowStepSchema = z
 
 const workflowSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("workflow"),
     model: z.string().min(1),
     steps: z.array(workflowStepSchema).min(1),
@@ -414,7 +574,7 @@ const channelAgentSchema = z
 
 const channelSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("channel"),
     agent: channelAgentSchema,
     channels: channelsBlock,
@@ -464,11 +624,11 @@ const graphEdgeSchema = z
 
 const graphSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("graph"),
     model: z.string().min(1),
     entry: z.string().min(1),
-    nodes: z.record(z.string().min(1), graphNodeSchema),
+    nodes: z.record(safeName, graphNodeSchema),
     edges: z.array(graphEdgeSchema).default([]),
     permissions: permissionsBlock,
     compaction: compactionBlock,
@@ -505,7 +665,7 @@ const managedAgentSchema = z
 
 const managedSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("managed"),
     agent: managedAgentSchema,
     tenants: z.array(managedTenantSchema).min(1),
@@ -515,6 +675,17 @@ const managedSchema = z
   })
   .strict();
 
+// Vector-store backend ids accepted in specs. Mirrors `VectorBackendId`
+// from @crewhaus/vector-store (and `IrVectorBackend`) — the canonical set
+// of implemented backends — kept inline so the spec stays dependency-light.
+// Keep in sync when a backend is added or removed.
+const VECTOR_BACKENDS = ["in-memory", "lance", "qdrant", "pinecone", "weaviate"] as const;
+
+// The HTTP backends construct only with a `url` + `collection` (the
+// vector-store factory throws otherwise); parseSpec requires both so a
+// spec that selects one without them fails at compile, not at runtime.
+const HTTP_VECTOR_BACKENDS = new Set(["qdrant", "pinecone", "weaviate"]);
+
 // Pipeline / RAG target (Section 21). Carries the embedder + vector-store
 // config, an indexing pipeline, and a chat agent that uses Retrieve.
 const pipelineDocumentSchema = z
@@ -527,7 +698,7 @@ const pipelineDocumentSchema = z
 
 const pipelineSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("pipeline"),
     agent: z
       .object({
@@ -538,8 +709,16 @@ const pipelineSchema = z
     retrieve: z
       .object({
         embedderModel: z.string().min(1),
-        vectorBackend: z.enum(["in-memory"]).default("in-memory"),
+        vectorBackend: z.enum(VECTOR_BACKENDS).default("in-memory"),
         defaultK: z.number().int().positive().max(50).default(5),
+        // Remote (qdrant/pinecone/weaviate) + file (lance) backend config.
+        // `url` is the service base URL (or, for lance, the on-disk index
+        // path); `apiKey` accepts a `$ENV_REF` so the secret resolves from
+        // `process.env` in the bundle rather than being baked into it. The
+        // HTTP backends require `url` + `collection` (enforced in parseSpec).
+        url: z.string().min(1).optional(),
+        collection: z.string().min(1).optional(),
+        apiKey: z.string().min(1).optional(),
       })
       .strict(),
     indexing: z
@@ -588,12 +767,12 @@ const crewRoutingSchema = z
 
 const crewSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("crew"),
     /** Crew-wide model fallback used by any role that omits `role.model`. */
     model: z.string().min(1),
     entry: z.string().min(1),
-    roles: z.record(z.string().min(1), crewRoleSchema),
+    roles: z.record(safeName, crewRoleSchema),
     routing: crewRoutingSchema.optional(),
     mcp_servers: mcpServersBlock,
     permissions: permissionsBlock,
@@ -618,13 +797,13 @@ const researchRetrieveSchema = z
   .object({
     allowedOrigins: z.array(z.string().min(1)).default([]),
     allowedFileRoots: z.array(z.string().min(1)).default([]),
-    vectorBackend: z.enum(["in-memory"]).optional(),
+    vectorBackend: z.enum(VECTOR_BACKENDS).optional(),
   })
   .strict();
 
 const researchSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("research"),
     agent: z
       .object({
@@ -665,7 +844,7 @@ const batchQueueSchema = z
 
 const batchSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("batch"),
     agent: z
       .object({
@@ -708,7 +887,7 @@ const voiceTelephonySchema = z
 
 const voiceSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("voice"),
     agent: z
       .object({
@@ -744,7 +923,7 @@ const browserDriverSchema = z
 
 const browserSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("browser"),
     agent: z
       .object({
@@ -774,7 +953,7 @@ const browserSchema = z
  */
 const evalSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("eval"),
     agent: z
       .object({
@@ -785,7 +964,7 @@ const evalSchema = z
       .strict(),
     dataset: z
       .object({
-        name: z.string().min(1),
+        name: safeName,
         version: z.string().min(1),
         split: z.enum(["train", "dev", "test"]).default("dev"),
       })
@@ -794,7 +973,7 @@ const evalSchema = z
       .array(
         z
           .object({
-            name: z.string().min(1),
+            name: safeName,
             opts: z.record(z.unknown()).optional(),
           })
           .strict(),
@@ -842,7 +1021,7 @@ const onchainTriggerSchema = z.discriminatedUnion("kind", [
 
 const onchainSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("onchain"),
     agent: z
       .object({
@@ -877,7 +1056,7 @@ const onchainSchema = z
  */
 const onchainGameSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("onchain-game"),
     agent: z
       .object({
@@ -965,6 +1144,7 @@ export type SpecEval = z.infer<typeof evalSchema>;
 export type SpecMcpServerConfig = z.infer<typeof mcpServerConfigSchema>;
 export type SpecSubAgentDefinition = z.infer<typeof subAgentDefinitionSchema>;
 export type SpecCompactionBlock = z.infer<typeof compactionBlock>;
+export type SpecSecurityBlock = z.infer<typeof securityBlock>;
 export type SpecFailureTaxonomyEntry = z.infer<typeof failureTaxonomyEntrySchema>;
 export type SpecFailureTaxonomy = z.infer<typeof failureTaxonomyBlock>;
 
@@ -1031,5 +1211,23 @@ export function parseSpec(yamlText: string): Spec {
       }
     }
   }
+  // Section 21 — pipeline HTTP-backend invariants. qdrant/pinecone/weaviate
+  // throw at construction without a url + collection, so selecting one
+  // without both would emit an unrunnable bundle. Reject at parse time with
+  // a message naming the missing field (kept here, not as a `.refine()`, so
+  // the discriminated-union member stays a plain ZodObject).
+  if (data.target === "pipeline" && HTTP_VECTOR_BACKENDS.has(data.retrieve.vectorBackend)) {
+    const { vectorBackend, url, collection } = data.retrieve;
+    if (!url) {
+      throw new SpecParseError(
+        `pipeline retrieve.vectorBackend "${vectorBackend}" requires retrieve.url (the remote service base URL)`,
+      );
+    }
+    if (!collection) {
+      throw new SpecParseError(
+        `pipeline retrieve.vectorBackend "${vectorBackend}" requires retrieve.collection`,
+      );
+    }
+  }
   return data;
 }