phaedo-mcp 0.1.0

package/cache.js

@@ -0,0 +1,76 @@
+// MCP Phase 1b-iii — encrypted at-rest fingerprint cache.
+//
+// So the server can serve injections when the phone is ABSENT (the frictionless
+// default — desktop/CLI use where the phone often isn't reachable). Mirrors the
+// extension's Option C: the fingerprint is cached as CIPHERTEXT under a
+// server-held key. Defense-in-depth for a DERIVED cache only — NOT phone-gated,
+// NOT forensic-grade: the device can decrypt itself, and the cache is always
+// recoverable from the phone (re-pull) on loss.
+//
+// Key storage (v1): a 32-byte AES key in a 0600 file. Weaker than the extension's
+// non-extractable WebCrypto key (the raw bytes are on disk), because Node has no
+// IndexedDB-style non-extractable-key store that survives restarts. OS-keychain
+// storage is the hardening follow-up. The cache file holds only ciphertext.
+
+import { mkdir, readFile, writeFile, chmod, rm } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { Phaedo, b64uEnc, b64uDec } from './lib/phaedo-crypto.js';
+
+const { Envelope } = Phaedo;
+
+export function defaultStateDir() {
+  return process.env.PHAEDO_MCP_STATE_DIR || join(homedir(), '.phaedo-mcp');
+}
+
+async function ensureDir(dir) { await mkdir(dir, { recursive: true, mode: 0o700 }); }
+
+export async function getOrCreateCacheKey(stateDir) {
+  await ensureDir(stateDir);
+  const keyPath = join(stateDir, 'cache.key');
+  if (existsSync(keyPath)) return b64uDec((await readFile(keyPath, 'utf8')).trim());
+  const key = crypto.getRandomValues(new Uint8Array(32));
+  await writeFile(keyPath, b64uEnc(key), { mode: 0o600 });
+  await chmod(keyPath, 0o600);
+  return key;
+}
+
+// Encrypt + persist the vault payload. `now` injectable for tests.
+export async function writeCache(stateDir, vaultPayload, now = Date.now()) {
+  const key = await getOrCreateCacheKey(stateDir);
+  const plaintext = new TextEncoder().encode(JSON.stringify(vaultPayload));
+  const envelope = await Envelope.wrap(plaintext, key, {
+    artifact_kind: 'fingerprint',
+    fingerprint_id: vaultPayload?.phaedo_fingerprint?.fingerprint_id || null,
+    created_at: new Date(now).toISOString(),
+  });
+  plaintext.fill(0);
+  const cachePath = join(stateDir, 'cache.enc');
+  await writeFile(cachePath, JSON.stringify({ envelope, cached_at: now }), { mode: 0o600 });
+  await chmod(cachePath, 0o600);
+}
+
+// Remove the at-rest cache. Used on revocation: a cached profile must not
+// outlive authorization, so once the phone rejects this client the ciphertext
+// copy is deleted (the cache is always re-pullable after a fresh pairing).
+export async function clearCache(stateDir) {
+  try { await rm(join(stateDir, 'cache.enc'), { force: true }); } catch { /* nothing to clear */ }
+}
+
+// Decrypt the cache → { vault, cachedAt } or null (absent/corrupt/undecryptable
+// → treated as no cache, since it's recoverable from the phone).
+export async function readCache(stateDir) {
+  const cachePath = join(stateDir, 'cache.enc');
+  if (!existsSync(cachePath)) return null;
+  try {
+    const key = await getOrCreateCacheKey(stateDir);
+    const { envelope, cached_at } = JSON.parse(await readFile(cachePath, 'utf8'));
+    const plaintext = await Envelope.unwrap(envelope, key);
+    const vault = JSON.parse(new TextDecoder().decode(plaintext));
+    plaintext.fill(0);
+    return { vault, cachedAt: cached_at };
+  } catch {
+    return null;
+  }
+}

package/consult-core.js

