@vauban-org/agent-sdk 1.0.0 → 1.2.0

package/dist/verify/formal/spec-language.js

@@ -0,0 +1,219 @@
+/**
+ * src/verify/formal/spec-language.ts
+ *
+ * Sprint-587 — DSL for axiom specifications, compiled to SMT-LIB v2.
+ *
+ * Design philosophy (inspired by FormalJudge, arXiv:2602.11136) : agent-cycle
+ * properties are expressed as small, typed pre/post-condition tuples. Each
+ * condition is mapped to an SMT-LIB fragment by {@link compileToSmt}, which
+ * frames the property as a NEGATION of the post-conditions under the
+ * pre-conditions. This way, Z3 returning `sat` means a counterexample exists
+ * (= UNSAFE) and `unsat` means the post-conditions hold (= SAFE).
+ *
+ * Bound types : Reals for budgets and ratios, Bools for binary properties,
+ * Sets-as-symbols for scope subset checks.
+ *
+ * @module verify/formal/spec-language
+ */
+function ensureDecl(ctx, decl, name) {
+    if (ctx.declared.has(name))
+        return;
+    ctx.declared.add(name);
+    ctx.declarations.push(decl);
+}
+/**
+ * Lower a single Condition into SMT-LIB assertions appended to `ctx`.
+ * `negated` flag : when true, the condition is being added as a negated
+ * post-condition (i.e. we want to find a counterexample).
+ */
+function lowerCondition(c, ctx, negated) {
+    switch (c.type) {
+        case "budget_constraint": {
+            // parent_budget >= 0, child_budget >= 0, child_budget <= parent_budget * fraction
+            ensureDecl(ctx, "(declare-const parent_budget Real)", "parent_budget");
+            ensureDecl(ctx, "(declare-const child_budget Real)", "child_budget");
+            // Positivity is part of the pre-state, always assert.
+            ctx.assertions.push("(assert (>= parent_budget 0))");
+            ctx.assertions.push("(assert (>= child_budget 0))");
+            const expr = `(<= child_budget (* parent_budget ${c.child_max_fraction}))`;
+            ctx.assertions.push(`(assert ${negated ? `(not ${expr})` : expr})`);
+            return;
+        }
+        case "scope_subset": {
+            // Encode each child element as a Bool : it must be present in parent.
+            // We do this by reducing to a boolean conjunction over the listed
+            // child elements. Mismatches surface as a counterexample.
+            const parentSet = new Set(c.parent_scope);
+            const childOk = c.child_scope.every((s) => parentSet.has(s));
+            // No declarations needed — fold the result statically into a bool.
+            const expr = childOk ? "true" : "false";
+            ctx.assertions.push(`(assert ${negated ? `(not ${expr})` : expr})`);
+            return;
+        }
+        case "no_pii_in_output": {
+            const name = c.pii_count_var ?? "pii_count";
+            ensureDecl(ctx, `(declare-const ${name} Int)`, name);
+            // pii_count >= 0 (always)
+            ctx.assertions.push(`(assert (>= ${name} 0))`);
+            const expr = `(= ${name} 0)`;
+            ctx.assertions.push(`(assert ${negated ? `(not ${expr})` : expr})`);
+            return;
+        }
+        case "cost_positive_roi": {
+            ensureDecl(ctx, "(declare-const cost Real)", "cost");
+            ensureDecl(ctx, "(declare-const value Real)", "value");
+            ctx.assertions.push("(assert (> cost 0))");
+            ctx.assertions.push("(assert (>= value 0))");
+            const expr = `(>= (/ value cost) ${c.min_roi_ratio})`;
+            ctx.assertions.push(`(assert ${negated ? `(not ${expr})` : expr})`);
+            return;
+        }
+        case "response_time": {
+            ensureDecl(ctx, "(declare-const response_ms Real)", "response_ms");
+            ctx.assertions.push("(assert (>= response_ms 0))");
+            const expr = `(<= response_ms ${c.max_ms})`;
+            ctx.assertions.push(`(assert ${negated ? `(not ${expr})` : expr})`);
+            return;
+        }
+        case "custom_smt": {
+            const frag = c.smt_fragment.trim();
+            // The custom fragment is expected to be a parenthesised assertion body.
+            if (negated) {
+                ctx.assertions.push(`(assert (not ${frag}))`);
+            }
+            else {
+                ctx.assertions.push(`(assert ${frag})`);
+            }
+            return;
+        }
+    }
+}
+/**
+ * Compile an {@link AxiomSpec} into an SMT-LIB v2 program string.
+ *
+ * Pattern : preconditions are asserted as-is ; postconditions are joined by
+ * conjunction and asserted NEGATED. A counterexample (z3 returns `sat`)
+ * therefore means : "pre-conditions hold AND at least one post-condition
+ * fails" — i.e. an UNSAFE outcome.
+ *
+ * Includes `(check-sat)` and `(get-model)` as terminating commands.
+ */
+export function compileToSmt(spec) {
+    const ctx = {
+        declared: new Set(),
+        declarations: [],
+        assertions: [],
+    };
+    // Header — set logic to QF_LRA (quantifier-free linear real arithmetic
+    // plus integers) which covers all our supported condition kinds.
+    const header = ["(set-logic ALL)", `; AxiomSpec : ${spec.axiom}`];
+    // Preconditions : assert as-is (positive form).
+    for (const pre of spec.preconditions) {
+        lowerCondition(pre, ctx, false);
+    }
+    // Postconditions : conjoin and negate.
+    // Strategy : assert each one negated separately using De Morgan. We want
+    //   NOT (post1 AND post2 AND …) ≡ (NOT post1) OR (NOT post2) OR …
+    // For check-sat-as-counterexample, we want the solver to find *any*
+    // violation, so we encode the disjunction with an auxiliary Bool flag
+    // per postcondition. Simpler equivalent : assert (or (not post1) (not post2) …).
+    if (spec.postconditions.length === 0) {
+        // Empty postcondition set : trivially SAFE (no obligation to verify).
+        ctx.assertions.push("(assert false)");
+    }
+    else if (spec.postconditions.length === 1) {
+        lowerCondition(spec.postconditions[0], ctx, true);
+    }
+    else {
+        // Build per-postcondition expression strings via a side-context, then
+        // emit a single `(assert (or ...))`.
+        const subCtx = {
+            declared: ctx.declared,
+            declarations: ctx.declarations,
+            assertions: [],
+        };
+        const negatedExprs = [];
+        for (const post of spec.postconditions) {
+            const before = subCtx.assertions.length;
+            lowerCondition(post, subCtx, true);
+            // The last appended assertion is "(assert <neg expr>)" or pre-assertions.
+            // To recover only the negated post-condition body, we accept that some
+            // conditions append additional non-negotiable preconditions (positivity).
+            // Those are valid in any case and stay in the main assertion list.
+            for (let i = before; i < subCtx.assertions.length; i++) {
+                const a = subCtx.assertions[i];
+                // Heuristic : split positivity asserts (>= x 0) and the negated body.
+                // The negated body always contains "(not ".
+                if (a.includes("(not ")) {
+                    // Extract the inner expr "(not …)" inside the outer assert.
+                    const inner = a.slice("(assert ".length, -1);
+                    negatedExprs.push(inner);
+                }
+            }
+            // Drop the negated body assertions from subCtx so we only keep
+            // the positivity ones in the main assertion list.
+            subCtx.assertions = subCtx.assertions.filter((a) => !a.includes("(not "));
+        }
+        ctx.assertions = subCtx.assertions;
+        ctx.assertions.push(`(assert (or ${negatedExprs.join(" ")}))`);
+    }
+    return [
+        ...header,
+        ...ctx.declarations,
+        ...ctx.assertions,
+        "(check-sat)",
+        "(get-model)",
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Pre-built specs for the 5 Vauban axioms
+// ---------------------------------------------------------------------------
+/**
+ * Default per-axiom AxiomSpec presets. Consumers can override the timeout
+ * or augment with additional conditions before passing to `formalVerify`.
+ *
+ * Robuste        : 5s — engineering robustness, may need richer checks
+ * Institutionnel : 10s — strongest spec, PII + scope-subset + budget
+ * SOTA           : 2s  — lightweight (single ROI check on cost)
+ * AntiFragile    : 1s  — response-time bound only
+ * Profitable     : 1s  — cost-vs-value ROI check
+ */
+export const AXIOM_SPECS = {
+    Robuste: {
+        axiom: "Robuste",
+        preconditions: [],
+        postconditions: [
+            { type: "budget_constraint", child_max_fraction: 1.0 },
+            { type: "response_time", max_ms: 30_000 },
+        ],
+        timeout_ms: 5000,
+    },
+    Institutionnel: {
+        axiom: "Institutionnel",
+        preconditions: [],
+        postconditions: [
+            { type: "no_pii_in_output" },
+            { type: "budget_constraint", child_max_fraction: 1.0 },
+        ],
+        timeout_ms: 10_000,
+    },
+    SOTA: {
+        axiom: "SOTA",
+        preconditions: [],
+        postconditions: [{ type: "cost_positive_roi", min_roi_ratio: 1.0 }],
+        timeout_ms: 2000,
+    },
+    AntiFragile: {
+        axiom: "AntiFragile",
+        preconditions: [],
+        postconditions: [{ type: "response_time", max_ms: 60_000 }],
+        timeout_ms: 1000,
+    },
+    Profitable: {
+        axiom: "Profitable",
+        preconditions: [],
+        postconditions: [{ type: "cost_positive_roi", min_roi_ratio: 1.5 }],
+        timeout_ms: 1000,
+    },
+};
+//# sourceMappingURL=spec-language.js.map

package/dist/verify/formal/spec-language.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-language.js","sourceRoot":"","sources":["../../../src/verify/formal/spec-language.ts"],"names":[],"mappings":"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"}

package/docs/attestation.md

@@ -0,0 +1,199 @@
+# Run Certificate Verification (Standalone)
+
+**Module:** `@vauban-org/agent-sdk/proof/cert-verify` · **Since:** CC v3.1 sprint-562 (Livrable D, 2026-05-14)
+
+The standalone verifier in `src/proof/cert-verify.ts` verifies a `SignedRunProofCertificate` without any database or network dependency. It is the verification counterpart to the CC server's signing surface (`src/proof/ed25519-signer.ts`) and implements [draft-vauban-skill-attestation-00 §5](https://datatracker.ietf.org/doc/draft-vauban-skill-attestation/).
+
+Suitable for: CI pipelines, third-party integrators, audits, and the `preste attest verify` CLI command.
+
+## Quick start
+
+```typescript
+import { verifyRunCertificate } from "@vauban-org/agent-sdk/proof/cert-verify";
+import { readFileSync } from "node:fs";
+
+const cert = JSON.parse(readFileSync("cert.json", "utf-8"));
+
+const result = verifyRunCertificate(cert);
+
+if (!result.valid) {
+  console.error(`Verification failed: ${result.reason} — ${result.details}`);
+  process.exit(1);
+}
+
+console.log("Certificate valid. hash:", result.recomputed_cert_hash_felt252);
+```
+
+---
+
+## Imports
+
+```typescript
+import {
+  verifyRunCertificate,
+  computeCertHashFelt252,
+  publicKeyFromSpkiB64,
+  CERT_MARKER_FELT,
+} from "@vauban-org/agent-sdk/proof/cert-verify";
+
+import type {
+  CertVerifyResult,
+  CertVerifyFailReason,
+  CertVerifyOptions,
+  SignedRunProofCertificateLike,
+  SignaturePayload,
+} from "@vauban-org/agent-sdk/proof/cert-verify";
+```
+
+---
+
+## Types
+
+```typescript
+interface CertVerifyResult {
+  valid: boolean;
+  reason?: CertVerifyFailReason;          // only when valid === false
+  details?: string;                       // human-readable context
+  recomputed_cert_hash_felt252: string;   // always present — useful for debug
+}
+
+type CertVerifyFailReason =
+  | "missing_signature"    // cert.signature field absent
+  | "wrong_alg"            // alg !== "Ed25519"
+  | "hash_mismatch"        // embedded cert_hash_felt252 != recomputed
+  | "kid_mismatch"         // expectedKid set and does not match
+  | "pubkey_unresolvable"  // SPKI base64 malformed or not Ed25519
+  | "signature_invalid"    // Ed25519 verify returns false
+  | "malformed_signature"; // signature.value is not valid base64 / wrong length
+
+interface CertVerifyOptions {
+  expectedPublicKey?: KeyObject;  // Node.js KeyObject (bypass embedded SPKI)
+  expectedKid?: string;           // pin to a specific key ID
+}
+```
+
+---
+
+## `verifyRunCertificate(cert, opts?)`
+
+```typescript
+function verifyRunCertificate(
+  cert: SignedRunProofCertificateLike,
+  opts?: CertVerifyOptions
+): CertVerifyResult
+```
+
+Returns synchronously — all crypto is Node.js built-in `node:crypto`. Never throws on verification failure; only throws when `cert` is not a plain object.
+
+`recomputed_cert_hash_felt252` is always returned regardless of outcome — use it to debug `hash_mismatch` failures without a separate call.
+
+### Basic verification
+
+```typescript
+const result = verifyRunCertificate(cert);
+if (!result.valid) {
+  console.error(`Invalid: ${result.reason} — ${result.details}`);
+}
+```
+
+### Pin to a known public key (recommended for production)
+
+```typescript
+import { publicKeyFromSpkiB64, verifyRunCertificate } from "@vauban-org/agent-sdk/proof/cert-verify";
+
+const pubkey = publicKeyFromSpkiB64(process.env["CC_ATTEST_PUBKEY_SPKI_B64"]!);
+
+const result = verifyRunCertificate(cert, { expectedPublicKey: pubkey });
+```
+
+`publicKeyFromSpkiB64` throws if the base64 is malformed or the key is not Ed25519. Call it once at startup and cache the `KeyObject`.
+
+### Pin to a key ID
+
+```typescript
+const result = verifyRunCertificate(cert, {
+  expectedKid: "cc-attest-2026-05",
+});
+// → reason: "kid_mismatch" if cert was signed with a different key
+```
+
+### CI pipeline — exit code gate
+
+```typescript
+import { verifyRunCertificate } from "@vauban-org/agent-sdk/proof/cert-verify";
+import { readFileSync } from "node:fs";
+
+const cert = JSON.parse(readFileSync("cert.json", "utf-8"));
+const { valid, reason, recomputed_cert_hash_felt252 } = verifyRunCertificate(cert);
+
+console.log(`hash: ${recomputed_cert_hash_felt252}`);
+process.exit(valid ? 0 : 1);
+```
+
+---
+
+## Verification algorithm
+
+Implements draft-vauban-skill-attestation-00 §5. Seven sequential checks — the first failure stops the chain:
+
+| Step | Check | Failure reason |
+|------|-------|----------------|
+| 1 | `cert.signature` field is present | `missing_signature` |
+| 2 | `signature.alg === "Ed25519"` | `wrong_alg` |
+| 3 | Strip `signature`, JCS-canonicalize (RFC 8785 subset: sorted keys, `-0 → 0`), SHA-256 first 31 bytes → felt252, Poseidon(`[0x1, sha_felt, CERT_MARKER_FELT]`) — compare with `signature.cert_hash_felt252` | `hash_mismatch` |
+| 4 | If `opts.expectedKid` set, compare with `signature.kid` | `kid_mismatch` |
+| 5 | Resolve public key: `opts.expectedPublicKey` if provided, else `publicKeyFromSpkiB64(signature.pubkey_spki_b64)` | `pubkey_unresolvable` |
+| 6 | Decode `signature.value` from base64, assert 64 bytes | `malformed_signature` |
+| 7 | Ed25519 verify: `crypto.verify(null, felt252Bytes(recomputed), pubkey, sigBytes)` | `signature_invalid` |
+
+**`CERT_MARKER_FELT`** is the domain separator — UTF-8 `"run_cert"` encoded as a felt252 (right-aligned, zero-padded). It prevents cross-context signature reuse: a signature over a different cert type cannot satisfy the Poseidon preimage.
+
+---
+
+## `computeCertHashFelt252(cert)`
+
+Standalone hash computation — useful for debugging `hash_mismatch` failures.
+
+```typescript
+import { computeCertHashFelt252 } from "@vauban-org/agent-sdk/proof/cert-verify";
+
+const expected = cert.signature?.cert_hash_felt252;
+const recomputed = computeCertHashFelt252(cert);
+
+if (expected !== recomputed) {
+  console.error("Hash mismatch:");
+  console.error("  embedded  :", expected);
+  console.error("  recomputed:", recomputed);
+}
+```
+
+`computeCertHashFelt252` strips the embedded `signature` field before hashing — calling it on a signed cert and on the pre-signature cert produces the same result.
+
+---
+
+## Security considerations
+
+!!! warning "Treat embedded `pubkey_spki_b64` as a key-discovery hint, not a security guarantee"
+    The `pubkey_spki_b64` field in `signature` helps resolve the signing key for display and debugging, but an attacker can substitute it with their own public key and produce a valid self-consistent signature.
+
+    For production use, always pin to a known public key via `opts.expectedPublicKey` (loaded from a trusted source such as an environment variable, K8s secret, or a JWKS registry keyed on `signature.kid`). Never accept a certificate as authoritative based solely on its embedded public key.
+
+---
+
+## `preste attest verify` CLI
+
+The standalone verifier is the engine behind the CLI command:
+
+```bash
+preste attest verify cert.json
+# Exit 0: certificate valid
+# Exit 1: verification failed — reason printed to stderr
+
+preste attest verify cert.json --kid cc-attest-2026-05
+# Adds kid pinning
+
+preste attest verify cert.json --pubkey "$CC_ATTEST_PUBKEY_SPKI_B64"
+# Pins to an explicit SPKI base64 public key
+```
+
+The CLI sets `process.exitCode` to `1` on failure so it composes naturally with `&&` in shell scripts and CI steps.

package/docs/identity.md

@@ -0,0 +1,193 @@
+# Agent Identity & Persona
+
+**Module:** `@vauban-org/agent-sdk` · **Since:** CC v3.1 sprint-562 (Livrable E, 2026-05-14)
+
+An `AgentPersona` is a structured description of how an agent communicates — tone, formality, domain expertise, and response-shape preferences. The persona travels from Brain Tier 3 (semantic storage) through the CC server as a system-prompt prefix, and can be overridden locally via `~/.preste/persona.yaml`.
+
+## Quick start
+
+```typescript
+import {
+  buildPersonaPromptBlock,
+  mergePersona,
+  DEFAULT_PERSONA,
+  validatePersona,
+} from "@vauban-org/agent-sdk";
+import type { AgentPersona } from "@vauban-org/agent-sdk";
+
+const persona: AgentPersona = {
+  identity: {
+    name: "ARCHITECT",
+    role: "Senior Cairo/TypeScript engineer",
+    tone: "concise",
+    formality: "technical",
+    language: "en",
+  },
+  domain_expertise: ["Starknet", "TypeScript", "ZK proofs"],
+  communication: {
+    acknowledgment_style: "minimal",
+    explain_reasoning: "on_error",
+  },
+};
+
+const systemPrompt =
+  "You are an agent in the Vauban ecosystem." +
+  buildPersonaPromptBlock(persona);
+```
+
+The `buildPersonaPromptBlock` call appends the block only when actionable fields are present — it is safe to concatenate unconditionally.
+
+---
+
+## `AgentPersona` schema
+
+All fields are optional. Zod validation enforces the limits below; `PersonaSchema.parse(input)` throws on violation.
+
+```typescript
+interface AgentPersona {
+  identity?: {
+    name?: string;       // max 64 chars
+    role?: string;       // max 256 chars
+    tone?: "concise" | "detailed" | "pedagogical";
+    formality?: "casual" | "formal" | "technical";
+    language?: string;   // BCP 47, e.g. "en", "fr-FR"
+  };
+  traits?: string[];           // max 16 items, max 64 chars each
+  domain_expertise?: string[]; // max 32 items, max 128 chars each
+  communication?: {
+    max_response_length?: number;
+    use_analogies?: boolean;
+    explain_reasoning?: "always" | "on_error" | "never";
+    acknowledgment_style?: "minimal" | "detailed" | "none";
+  };
+}
+```
+
+`DEFAULT_PERSONA` is applied before any user-defined value:
+
+```typescript
+const DEFAULT_PERSONA: AgentPersona = {
+  identity: { tone: "concise", formality: "technical", language: "en" },
+  traits: [],
+  domain_expertise: [],
+  communication: { explain_reasoning: "on_error", acknowledgment_style: "minimal" },
+};
+```
+
+---
+
+## `buildPersonaPromptBlock(persona)`
+
+Converts an `AgentPersona` to a compact system-prompt block bounded by `--- persona ---` / `--- end persona ---` markers.
+
+```typescript
+import { buildPersonaPromptBlock } from "@vauban-org/agent-sdk";
+
+const block = buildPersonaPromptBlock({
+  identity: { name: "SCRIBE", tone: "pedagogical", formality: "formal" },
+  domain_expertise: ["technical writing", "API documentation"],
+  communication: { explain_reasoning: "always" },
+});
+
+// block ===
+// \n--- persona ---
+// You are SCRIBE.
+// Communication style: pedagogical, formal.
+// Domain expertise: technical writing, API documentation.
+// Always explain your reasoning step by step.
+// --- end persona ---
+```
+
+**Properties:**
+
+- Returns `""` when the persona has no actionable fields — safe for unconditional concatenation.
+- `language` field only emits an instruction when it differs from `"en"`.
+- Empty `traits` / `domain_expertise` arrays produce no output.
+- The leading `\n` ensures correct spacing when appended to an existing system prompt.
+
+---
+
+## Merge semantics
+
+`mergePersona(base, local)` applies `local` on top of `base` field-by-field. Brain Tier 3 is the base; `~/.preste/persona.yaml` is the local override.
+
+```typescript
+import { mergePersona, DEFAULT_PERSONA } from "@vauban-org/agent-sdk";
+
+const brainPersona: AgentPersona = {
+  identity: { name: "BUILDER", tone: "concise" },
+  domain_expertise: ["Cairo", "TypeScript"],
+};
+
+const localOverride: AgentPersona = {
+  identity: { tone: "detailed" },       // overrides tone only
+  domain_expertise: ["Rust"],           // REPLACES the array entirely
+};
+
+const resolved = mergePersona(
+  mergePersona(DEFAULT_PERSONA, brainPersona),
+  localOverride,
+);
+// resolved.identity.name === "BUILDER"  (from brainPersona)
+// resolved.identity.tone === "detailed" (from localOverride)
+// resolved.domain_expertise === ["Rust"] (array replaced, not extended)
+```
+
+!!! warning "Array replacement semantics"
+    `traits` and `domain_expertise` are **replaced**, not extended. If you want to extend the Brain-stored array, concatenate before calling `mergePersona`:
+    ```typescript
+    const extended = mergePersona(base, {
+      ...local,
+      domain_expertise: [...(base.domain_expertise ?? []), ...(local.domain_expertise ?? [])],
+    });
+    ```
+
+---
+
+## System-level injection (CC server)
+
+Set `CC_AGENT_PERSONA_JSON` on the CC server to inject the persona as a system message prefix for every agent call, without modifying agent code.
+
+**Generate the env value:**
+
+```bash
+echo '{"identity":{"name":"ARCHITECT","role":"Senior Cairo/TypeScript engineer","tone":"concise","formality":"technical"},"domain_expertise":["Starknet","TypeScript","ZK proofs"],"communication":{"acknowledgment_style":"minimal","explain_reasoning":"on_error"}}' | base64 -w0
+```
+
+```bash
+export CC_AGENT_PERSONA_JSON="<base64 output>"
+```
+
+The CC server decodes, validates via `PersonaSchema.parse`, and calls `buildPersonaPromptBlock` before prepending to each agent system message.
+
+---
+
+## CLI persona management
+
+The `preste persona` sub-command manages the local `~/.preste/persona.yaml` override file.
+
+```bash
+preste persona show                                         # display resolved persona (Brain + local merge)
+preste persona set --name ARCHITECT --role "..." --tone concise --formality technical
+preste persona export persona.yaml                          # write to YAML file
+preste persona import persona.yaml                          # load from YAML file (validates schema)
+preste persona reset                                        # delete ~/.preste/persona.yaml (revert to Brain-only)
+```
+
+`preste persona show` prints the fully-resolved persona (Brain base + local override + defaults) and the rendered `buildPersonaPromptBlock` output so you can inspect what the model will receive.
+
+---
+
+## Validation
+
+```typescript
+import { validatePersona } from "@vauban-org/agent-sdk";
+
+try {
+  const persona = validatePersona(untrustedInput);
+} catch (err) {
+  // ZodError — inspect err.issues for field-level messages
+}
+```
+
+`validatePersona` wraps `PersonaSchema.parse` and throws `ZodError` on invalid input. Call it at ingestion boundaries (e.g., when loading `~/.preste/persona.yaml` or deserializing from Brain).