@rubytech/create-maxy-code 0.1.446 → 0.1.448

package/payload/premium-plugins/writer-craft/mcp/src/tools/voice-distil-profile.ts

@@ -1,833 +0,0 @@
-/**
- * voice-distil-profile — walk the operator's `human-only` corpus and
- * persist a `:VoiceProfile` style card.
- *
- * Task 462: one `:VoiceProfile` per `(accountId, userId, format)`.
- * `format` ∈ `{text, email, social-post, article, marketing-copy, note}`.
- *
- *   - When `format` is supplied, distils that format only.
- *   - When `format` is omitted, enumerates distinct format values present
- *     in the corpus (nodes where `n.format IS NOT NULL`) and distils each
- *     that fires the cadence guard. Returns `skipReason: 'no-format-tagged-content'`
- *     when enumeration yields zero formats.
- *
- * Cadence guard: re-runs on ≥20% corpus growth since last profile, OR
- * ≥30 days since `generatedAt`. `force: true` overrides both.
- *
- * Body-text sampling caps at ~120k chars (rough proxy for tokens at
- * 4 chars/token = 30k tokens) — well inside Haiku's 200k context window
- * with headroom for the system prompt + tool schema.
- *
- * Task 424 — the Haiku style-card composition moved into the calling agent's
- * turn. The agent reads the corpus exemplars and feedback intents (this tool
- * returns them when called with `mode='sample'`), composes the style-card
- * YAML, then calls this tool again with `mode='write'` + `styleCardYaml` set.
- */
-import neo4j from "neo4j-driver";
-import { getSession } from "../lib/neo4j.js";
-import { notTrashed } from "../lib/voice-corpus.js";
-import {
-  VOICE_CORPUS_WHERE,
-  voiceCorpusWhereWithFormat,
-  voiceCorpusWhereWithFormatAndAuthor,
-  profileUserIdForScope,
-  FORMAT_VALUES,
-  type VoiceFormat,
-  type VoiceScope,
-} from "../lib/voice-corpus.js";
-
-/**
- * Coerce a neo4j cypher RETURN value to a plain JS number.
- *
- * Neo4j-driver represents INTs as `Integer` objects (high/low 32-bit
- * pair to safely carry int64). `Number()` *usually* works via valueOf()
- * but the safe path is `Integer#toNumber()`. Returns null when the
- * value is null/undefined so cadence-guard arithmetic stays explicit
- * about the "no prior profile" case.
- */
-function toJsNumber(value: unknown): number | null {
-  if (value === null || value === undefined) return null;
-  if (typeof value === "number") return value;
-  if (neo4j.isInt(value)) return (value as { toNumber: () => number }).toNumber();
-  if (typeof value === "string") {
-    const parsed = Number(value);
-    return Number.isFinite(parsed) ? parsed : null;
-  }
-  return null;
-}
-
-const SAMPLE_CHAR_CAP = 120_000;
-const RE_RUN_GROWTH_FRACTION = 0.2;
-const RE_RUN_AGE_DAYS = 30;
-
-export interface VoiceDistilProfileParams {
-  accountId: string;
-  userId: string;
-  /**
-   * Profile scope (Task 676). `'personal'` (default) distils the operator's
-   * own author-filtered corpus onto `:AdminUser`; `'org'` distils the whole
-   * account onto `:LocalBusiness` under the reserved sentinel userId.
-   */
-  scope?: VoiceScope;
-  force?: boolean;
-  /**
-   * Writing format to distil. When omitted on `sample`, enumerates distinct
-   * format values in the corpus and distils each that fires the cadence
-   * guard. Required on `amend` and `write`.
-   */
-  format?: VoiceFormat;
-  /**
-   * Operation mode:
-   *   - `'sample'` (default, Task 424) — walk the full per-format corpus and
-   *     return exemplars + feedback intents. No write. The calling agent
-   *     composes the style-card YAML in-turn.
-   *   - `'write'` (Task 424) — persist the style card the agent produced.
-   *     Requires `styleCardYaml`. Optional `amendedFromNodeIds` adds
-   *     `LEARNED_FROM` edges to the named nodes (additive — MERGE preserves
-   *     prior edges).
-   *   - `'amend'` (Task 472) — operator-initiated incremental update from
-   *     one or more named documents. Reads only those nodes plus the
-   *     existing `:VoiceProfile.styleCard` so the agent can decide whether
-   *     the document moves the profile. Format predicate is dropped on the
-   *     read (the operator picked the docs); `authorshipMode` + trashed +
-   *     label predicates still apply per-document. Cadence guard does not
-   *     apply.
-   */
-  mode?: "sample" | "write" | "amend";
-  /** Required when `mode='write'`. The style-card YAML produced by the agent. */
-  styleCardYaml?: string;
-  /**
-   * Required when `mode='amend'`. ElementIds of the documents to fold into
-   * the profile. Each id is eligibility-checked; ineligible ones are
-   * reported in the return payload (the agent surfaces them to the operator).
-   */
-  nodeIds?: string[];
-  /**
-   * Optional on `mode='write'` after an `amend` sample. ElementIds the
-   * agent decided moved the profile. Each becomes a `LEARNED_FROM` edge
-   * from the persisted `:VoiceProfile`. Additive — pre-existing edges
-   * remain via `MERGE`.
-   */
-  amendedFromNodeIds?: string[];
-}
-
-export interface VoiceCorpusExemplar {
-  id: string;
-  label: string;
-  body: string;
-}
-
-export interface VoiceDistilProfileResult {
-  profileId: string | null;
-  corpusSize: number;
-  generatedAt: string | null;
-  feedbackEntries: number;
-  skipped: boolean;
-  /** Present only on the multi-format path: the format this result was distilled for. */
-  format?: VoiceFormat;
-  skipReason?:
-    | "below-threshold"
-    | "recent"
-    | "empty-corpus"
-    | "missing-style-card"
-    | "no-format-tagged-content"
-    | "amend-no-eligible-documents";
-  errorReason?: string;
-  /** Present when `mode='sample'` or `mode='amend'`: corpus exemplars for the agent to read. */
-  exemplars?: VoiceCorpusExemplar[];
-  /** Present when `mode='sample'` or `mode='amend'`: operator-edit intents to fold into the style card. */
-  feedbackIntents?: string[];
-  /**
-   * Present when `mode='amend'`: the current `:VoiceProfile.styleCard` (or
-   * null if no profile exists yet) so the agent can compare the named
-   * documents against the prior card and decide update-or-skip.
-   */
-  existingStyleCard?: string | null;
-  /** Present when `mode='amend'`: count of input nodeIds that passed eligibility. */
-  eligible?: number;
-  /**
-   * Present when `mode='amend'`: per-input-id ineligibility records. Each
-   * entry names the nodeId and the first failing predicate so the agent
-   * can tell the operator which documents were rejected and why.
-   */
-  ineligible?: { nodeId: string; reason: string }[];
-}
-
-// The agent produces a YAML style card with at minimum these keys:
-//   sentenceLengthDistribution, register, favoured, avoided, taboos,
-//   openingPattern, closingPattern, exemplarSentences
-// Exemplar sentences should be quoted verbatim from the returned corpus.
-
-/**
- * Single-format distil. Opens a new session for each call.
- */
-async function distilForFormat(
-  params: Required<Pick<VoiceDistilProfileParams, "accountId" | "userId">> &
-    Pick<VoiceDistilProfileParams, "force" | "mode" | "styleCardYaml" | "scope"> & {
-      format: VoiceFormat;
-    },
-): Promise<VoiceDistilProfileResult> {
-  const { accountId, userId, format, force = false } = params;
-  const scope: VoiceScope = params.scope ?? "personal";
-  const profileUserId = profileUserIdForScope(scope, userId);
-  const anchorLabel = scope === "org" ? "LocalBusiness" : "AdminUser";
-  // Org walks the whole account; personal narrows to one author's content.
-  const corpusWhere =
-    scope === "org"
-      ? voiceCorpusWhereWithFormat(format)
-      : voiceCorpusWhereWithFormatAndAuthor(format);
-  const corpusParams =
-    scope === "org"
-      ? { accountId, format }
-      : { accountId, format, voiceAuthor: userId };
-  const session = getSession();
-  const now = new Date();
-  const nowIso = now.toISOString();
-
-  try {
-    // 1. Read existing scoped profile (if any) for cadence-guard comparison.
-    //    Key-only match — the (accountId, profileUserId, format) triple is the
-    //    unique constraint key, so no anchor traversal is needed on the read.
-    const existing = await session.run(
-      `OPTIONAL MATCH (p:VoiceProfile {accountId: $accountId, userId: $profileUserId, format: $format})
-       RETURN elementId(p) AS profileId, p.corpusSize AS corpusSize,
-              p.generatedAt AS generatedAt`,
-      { accountId, profileUserId, format },
-    );
-    const existingRow = existing.records[0];
-    const prevProfileId = (existingRow?.get("profileId") as string | null) ?? null;
-    const prevCorpusSize = toJsNumber(existingRow?.get("corpusSize"));
-    const prevGeneratedAt = (existingRow?.get("generatedAt") as string | null) ?? null;
-
-    // 2. Count corpus for this scope + format.
-    const countResult = await session.run(
-      `MATCH (n)
-       WHERE ${corpusWhere}
-       RETURN count(n) AS c`,
-      corpusParams,
-    );
-    const corpusSize = toJsNumber(countResult.records[0]?.get("c")) ?? 0;
-
-    if (corpusSize === 0) {
-      process.stderr.write(
-        `[voice-distil] scope=${scope} userId=${profileUserId} format=${format} skip reason=empty-corpus\n`,
-      );
-      return {
-        profileId: prevProfileId,
-        corpusSize: 0,
-        generatedAt: prevGeneratedAt,
-        feedbackEntries: 0,
-        skipped: true,
-        skipReason: "empty-corpus",
-      };
-    }
-
-    // 3. Cadence guard.
-    if (!force && prevProfileId && prevCorpusSize !== null && prevGeneratedAt) {
-      const ageMs = now.getTime() - new Date(prevGeneratedAt).getTime();
-      const ageDays = ageMs / (24 * 60 * 60 * 1000);
-      const growth =
-        prevCorpusSize > 0
-          ? (corpusSize - prevCorpusSize) / prevCorpusSize
-          : 1;
-      const ageTrigger = ageDays >= RE_RUN_AGE_DAYS;
-      const growthTrigger = growth >= RE_RUN_GROWTH_FRACTION;
-      if (!ageTrigger && !growthTrigger) {
-        const reason = ageDays < 1 ? "recent" : "below-threshold";
-        process.stderr.write(
-          `[voice-distil] scope=${scope} userId=${profileUserId} format=${format} skip reason=${reason} corpusSize=${corpusSize} prevCorpus=${prevCorpusSize} ageDays=${ageDays.toFixed(1)}\n`,
-        );
-        return {
-          profileId: prevProfileId,
-          corpusSize,
-          generatedAt: prevGeneratedAt,
-          feedbackEntries: 0,
-          skipped: true,
-          skipReason: reason,
-        };
-      }
-    }
-
-    // 4. Sample corpus bodies up to the char cap. Pick recent first.
-    //
-    // Body resolution (Task 471):
-    //   - For a :KnowledgeDocument with HAS_SECTION children, concatenate
-    //     child :Section bodies in `position` order — KD.body itself is
-    //     null after the Task 465 server-slicing change.
-    //   - Other labels (:Message, :SocialPost, :Section chat chunks) read
-    //     n.body directly via the existing COALESCE fallback chain.
-    //
-    // `collect(s.body)` is null-skipping in Cypher, so KDs with no children
-    // produce sectionBodies = [] and fall through to the COALESCE branch
-    // correctly. The `usedSectionWalk` flag is returned for per-exemplar
-    // observability.
-    const sampled = await session.run(
-      `MATCH (n)
-       WHERE ${corpusWhere}
-       WITH n, coalesce(n.dateSent, n.datePublished, n.firstMessageAt, n.dateCreated, n.createdAt) AS ts
-       OPTIONAL MATCH (parent:KnowledgeDocument)-[:HAS_SECTION]->(n)
-       WHERE 'Section' IN labels(n) AND parent.conversationIdentity IS NOT NULL
-         AND ${notTrashed("parent")}
-       WITH n, ts, parent
-       OPTIONAL MATCH (n)-[:HAS_SECTION]->(s:Section)
-       WHERE ${notTrashed("s")}
-       WITH n, ts, parent, s ORDER BY s.position
-       WITH n, ts, parent, collect(s.body) AS sectionBodies
-       WITH n, ts, parent,
-            'KnowledgeDocument' IN labels(n) AND size(sectionBodies) > 0 AS usedSectionWalk,
-            CASE
-              WHEN 'KnowledgeDocument' IN labels(n) AND size(sectionBodies) > 0
-                THEN reduce(acc = '', b IN sectionBodies | acc + b + '\n\n')
-              ELSE coalesce(n.body, n.abstract, n.subject, n.title, n.summary, '')
-            END AS body
-       RETURN elementId(n) AS id,
-              labels(n) AS labels,
-              body,
-              usedSectionWalk,
-              parent.conversationIdentity IS NOT NULL AS isConversationChunk,
-              ts
-       ORDER BY ts IS NULL, ts DESC
-       LIMIT 500`,
-      corpusParams,
-    );
-    const samples: { id: string; label: string; body: string }[] = [];
-    let sectionWalkCount = 0;
-    let nBodyCount = 0;
-    let charBudget = SAMPLE_CHAR_CAP;
-    for (const r of sampled.records) {
-      const body = (r.get("body") as string | null) ?? "";
-      const labels = (r.get("labels") as string[]) ?? [];
-      const isConversationChunk = Boolean(r.get("isConversationChunk"));
-      const usedSectionWalk = Boolean(r.get("usedSectionWalk"));
-      const label = isConversationChunk
-        ? "Conversation"
-        : (labels.find((l) =>
-            ["KnowledgeDocument", "Message", "SocialPost"].includes(l),
-          ) ?? labels[0] ?? "Unknown");
-      if (body.length === 0) continue;
-      const trimmed = body.length > charBudget ? body.slice(0, charBudget) : body;
-      samples.push({ id: r.get("id") as string, label, body: trimmed });
-      if (usedSectionWalk) sectionWalkCount += 1;
-      else nBodyCount += 1;
-      charBudget -= trimmed.length;
-      if (charBudget <= 0) break;
-    }
-
-    // 5. Pull feedback intents from existing :VoiceEdit nodes for this scope +
-    //    format. Keyed by profileUserId: org edits live under the sentinel, so
-    //    org distil reads org feedback and personal distil reads only this
-    //    operator's edits — no extra scope predicate needed.
-    const feedback = await session.run(
-      `MATCH (e:VoiceEdit {userId: $profileUserId, accountId: $accountId, format: $format})
-       RETURN e.intent AS intent ORDER BY e.occurredAt DESC LIMIT 50`,
-      { accountId, profileUserId, format },
-    );
-    const feedbackIntents = feedback.records
-      .map((r) => r.get("intent") as string | null)
-      .filter((x): x is string => typeof x === "string" && x.length > 0);
-
-    // 6. Mode branch (Task 424).
-    const mode = params.mode ?? "sample";
-    if (mode === "sample") {
-      process.stderr.write(
-        `[voice-distil] scope=${scope} userId=${profileUserId} format=${format} mode=sample corpusSize=${corpusSize} ` +
-          `exemplars=${samples.length} feedbackEntries=${feedbackIntents.length} ` +
-          `sample-body-source=section-walk:${sectionWalkCount} n.body:${nBodyCount}\n`,
-      );
-      return {
-        profileId: prevProfileId,
-        corpusSize,
-        generatedAt: prevGeneratedAt,
-        feedbackEntries: feedbackIntents.length,
-        skipped: true,
-        skipReason: "missing-style-card",
-        exemplars: samples,
-        feedbackIntents,
-      };
-    }
-
-    const styleCardYaml = (params.styleCardYaml ?? "").trim();
-    if (!styleCardYaml) {
-      throw new Error(
-        "voice-distil-profile: mode='write' requires styleCardYaml (the YAML you composed from the sample-mode response).",
-      );
-    }
-
-    // 7. Write the :VoiceProfile node — keyed on (accountId, profileUserId,
-    //    format) — anchored on :AdminUser (personal) or :LocalBusiness (org),
-    //    plus LEARNED_FROM edges to every sampled node. `scope` is SET after the
-    //    MERGE (never inside the pattern) so a legacy scope-less personal
-    //    profile is matched and backfilled rather than duplicated.
-    const anchorMatch =
-      scope === "org"
-        ? `MATCH (anchor:LocalBusiness {accountId: $accountId})`
-        : `MATCH (anchor:AdminUser {accountId: $accountId, userId: $profileUserId})`;
-    // Two-step MERGE: the profile node is MERGEd by its unique key alone, then
-    // the anchor edge is MERGEd separately. MERGEing the node through the anchor
-    // pattern would create a duplicate (constraint error) if the node existed
-    // but its anchor edge did not. Keying the node first mirrors the key-only
-    // reads and keeps the legacy scope-less backfill matching by key.
-    const writeResult = await session.run(
-      `${anchorMatch}
-       MERGE (p:VoiceProfile {accountId: $accountId, userId: $profileUserId, format: $format})
-         ON CREATE SET p.createdAt = $now
-       MERGE (anchor)-[:HAS_VOICE_PROFILE]->(p)
-       SET p.scope = $scope,
-           p.styleCard = $styleCard,
-           p.generatedAt = $now,
-           p.corpusSize = $corpusSize,
-           p.feedbackEntries = $feedbackEntries,
-           p.updatedAt = $now
-       WITH p
-       UNWIND $sampleIds AS sid
-       MATCH (s) WHERE elementId(s) = sid
-       MERGE (p)-[:LEARNED_FROM]->(s)
-       RETURN elementId(p) AS profileId`,
-      {
-        accountId,
-        profileUserId,
-        format,
-        scope,
-        styleCard: styleCardYaml,
-        now: nowIso,
-        corpusSize,
-        feedbackEntries: feedbackIntents.length,
-        sampleIds: samples.map((s) => s.id),
-      },
-    );
-    if (writeResult.records.length === 0) {
-      throw new Error(
-        scope === "org"
-          ? `voice-mirror: :LocalBusiness {accountId='${accountId}'} not found. The account org node must exist before an org distil (created at onboarding alongside :AdminUser).`
-          : `voice-mirror: :AdminUser {accountId='${accountId}', userId='${userId}'} not found. Onboarding must promote the operator to :AdminUser before distillation.`,
-      );
-    }
-    const profileId = writeResult.records[0].get("profileId") as string;
-
-    process.stderr.write(
-      `[voice-distil] scope=${scope} userId=${profileUserId} anchor=${anchorLabel} format=${format} corpusSize=${corpusSize} generatedAt=${nowIso} feedbackEntries=${feedbackIntents.length}${scope === "org" ? " sentinel=__org__" : ""}\n`,
-    );
-
-    return {
-      profileId,
-      corpusSize,
-      generatedAt: nowIso,
-      feedbackEntries: feedbackIntents.length,
-      skipped: false,
-    };
-  } finally {
-    await session.close();
-  }
-}
-
-/**
- * Single-document amend (Task 472).
- *
- * Operator-initiated incremental update: the operator names one or more
- * documents (`nodeIds`), the tool reads only those plus the existing
- * `:VoiceProfile.styleCard` for the format, and the calling agent decides
- * whether the documents move the profile or don't. Same body-resolution
- * and trashed/authorshipMode/label predicates as the full-corpus sample;
- * the corpus-wide format predicate is dropped (the operator picked the
- * docs); the cadence guard does not apply.
- */
-async function amendForFormat(params: {
-  accountId: string;
-  userId: string;
-  format: VoiceFormat;
-  nodeIds: string[];
-  scope?: VoiceScope;
-}): Promise<VoiceDistilProfileResult> {
-  const { accountId, userId, format, nodeIds } = params;
-  const scope: VoiceScope = params.scope ?? "personal";
-  const profileUserId = profileUserIdForScope(scope, userId);
-  const session = getSession();
-
-  try {
-    // 1. Existing scoped profile (may be absent — first-time amend, no prior
-    //    card). Key-only match on the unique (accountId, profileUserId, format).
-    const profileRow = await session.run(
-      `OPTIONAL MATCH (p:VoiceProfile {accountId: $accountId, userId: $profileUserId, format: $format})
-       RETURN elementId(p) AS profileId,
-              p.styleCard AS styleCard,
-              p.corpusSize AS corpusSize,
-              p.generatedAt AS generatedAt`,
-      { accountId, profileUserId, format },
-    );
-    const prow = profileRow.records[0];
-    const prevProfileId = (prow?.get("profileId") as string | null) ?? null;
-    const existingStyleCard = (prow?.get("styleCard") as string | null) ?? null;
-    const prevCorpusSize = toJsNumber(prow?.get("corpusSize")) ?? 0;
-    const prevGeneratedAt = (prow?.get("generatedAt") as string | null) ?? null;
-
-    // 2. Per-document eligibility classification. Each input id gets a
-    //    verdict; the first failing predicate wins. The predicate set mirrors
-    //    VOICE_CORPUS_WHERE except `format` is dropped (operator picked the
-    //    docs) and conversation-section sub-pattern is inlined for the
-    //    per-document case.
-    const eligibilityResult = await session.run(
-      `UNWIND $nodeIds AS nid
-       OPTIONAL MATCH (n) WHERE elementId(n) = nid
-       WITH nid, n,
-            CASE
-              WHEN n IS NULL THEN 'node-not-found'
-              WHEN n.accountId <> $accountId THEN 'wrong-account'
-              WHEN NOT coalesce(n.authorshipMode, '') IN ['human-only', 'human-led-agent-assisted']
-                THEN 'ineligible-authorship-mode'
-              WHEN n:Trashed OR n.deletedAt IS NOT NULL THEN 'trashed'
-              WHEN NOT (
-                any(lbl IN labels(n) WHERE lbl IN ['KnowledgeDocument', 'Message', 'SocialPost'])
-                OR ('Section' IN labels(n) AND EXISTS {
-                  MATCH (parent:KnowledgeDocument)-[:HAS_SECTION]->(n)
-                  WHERE parent.conversationIdentity IS NOT NULL
-                    AND ${notTrashed("parent")}
-                })
-              ) THEN 'ineligible-label'
-              ELSE 'ok'
-            END AS verdict
-       RETURN nid, verdict`,
-      { accountId, nodeIds },
-    );
-
-    const eligibleIds: string[] = [];
-    const ineligible: { nodeId: string; reason: string }[] = [];
-    for (const r of eligibilityResult.records) {
-      const nid = r.get("nid") as string;
-      const verdict = r.get("verdict") as string;
-      if (verdict === "ok") eligibleIds.push(nid);
-      else ineligible.push({ nodeId: nid, reason: verdict });
-    }
-
-    // 3. Feedback intents (same as sample) — agent benefits even on a no-op
-    //    amend ("you've already corrected this voice tic ten times"). Keyed by
-    //    profileUserId so org amends read org feedback.
-    const feedback = await session.run(
-      `MATCH (e:VoiceEdit {userId: $profileUserId, accountId: $accountId, format: $format})
-       RETURN e.intent AS intent ORDER BY e.occurredAt DESC LIMIT 50`,
-      { accountId, profileUserId, format },
-    );
-    const feedbackIntents = feedback.records
-      .map((r) => r.get("intent") as string | null)
-      .filter((x): x is string => typeof x === "string" && x.length > 0);
-
-    if (eligibleIds.length === 0) {
-      process.stderr.write(
-        `[voice-distil] scope=${scope} mode=amend userId=${profileUserId} format=${format} nodeIds=${nodeIds.length} ` +
-          `existingProfile=${prevProfileId ?? "none"} eligible=0 ineligible=${ineligible.length}\n`,
-      );
-      return {
-        profileId: prevProfileId,
-        corpusSize: prevCorpusSize,
-        generatedAt: prevGeneratedAt,
-        feedbackEntries: feedbackIntents.length,
-        skipped: true,
-        skipReason: "amend-no-eligible-documents",
-        existingStyleCard,
-        eligible: 0,
-        ineligible,
-        exemplars: [],
-        feedbackIntents,
-      };
-    }
-
-    // 4. Body walk for eligible ids — identical body resolution to the
-    //    full-corpus sample path: KD-with-Section-children concatenates child
-    //    bodies in `position` order (trashed sections filtered); other labels
-    //    fall through to the COALESCE chain.
-    const bodyResult = await session.run(
-      `UNWIND $eligibleIds AS nid
-       MATCH (n) WHERE elementId(n) = nid
-       OPTIONAL MATCH (parent:KnowledgeDocument)-[:HAS_SECTION]->(n)
-       WHERE 'Section' IN labels(n) AND parent.conversationIdentity IS NOT NULL
-         AND ${notTrashed("parent")}
-       WITH n, parent
-       OPTIONAL MATCH (n)-[:HAS_SECTION]->(s:Section)
-       WHERE ${notTrashed("s")}
-       WITH n, parent, s ORDER BY s.position
-       WITH n, parent, collect(s.body) AS sectionBodies
-       WITH n, parent,
-            'KnowledgeDocument' IN labels(n) AND size(sectionBodies) > 0 AS usedSectionWalk,
-            CASE
-              WHEN 'KnowledgeDocument' IN labels(n) AND size(sectionBodies) > 0
-                THEN reduce(acc = '', b IN sectionBodies | acc + b + '\n\n')
-              ELSE coalesce(n.body, n.abstract, n.subject, n.title, n.summary, '')
-            END AS body
-       RETURN elementId(n) AS id,
-              labels(n) AS labels,
-              body,
-              usedSectionWalk,
-              parent.conversationIdentity IS NOT NULL AS isConversationChunk`,
-      { eligibleIds },
-    );
-
-    const exemplars: VoiceCorpusExemplar[] = [];
-    let charBudget = SAMPLE_CHAR_CAP;
-    let sectionWalkCount = 0;
-    let nBodyCount = 0;
-    for (const r of bodyResult.records) {
-      const body = (r.get("body") as string | null) ?? "";
-      if (body.length === 0) continue;
-      const labels = (r.get("labels") as string[]) ?? [];
-      const isConversationChunk = Boolean(r.get("isConversationChunk"));
-      const usedSectionWalk = Boolean(r.get("usedSectionWalk"));
-      const label = isConversationChunk
-        ? "Conversation"
-        : (labels.find((l) =>
-            ["KnowledgeDocument", "Message", "SocialPost"].includes(l),
-          ) ?? labels[0] ?? "Unknown");
-      const trimmed = body.length > charBudget ? body.slice(0, charBudget) : body;
-      exemplars.push({ id: r.get("id") as string, label, body: trimmed });
-      if (usedSectionWalk) sectionWalkCount += 1;
-      else nBodyCount += 1;
-      charBudget -= trimmed.length;
-      if (charBudget <= 0) break;
-    }
-
-    process.stderr.write(
-      `[voice-distil] scope=${scope} mode=amend userId=${profileUserId} format=${format} nodeIds=${nodeIds.length} ` +
-        `existingProfile=${prevProfileId ?? "none"} eligible=${eligibleIds.length} ineligible=${ineligible.length} ` +
-        `exemplars=${exemplars.length} sample-body-source=section-walk:${sectionWalkCount} n.body:${nBodyCount}\n`,
-    );
-
-    // `skipped: false` because the function DID deliver value — exemplars
-    // + existingStyleCard for the agent to act on. The agent decides
-    // whether to compose new YAML (calls `mode='write'`) or replies "no
-    // material delta"; either is a valid amend outcome, neither is a
-    // "skip" in the cadence-guard sense.
-    return {
-      profileId: prevProfileId,
-      corpusSize: prevCorpusSize,
-      generatedAt: prevGeneratedAt,
-      feedbackEntries: feedbackIntents.length,
-      skipped: false,
-      existingStyleCard,
-      eligible: eligibleIds.length,
-      ineligible,
-      exemplars,
-      feedbackIntents,
-    };
-  } finally {
-    await session.close();
-  }
-}
-
-/**
- * Amend write (Task 472). Persists the agent-composed style card after an
- * `amend` sample. Bypasses the cadence guard and the full corpus walk; the
- * only `LEARNED_FROM` edges added are to `amendedFromNodeIds`. Pre-existing
- * `LEARNED_FROM` edges remain via `MERGE`. `corpusSize` on the profile is
- * untouched — the amend doesn't change the operator's qualifying corpus,
- * only the styleCard's interpretation of it.
- */
-async function amendWriteForFormat(params: {
-  accountId: string;
-  userId: string;
-  format: VoiceFormat;
-  styleCardYaml: string;
-  amendedFromNodeIds: string[];
-  scope?: VoiceScope;
-}): Promise<VoiceDistilProfileResult> {
-  const { accountId, userId, format, styleCardYaml, amendedFromNodeIds } = params;
-  const scope: VoiceScope = params.scope ?? "personal";
-  const profileUserId = profileUserIdForScope(scope, userId);
-  const anchorLabel = scope === "org" ? "LocalBusiness" : "AdminUser";
-  const session = getSession();
-  const nowIso = new Date().toISOString();
-  try {
-    // 1. Pre-resolve the amend ids and refuse if none survive. The write
-    //    Cypher SETs `p` before the UNWIND/MATCH on amend ids, so if every
-    //    id is stale the profile would be mutated then the function would
-    //    throw — leaving a silently advanced styleCard the operator never
-    //    confirmed. Resolving here means the SET never runs on an empty
-    //    target list, and stale ids surface as a structured error before
-    //    any write commits. Code-review pass-1 fix.
-    const resolve = await session.run(
-      `UNWIND $amendIds AS sid
-       MATCH (s) WHERE elementId(s) = sid
-       RETURN elementId(s) AS id`,
-      { amendIds: amendedFromNodeIds },
-    );
-    const resolvedAmendIds = resolve.records.map(
-      (r) => r.get("id") as string,
-    );
-    if (resolvedAmendIds.length === 0) {
-      throw new Error(
-        `voice-mirror: none of amendedFromNodeIds=${JSON.stringify(amendedFromNodeIds)} ` +
-          `resolved to live nodes. Confirm the named docs exist and are accessible.`,
-      );
-    }
-
-    const feedback = await session.run(
-      `MATCH (e:VoiceEdit {userId: $profileUserId, accountId: $accountId, format: $format})
-       RETURN count(e) AS c`,
-      { accountId, profileUserId, format },
-    );
-    const feedbackEntries = toJsNumber(feedback.records[0]?.get("c")) ?? 0;
-
-    const anchorMatch =
-      scope === "org"
-        ? `MATCH (anchor:LocalBusiness {accountId: $accountId})`
-        : `MATCH (anchor:AdminUser {accountId: $accountId, userId: $profileUserId})`;
-    // Two-step MERGE (see distilForFormat): node by unique key, then anchor edge.
-    const result = await session.run(
-      `${anchorMatch}
-       MERGE (p:VoiceProfile {accountId: $accountId, userId: $profileUserId, format: $format})
-         ON CREATE SET p.createdAt = $now, p.corpusSize = 0
-       MERGE (anchor)-[:HAS_VOICE_PROFILE]->(p)
-       SET p.scope = $scope,
-           p.styleCard = $styleCard,
-           p.generatedAt = $now,
-           p.feedbackEntries = $feedbackEntries,
-           p.updatedAt = $now
-       WITH p
-       UNWIND $amendIds AS sid
-       MATCH (s) WHERE elementId(s) = sid
-       MERGE (p)-[:LEARNED_FROM]->(s)
-       WITH p
-       RETURN elementId(p) AS profileId, p.corpusSize AS corpusSize`,
-      {
-        accountId,
-        profileUserId,
-        format,
-        scope,
-        styleCard: styleCardYaml,
-        now: nowIso,
-        feedbackEntries,
-        amendIds: resolvedAmendIds,
-      },
-    );
-    if (result.records.length === 0) {
-      throw new Error(
-        scope === "org"
-          ? `voice-mirror: :LocalBusiness {accountId='${accountId}'} not found. The account org node must exist before an org amend-write.`
-          : `voice-mirror: :AdminUser {accountId='${accountId}', userId='${userId}'} not found. ` +
-            `Onboarding must promote the operator to :AdminUser before distillation.`,
-      );
-    }
-    const profileId = result.records[0].get("profileId") as string;
-    const corpusSize = toJsNumber(result.records[0].get("corpusSize")) ?? 0;
-
-    process.stderr.write(
-      `[voice-distil] scope=${scope} mode=write userId=${profileUserId} anchor=${anchorLabel} format=${format} amended=true ` +
-        `amendedFromNodeIds=${amendedFromNodeIds.length} corpusSize=${corpusSize} ` +
-        `generatedAt=${nowIso} feedbackEntries=${feedbackEntries}\n`,
-    );
-
-    return {
-      profileId,
-      corpusSize,
-      generatedAt: nowIso,
-      feedbackEntries,
-      skipped: false,
-    };
-  } finally {
-    await session.close();
-  }
-}
-
-export async function voiceDistilProfile(
-  params: VoiceDistilProfileParams,
-): Promise<VoiceDistilProfileResult | VoiceDistilProfileResult[]> {
-  const { accountId, userId, force = false } = params;
-  const scope: VoiceScope = params.scope ?? "personal";
-  if (!accountId || !userId) {
-    throw new Error("voice-distil-profile: accountId and userId required");
-  }
-
-  // Amend sample (Task 472): operator-initiated single-document update.
-  if (params.mode === "amend") {
-    if (!params.format) {
-      throw new Error("voice-distil-profile: mode='amend' requires format");
-    }
-    const nodeIds = params.nodeIds ?? [];
-    if (nodeIds.length === 0) {
-      throw new Error(
-        "voice-distil-profile: mode='amend' requires nodeIds (at least one)",
-      );
-    }
-    return amendForFormat({
-      accountId,
-      userId,
-      format: params.format,
-      nodeIds,
-      scope,
-    });
-  }
-
-  // Amend write (Task 472): persist after the agent composed from an amend
-  // sample. Triggered by `mode='write'` + non-empty `amendedFromNodeIds`.
-  // Distinct from the full-corpus write — bypasses cadence + corpus walk.
-  if (
-    params.mode === "write" &&
-    params.amendedFromNodeIds &&
-    params.amendedFromNodeIds.length > 0
-  ) {
-    if (!params.format) {
-      throw new Error(
-        "voice-distil-profile: mode='write' with amendedFromNodeIds requires format",
-      );
-    }
-    const styleCardYaml = (params.styleCardYaml ?? "").trim();
-    if (!styleCardYaml) {
-      throw new Error(
-        "voice-distil-profile: mode='write' requires styleCardYaml (the YAML you composed from the amend-sample response).",
-      );
-    }
-    return amendWriteForFormat({
-      accountId,
-      userId,
-      format: params.format,
-      styleCardYaml,
-      amendedFromNodeIds: params.amendedFromNodeIds,
-      scope,
-    });
-  }
-
-  // Single-format path.
-  if (params.format !== undefined) {
-    return distilForFormat({ ...params, format: params.format, force });
-  }
-
-  // Multi-format path: enumerate distinct format values present in the corpus.
-  // Scope-aware: personal enumerates only the operator's authored content, org
-  // enumerates the whole account.
-  const session = getSession();
-  let formats: VoiceFormat[] = [];
-  try {
-    const enumResult = await session.run(
-      `MATCH (n)
-       WHERE ${VOICE_CORPUS_WHERE} AND n.format IS NOT NULL${scope === "personal" ? " AND n.voiceAuthor = $voiceAuthor" : ""}
-       RETURN DISTINCT n.format AS fmt`,
-      scope === "personal" ? { accountId, voiceAuthor: userId } : { accountId },
-    );
-    formats = enumResult.records
-      .map((r) => r.get("fmt") as string)
-      .filter((f): f is VoiceFormat =>
-        (FORMAT_VALUES as readonly string[]).includes(f),
-      );
-  } finally {
-    await session.close();
-  }
-
-  if (formats.length === 0) {
-    process.stderr.write(
-      `[voice-distil] scope=${scope} userId=${profileUserIdForScope(scope, userId)} skip reason=no-format-tagged-content\n`,
-    );
-    return {
-      profileId: null,
-      corpusSize: 0,
-      generatedAt: null,
-      feedbackEntries: 0,
-      skipped: true,
-      skipReason: "no-format-tagged-content",
-    };
-  }
-
-  // Distil each discovered format sequentially.
-  const results: VoiceDistilProfileResult[] = [];
-  for (const format of formats) {
-    const result = await distilForFormat({ ...params, format, force });
-    results.push({ ...result, format });
-  }
-  return results;
-}