@@ -0,0 +1,439 @@
+// Phaedo §10 Agent Consultation — the PURE resolver core.
+//
+// resolveConsultationCore(vd, request[, opts]) -> §10.3 response. PURE: no browser
+// globals, no chrome, no fs, no network, no model, no process, no side effects —
+// the same discipline that makes context-block.js reusable across runtimes. The
+// OPTIONAL local model judge and all transport/config live in consult.js (the MCP
+// wrapper). Keeping the deterministic shapes here and the model there makes the
+// open-core line a file boundary (brief Invariant 7): this file is the publishable
+// reference resolver; the judge is the proprietary-side upgrade that wraps it.
+//
+// Resolution order (deterministic → authored): (A) inferred Decision/Risk signal,
+// confidence-gated; (B) abstain floor — if NO relevant cue was found, return
+// `insufficient_signal` rather than a confidently-wrong guess (§10.3); (C) authored
+// standing policies (§10.5) override either, so a hard guardrail wins even over an
+// abstain. Signals out, never structure out (§10.4).
+
+import { PhaedoError } from './errors.js';
+import { loadPolicies, applyPolicies, matchAuthorization } from './consult-policy.js';
+
+export const CONSULTATION_TYPES = [
+  'action_approval',
+  'voice_draft',
+  'domain_risk_check',
+  'escalation_default',
+];
+
+// §10.3 signal enum. `insufficient_signal` (abstain) is the producer declining to
+// answer for lack of coverage — distinct from `clarify` (gather more) and from an
+// error. Folded into the spec at v0.1.9 (proposal 0001).
+export const SIGNALS = ['proceed', 'proceed_with_note', 'clarify', 'escalate', 'decline', 'insufficient_signal'];
+const MAGNITUDES = ['low', 'medium', 'high'];
+
+// NOTE: for UNTAGGED signals (all fingerprints today), coverage is fingerprint-WIDE —
+// a rich fingerprint never abstains on an unfamiliar domain. As domain-TAGGED
+// Decision&Risk signals accrue (extraction/domain-inference.js prototype), coverage
+// becomes per-domain naturally: signals tagged for a different domain are skipped,
+// so a fingerprint whose relevant signals are all wrong-domain abstains here.
+const ABSTAIN_HINT =
+  'The fingerprint has no decision/risk coverage to ground a signal, so the oracle ' +
+  'abstains — fall back to your own default or escalate to the subject.';
+
+// ── vd contract guard (brief M0.4) ────────────────────────────────────────────
+// The consultation boundary's mirror of context-block.js validateVaultData (which
+// cannot be imported here — it is a classic browser script; the two are kept in
+// agreement by scripts/test_context_block_snapshots.mjs's cross-check). A breach
+// throws a structured PhaedoError naming the violating field — a malformed vault
+// payload is a producer bug and must never be resolved silently with partial data.
+// A MISSING fingerprint stays `decryption_failed` (the source had nothing), and
+// weird-but-conforming content (odd signal values, empty layers) still resolves
+// defensively — this guard rejects only type breaches of the documented vd shape
+// (spec/schemas/vault-data.schema.json).
+const isPlainObject = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
+export function validateVaultShape(vd) {
+  const errors = [];
+  if (!isPlainObject(vd)) return ['vault data must be a plain object'];
+  const fp = vd.phaedo_fingerprint;
+  if (fp !== undefined && fp !== null) {
+    if (!isPlainObject(fp)) errors.push('phaedo_fingerprint must be an object');
+    else {
+      if (!isPlainObject(fp.layers)) errors.push('phaedo_fingerprint.layers must be an object');
+      else for (const [id, L] of Object.entries(fp.layers)) if (!isPlainObject(L)) errors.push(`layer "${id}" must be an object`);
+      if (fp.persona_strength !== undefined && (typeof fp.persona_strength !== 'number' || fp.persona_strength < 0 || fp.persona_strength > 1))
+        errors.push('persona_strength must be a number in [0,1]');
+      if (fp.fingerprint_id !== undefined && fp.fingerprint_id !== null && typeof fp.fingerprint_id !== 'string')
+        errors.push('fingerprint_id must be a string');
+    }
+  }
+  for (const k of ['phaedo_behavioral_signals', 'phaedo_linguistic_profile', 'phaedo_session_metrics'])
+    if (vd[k] !== undefined && vd[k] !== null && !isPlainObject(vd[k])) errors.push(`${k} must be an object`);
+  return errors;
+}
+
+function assertVaultUsable(vd) {
+  if (!vd || !vd.phaedo_fingerprint) {
+    throw new PhaedoError('decryption_failed', 'No fingerprint available from the configured source.');
+  }
+  const errors = validateVaultShape(vd);
+  if (errors.length) {
+    throw new PhaedoError('internal_error', `vault data malformed: ${errors.join('; ')}`);
+  }
+}
+
+// ── Low-level fingerprint reads (defensive; never throw) ──────────────────────
+function layer(vd, id) { return vd?.phaedo_fingerprint?.layers?.[id]; }
+
+// Evidence basis of a signal, derived from its `source` (proposal 0002 vocabulary).
+// Drives how much a cue's per-signal confidence is trusted (below): observed/
+// corroborated learned signals > self-reported questionnaire answers > a bare
+// keyword hit in free text.
+function evidenceBasis(source) {
+  const s = String(source || '').toLowerCase();
+  if (s.includes('corrobor') || s.includes('reconcil')) return 'corroborated';
+  if (s.includes('question') || s.includes('self') || s.includes('interview')) return 'self_reported';
+  return 'observed'; // extraction/delta-sourced structured signals
+}
+const BASIS_WEIGHT = { observed: 1.0, corroborated: 1.0, self_reported: 0.9, text_scan: 0.75 };
+
+// Does a signal's §4.2.7 domain tag pertain to the action's domain? Same
+// case-insensitive substring convention as authored policies (either direction:
+// signal "financial" matches action "financial services" and vice versa).
+function domainMatches(sigDomain, actionDomain) {
+  const a = String(sigDomain).toLowerCase(), b = String(actionDomain).toLowerCase();
+  return a.includes(b) || b.includes(a);
+}
+
+// Resolve a relevant cue to { text, confidence, basis }, preferring a structured
+// §4.2 signal (which carries a real per-signal confidence + provenance) over a
+// dimensioned questionnaire response. Returns undefined when neither is present
+// (caller falls back to a free-text keyword scan). Positive/neutral polarity only.
+//
+// Domain preference (PROTOTYPE, §4.2.7 optional `domain`): when the action carries
+// a domain, a signal TAGGED with a matching domain wins; an UNTAGGED signal is the
+// fallback (today's fingerprint-wide behavior); a signal tagged with a DIFFERENT
+// domain is skipped — financial caution must not drive a writing decision. When
+// the action has no domain, tags are ignored (any field-matching signal serves).
+function signalCue(vd, layerId, fields, actionDomain) {
+  const L = layer(vd, layerId);
+  if (!L) return undefined;
+  const want = new Set(fields);
+  const asCue = (s) => {
+    const confidence = typeof s.confidence === 'number' ? Math.max(0, Math.min(1, s.confidence)) : 0.6;
+    // Prefer the producer-emitted evidence_basis (proposal 0002); else derive from source.
+    const basis = typeof s.evidence_basis === 'string' ? s.evidence_basis : evidenceBasis(s.source);
+    return { text: String(Array.isArray(s.value) ? s.value.join(' ') : s.value).toLowerCase(), confidence, basis };
+  };
+  let untagged;
+  for (const s of (L.signals || [])) {
+    if (!(s && want.has(s.field) && (s.polarity ?? 'positive') !== 'negative' && s.value != null)) continue;
+    if (typeof s.domain === 'string' && actionDomain) {
+      if (domainMatches(s.domain, actionDomain)) return asCue(s); // domain match wins outright
+      continue;                                                   // wrong domain — skip
+    }
+    if (typeof s.domain === 'string' && !actionDomain) return asCue(s); // no action domain → tags ignored
+    if (!untagged) untagged = asCue(s);                                  // untagged fallback
+  }
+  if (untagged) return untagged;
+  for (const r of (L.responses || L.answers || [])) {
+    const dim = r?.dimension || r?.field;
+    const v = r?.value ?? r?.answer;
+    if (dim && want.has(dim) && v != null) return { text: String(v).toLowerCase(), confidence: 0.7, basis: 'self_reported' };
+  }
+  return undefined;
+}
+
+// All free-text the layer carries (interview answers + learned summary), lowercased
+// — the fallback corpus for the keyword scan when a clean signal isn't present.
+function layerText(vd, layerId) {
+  const L = layer(vd, layerId);
+  if (!L) return '';
+  const parts = [];
+  for (const r of (L.responses || [])) if (r?.answer) parts.push(String(r.answer));
+  for (const r of (L.answers || []))   { const v = r?.answer ?? r?.value; if (v != null) parts.push(String(v)); }
+  if (typeof L.summary === 'string') parts.push(L.summary);
+  return parts.join('  \n  ').toLowerCase();
+}
+
+const hit = (text, needles) => needles.some(n => text.includes(n));
+
+// ── Cue catalog ───────────────────────────────────────────────────────────────
+// Each cue resolves a lean from a signal field if present, else from a keyword
+// scan of its layers' text. lean: +1 = cautious/high-bar, -1 = bold/fast, 0 = unknown.
+// Keywords are DIRECTIONAL phrases, not bare words — "quality over speed" must
+// read as cautious even though it contains "speed".
+const CUES = {
+  irreversibleCaution: {
+    layers: ['decision_and_risk'],
+    fields: ['reversible_vs_irreversible', 'irreversible_style'],
+    cautious: ['more_cautious', 'more cautious', 'seek more input', 'careful_still', 'think longer', 'longer_think'],
+    bold: ['consistent_style', 'consistent regardless', 'style is consistent', 'fast_adjust', 'decide fast'],
+  },
+  decisionThreshold: {
+    layers: ['behavioral', 'decision_and_risk'],
+    fields: ['decision_threshold'],
+    cautious: ['cover_risks', 'covered the main risks', 'cover the main risks', 'main risks before', 'depends_reversibility'],
+    bold: ['act_adjust', 'act on the best', 'adjust as i learn', 'best signal available'],
+  },
+  evidenceBar: {
+    layers: ['decision_and_risk'],
+    fields: ['evidence_bar', 'value_tradeoffs', 'evidence_threshold'],
+    cautious: ['accuracy over', 'thoroughness over', 'thoroughness', 'high evidence', 'evidence bar: high', 'consistency over'],
+    bold: ['speed over', 'simplicity over', 'adaptability over', 'good enough'],
+  },
+  speedQuality: {
+    layers: ['decision_and_risk'],
+    fields: ['speed_vs_quality'],
+    cautious: ['quality over', 'accuracy over'],
+    bold: ['speed over', 'fast over'],
+  },
+};
+
+// Ambiguity has a distinct axis (ask-first vs proceed), resolved separately.
+const AMBIGUITY = {
+  layers: ['behavioral', 'decision_and_risk'],
+  fields: ['handling_ambiguity', 'ambiguity_response', 'ambiguity_posture'],
+  askFirst: ['ask_first', 'clarifying question', 'ask a clarifying', 'ask before doing'],
+  proceed: ['assume_silent', 'assume_state', 'reasonable assumption', 'offer_two', 'offer two interpretations'],
+};
+
+function readCue(vd, spec, actionDomain) {
+  let cue;
+  for (const lid of spec.layers) { cue = signalCue(vd, lid, spec.fields, actionDomain); if (cue) break; } // a structured §4.2 signal wins
+  const text = cue ? cue.text : spec.layers.map(lid => layerText(vd, lid)).join('  ');       // else scan answers/summary
+  if (!text) return { found: false, lean: 0, confidence: 0, basis: null };
+  const c = hit(text, spec.cautious), b = hit(text, spec.bold);
+  const found = c || b;
+  const lean = (c && !b) ? 1 : (b && !c) ? -1 : 0; // both/neither → present but neutral
+  // per-cue confidence + basis: a structured signal carries its own; a keyword hit
+  // in free text is the weakest evidence (text_scan).
+  return { found, lean, confidence: found ? (cue ? cue.confidence : 0.6) : 0, basis: found ? (cue ? cue.basis : 'text_scan') : null };
+}
+
+function readAmbiguity(vd, actionDomain) {
+  let cue;
+  for (const lid of AMBIGUITY.layers) { cue = signalCue(vd, lid, AMBIGUITY.fields, actionDomain); if (cue) break; }
+  const text = cue ? cue.text : AMBIGUITY.layers.map(lid => layerText(vd, lid)).join('  ');
+  const confidence = cue ? cue.confidence : 0.6;
+  const basis = cue ? cue.basis : 'text_scan';
+  if (hit(text, AMBIGUITY.askFirst)) return { found: true, value: 'ask_first', confidence, basis };
+  if (hit(text, AMBIGUITY.proceed))  return { found: true, value: 'proceed', confidence, basis };
+  return { found: false, value: null, confidence: 0, basis: null };
+}
+
+function personaStrength(vd) {
+  const v = vd?.phaedo_fingerprint?.persona_strength;
+  return typeof v === 'number' ? Math.max(0, Math.min(1, v)) : 0.4;
+}
+
+// Build a scoped caution profile from ONLY the cues relevant to this consultation
+// type (§10 relevance scoping). Returns the caution score (0..1), the coverage
+// (found / relevant), the raw `found` count (0 = no relevant cue → abstain), and
+// the ambiguity verdict.
+function profile(vd, relevantCues, includeAmbiguity, actionDomain) {
+  let score = 0.5, found = 0, total = relevantCues.length + (includeAmbiguity ? 1 : 0);
+  const effConfs = []; // per-cue confidence × evidence-basis weight, for the cues actually used
+  for (const key of relevantCues) {
+    const r = readCue(vd, CUES[key], actionDomain);
+    if (r.found) { found++; score += r.lean * 0.13; effConfs.push(r.confidence * (BASIS_WEIGHT[r.basis] ?? 0.75)); }
+  }
+  let ambiguity = { found: false, value: null };
+  if (includeAmbiguity) {
+    ambiguity = readAmbiguity(vd, actionDomain);
+    if (ambiguity.found) { found++; if (ambiguity.value === 'ask_first') score += 0.13; effConfs.push(ambiguity.confidence * (BASIS_WEIGHT[ambiguity.basis] ?? 0.75)); }
+  }
+  return {
+    score: Math.max(0, Math.min(1, score)),
+    coverage: total ? found / total : 0,
+    found,
+    signalConfidence: effConfs.length ? effConfs.reduce((a, b) => a + b, 0) / effConfs.length : 0,
+    ambiguity,
+  };
+}
+
+// Confidence + deference for a resolved consultation.
+//   deference_level — breadth: RELEVANT cue coverage × persona strength (unchanged).
+//   confidence — now blends that breadth with `signalConfidence`: the mean per-signal
+//     confidence (evidence-basis weighted) of the cues actually used. So confidence
+//     VARIES with how strong/observed the underlying Decision&Risk signals are, rather
+//     than sitting flat across every action on one fingerprint (the fix for the pinned-
+//     confidence critique). A fingerprint of strong observed signals reads confident; a
+//     thin/keyword-only one reads low. `signalConfidence` 0 (no usable cues — e.g. the
+//     abstain floor's calibrate(vd,0)) → the breadth model alone, so abstain is unchanged.
+function calibrate(vd, coverage, signalConfidence = 0) {
+  const ps = personaStrength(vd);
+  const breadth = 0.3 + 0.4 * coverage * ps + 0.2 * ps;
+  const confidence = signalConfidence > 0
+    ? 0.45 * breadth + 0.55 * signalConfidence * (0.6 + 0.4 * ps)
+    : breadth;
+  const deference_level = (coverage >= 0.66 && ps >= 0.5) ? 'high'
+                        : (coverage >= 0.33 && ps >= 0.3) ? 'medium'
+                        : 'low';
+  return { confidence: Math.round(Math.max(0, Math.min(1, confidence)) * 100) / 100, deference_level };
+}
+
+const magnitudeRank = (m) => ({ low: 0, medium: 1, high: 2 }[m] ?? 1);
+
+// ── Request validation/normalization (§10.2) ──────────────────────────────────
+export function normalizeRequest(request) {
+  const type = request.consultation_type;
+  if (!CONSULTATION_TYPES.includes(type)) {
+    throw new PhaedoError('request_malformed', `Unknown consultation_type: ${type}. One of: ${CONSULTATION_TYPES.join(', ')}.`);
+  }
+  const ad = (request.action_descriptor && typeof request.action_descriptor === 'object') ? request.action_descriptor : {};
+  let magnitude = typeof ad.magnitude === 'string' ? ad.magnitude.toLowerCase() : undefined;
+  if (magnitude && !MAGNITUDES.includes(magnitude)) {
+    throw new PhaedoError('request_malformed', `magnitude must be one of: ${MAGNITUDES.join(', ')}.`);
+  }
+  const ctx = (request.context && typeof request.context === 'object') ? request.context : {};
+  const ev = ctx.evidence_provided;
+  return {
+    type,
+    domain: typeof ad.domain === 'string' ? ad.domain : undefined,
+    reversible: typeof ad.reversible === 'boolean' ? ad.reversible : undefined,
+    magnitude: magnitude || 'medium',
+    amount: typeof ad.amount === 'number' && isFinite(ad.amount) ? ad.amount : undefined,
+    summary: typeof ad.summary === 'string' ? ad.summary : undefined,
+    evidenceProvided: Array.isArray(ev) ? ev : (ev != null ? [ev] : []),
+  };
+}
+
+// ── Per-type resolvers → { signal, hint, coverage, found } ────────────────────
+function resolveActionApproval(vd, n) {
+  const p = profile(vd, ['irreversibleCaution', 'decisionThreshold', 'evidenceBar'], true, n.domain);
+  const irreversible = n.reversible === false;
+  const mag = magnitudeRank(n.magnitude);
+  const thinEvidence = n.evidenceProvided.length === 0;
+
+  let signal;
+  if (irreversible && mag >= 2) {
+    signal = p.score >= 0.55 ? (thinEvidence ? 'clarify' : 'escalate')
+           : p.score >= 0.4  ? 'escalate'
+           : 'proceed_with_note';
+  } else if (irreversible || mag >= 2) {
+    signal = p.score >= 0.6 ? 'escalate'
+           : (thinEvidence && p.score >= 0.45) ? 'clarify'
+           : 'proceed_with_note';
+  } else {
+    signal = p.score >= 0.7 ? 'proceed_with_note' : 'proceed';
+  }
+  const domain = n.domain ? ` in the ${n.domain} domain` : '';
+  const posture = p.score >= 0.55 ? 'favors caution and human review'
+                : p.score <= 0.4  ? 'favors acting and adjusting'
+                : 'weighs the main risks before committing';
+  const hint = irreversible
+    ? `On irreversible${mag >= 2 ? ', high-magnitude' : ''} actions${domain}, the subject ${posture}.`
+    : `On reversible actions${domain}, the subject ${posture}.`;
+  return { signal, hint, coverage: p.coverage, found: p.found, signalConfidence: p.signalConfidence };
+}
+
+function resolveDomainRiskCheck(vd, n) {
+  const p = profile(vd, ['evidenceBar', 'speedQuality', 'decisionThreshold'], false, n.domain);
+  const high = p.score >= 0.55;
+  const signal = high ? 'clarify' : p.score <= 0.4 ? 'proceed' : 'proceed_with_note';
+  const where = n.domain ? ` in ${n.domain}` : '';
+  const posture = high ? 'holds a high evidence bar and prefers thoroughness'
+                : p.score <= 0.4 ? 'is comfortable moving on the best available signal'
+                : 'balances evidence against speed';
+  return { signal, hint: `Risk posture${where}: the subject ${posture}.`, coverage: p.coverage, found: p.found, signalConfidence: p.signalConfidence };
+}
+
+function resolveEscalationDefault(vd, n) {
+  const p = profile(vd, ['decisionThreshold', 'irreversibleCaution'], true, n.domain);
+  let signal;
+  if (p.ambiguity.value === 'ask_first') signal = 'clarify';
+  else if (p.ambiguity.value === 'proceed') signal = 'proceed_with_note';
+  else signal = p.score >= 0.55 ? 'escalate' : 'clarify';
+  const hint = signal === 'clarify'
+    ? 'When uncertain, the subject defaults to asking a clarifying question before acting.'
+    : signal === 'escalate'
+      ? 'When uncertain on consequential calls, the subject defaults to surfacing for a live decision.'
+      : 'When uncertain on low-stakes calls, the subject defaults to a reasonable assumption, stated openly.';
+  return { signal, hint, coverage: p.coverage, found: p.found, signalConfidence: p.signalConfidence };
+}
+
+// voice_draft: v0 does not generate text. Voice == style == the injection
+// projection, so point the agent there (§10.4: content goes through injection).
+function resolveVoiceDraft() {
+  return {
+    signal: 'clarify',
+    hint: 'Drafting in the subject’s voice is served by the injection projection — call phaedo_request_injection and write in that style. (Generation is out of scope for consultation v0.)',
+    coverage: null,
+    found: null,
+  };
+}
+
+// §10.3 response shape — the ONLY fields that cross the boundary (§10.4).
+export function shape(type, signal, confidence, rationale_hint, deference_level) {
+  return {
+    phaedo_response_version: '0.1',
+    request_type: 'consultation',
+    consultation_type: type,
+    signal: SIGNALS.includes(signal) ? signal : 'clarify',
+    confidence: Math.max(0, Math.min(1, Number(confidence) || 0)),
+    rationale_hint: String(rationale_hint || '').replace(/\s+/g, ' ').trim().slice(0, 280),
+    deference_level: ['high', 'medium', 'low'].includes(deference_level) ? deference_level : 'medium',
+  };
+}
+
+// ── Rule resolver (deterministic, local, always available — the floor) ─────────
+export function ruleResponse(vd, n) {
+  let resolved;
+  switch (n.type) {
+    case 'action_approval':    resolved = resolveActionApproval(vd, n); break;
+    case 'domain_risk_check':  resolved = resolveDomainRiskCheck(vd, n); break;
+    case 'escalation_default': resolved = resolveEscalationDefault(vd, n); break;
+    case 'voice_draft':        resolved = resolveVoiceDraft(); break;
+  }
+  // Abstain floor (§10.3 `insufficient_signal`): a real decision type with ZERO
+  // relevant cues has no pattern basis. Say so rather than emit a signal derived
+  // only from the action's structure — a confidently-wrong answer is the worst
+  // output (brief principle 2). Structural safety belongs in authored policy (step
+  // C below), which still overrides this abstain. voice_draft never abstains (it's
+  // a redirect). An authored policy can still force a decision on top of this.
+  if (n.type !== 'voice_draft' && resolved.found === 0) {
+    return shape(n.type, 'insufficient_signal', calibrate(vd, 0).confidence, ABSTAIN_HINT, 'low');
+  }
+  const cal = n.type === 'voice_draft'
+    ? { confidence: 0.2, deference_level: 'low' }
+    : calibrate(vd, resolved.coverage, resolved.signalConfidence);
+  return shape(n.type, resolved.signal, cal.confidence, resolved.hint, cal.deference_level);
+}
+
+// ── Public pure entry ─────────────────────────────────────────────────────────
+// (vd, request[, opts]) -> §10.3 response. Deterministic; applies authored §10.5
+// policies last so a standing guardrail wins (even over an abstain). `opts.policies`
+// (a loaded local-config policy doc, passed in by the server) is data, not I/O —
+// the file read happens in the transport layer, so this stays pure.
+export function resolveConsultationCore(vd, request = {}, opts = {}) {
+  assertVaultUsable(vd);
+  const n = normalizeRequest(request);
+  return applyPolicies(ruleResponse(vd, n), n, loadPolicies(vd, opts));
+}
+
+// Back-compat alias: the prior public name of the sync rule entry. Kept so existing
+// importers (tests, spec/test-schemas.mjs) are unchanged.
+export const buildConsultationResponse = resolveConsultationCore;
+
+// ── Deterministic-only authorization check (brief M3) ─────────────────────────
+// (vd, request[, opts]) -> a small, fixed-shape result. Checks ONLY standing
+// authorizations (§10.5 force rules) — it does NOT run inferred evaluation, so it is
+// a fast pre-flight an agent can call before a full consultation: "is this already
+// decided by one of my standing rules?". A matched authorization is the subject's
+// deterministic pre-decision (confidence 1.0, deference high, by definition). Honors
+// §10.4 (no layer content crosses — only the rule's decision + provenance note).
+export function checkAuthorization(vd, request = {}, opts = {}) {
+  assertVaultUsable(vd);
+  const n = normalizeRequest(request);
+  const auth = matchAuthorization(n, loadPolicies(vd, opts));
+  return {
+    phaedo_response_version: '0.1',
+    request_type: 'authorization_check',
+    consultation_type: n.type,
+    authorization_matched: !!auth,
+    signal: auth ? auth.signal : null,
+    rule_id: auth ? (auth.rule.id || null) : null,
+    rationale_hint: auth
+      ? `Per your standing rule: ${auth.note}.`.replace(/\s+/g, ' ').trim().slice(0, 280)
+      : 'No standing authorization matches this action; run phaedo_consult for a full signal, or apply your own default.',
+  };
+}

package/consult-policies.sample.json

@@ -0,0 +1,36 @@
+{
+  "version": "0.1",
+  "_comment": "Standing AUTHORIZATIONS for phaedo_consult (§10.5): subject-authored rules that OVERRIDE the inferred signal. Force effects (escalate | require_human | decline | autoproceed) resolve the decision deterministically at confidence:1.0, deference:high; bias_cautious | bias_bold nudge one step. match: domains[] (substring, case-insensitive) · magnitude_min/max (low|medium|high) · reversible (true/false) · amount_gt (number; needs action_descriptor.amount). Portable: copy into the vault as phaedo_fingerprint.consult_policies, or point PHAEDO_CONSULT_POLICIES at this file to try them.",
+  "rules": [
+    {
+      "id": "irreversible-spend-over-5k-escalate",
+      "match": { "domains": ["financial", "payment", "spend", "purchase"], "reversible": false, "amount_gt": 5000 },
+      "effect": "escalate",
+      "note": "Any irreversible spend over $5,000 goes to me for a live decision"
+    },
+    {
+      "id": "irreversible-legal-escalate",
+      "match": { "domains": ["legal", "contract"], "reversible": false },
+      "effect": "escalate",
+      "note": "Irreversible legal or contract actions always go to a human"
+    },
+    {
+      "id": "autonomous-external-email-decline",
+      "match": { "domains": ["external email", "outbound email", "cold outreach"] },
+      "effect": "decline",
+      "note": "Do not send autonomous external email on my behalf"
+    },
+    {
+      "id": "low-stakes-writing-autoproceed",
+      "match": { "domains": ["writing", "draft", "internal note", "content"], "magnitude_max": "medium", "reversible": true },
+      "effect": "autoproceed",
+      "note": "Low-stakes, reversible writing is pre-approved"
+    },
+    {
+      "id": "people-matters-bias-cautious",
+      "match": { "domains": ["immigration", "hr", "personnel", "visa"] },
+      "effect": "bias_cautious",
+      "note": "Lean cautious on people / immigration matters"
+    }
+  ]
+}