pi-fluency 0.1.3 → 0.2.1

package/extensions/pi-fluency/practice-settings.ts

@@ -0,0 +1,201 @@
+import { createHash } from "node:crypto";
+import {
+  DEFAULT_PRACTICE_SETTINGS,
+  PRACTICE_SCHEMA_VERSION,
+  type PracticeSettings,
+  type PracticeTarget,
+} from "./types.js";
+
+export const MAX_PRACTICE_TARGETS = 50;
+export const MAX_PRACTICE_FIELD_LENGTH = 500;
+export const MAX_PRACTICE_MEMBER_KEYS = 500;
+export const FIVE_HOURS_MS = 5 * 60 * 60 * 1_000;
+export const PRACTICE_SESSION_ENTRY_TYPE = "pi-fluency-practice-snooze";
+export const PRACTICE_SESSION_RESUME_ENTRY_TYPE = "pi-fluency-practice-resume";
+
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f-\u009f]/;
+const PRACTICE_KEYS = new Set([
+  "schemaVersion",
+  "revision",
+  "epoch",
+  "enabled",
+  "consentedAt",
+  "targets",
+  "snoozedUntil",
+]);
+const TARGET_KEYS = new Set(["explanation", "memberPatternKeys"]);
+const SESSION_SNOOZE_KEYS = new Set(["schemaVersion", "epoch", "sessionHash"]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasOnlyKeys(value: Record<string, unknown>, allowed: ReadonlySet<string>): boolean {
+  return Object.keys(value).every((key) => allowed.has(key));
+}
+
+function isCounter(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+function isTimestamp(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function isPracticeField(value: unknown): value is string {
+  return typeof value === "string"
+    && value.length > 0
+    && value.length <= MAX_PRACTICE_FIELD_LENGTH
+    && !CONTROL_CHARACTER.test(value);
+}
+
+export function canonicalizePracticeTargets(value: unknown): PracticeTarget[] {
+  if (!Array.isArray(value) || value.length > MAX_PRACTICE_TARGETS) {
+    throw new Error("Invalid practice settings");
+  }
+
+  const membersByExplanation = new Map<string, Set<string>>();
+  for (const candidate of value) {
+    if (!isRecord(candidate) || !hasOnlyKeys(candidate, TARGET_KEYS)
+      || !isPracticeField(candidate.explanation)
+      || !Array.isArray(candidate.memberPatternKeys)
+      || candidate.memberPatternKeys.length === 0
+      || candidate.memberPatternKeys.length > MAX_PRACTICE_MEMBER_KEYS
+      || candidate.memberPatternKeys.some((key) => !isPracticeField(key))) {
+      throw new Error("Invalid practice settings");
+    }
+    const members = membersByExplanation.get(candidate.explanation) ?? new Set<string>();
+    for (const key of candidate.memberPatternKeys as string[]) members.add(key);
+    if (members.size > MAX_PRACTICE_MEMBER_KEYS) throw new Error("Invalid practice settings");
+    membersByExplanation.set(candidate.explanation, members);
+  }
+
+  return [...membersByExplanation]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([explanation, memberPatternKeys]) => ({
+      explanation,
+      memberPatternKeys: [...memberPatternKeys].sort((left, right) => left.localeCompare(right)),
+    }));
+}
+
+export function copyPracticeSettings(settings: PracticeSettings): PracticeSettings {
+  return {
+    ...settings,
+    targets: settings.targets.map((target) => ({
+      explanation: target.explanation,
+      memberPatternKeys: [...target.memberPatternKeys],
+    })),
+  };
+}
+
+export function defaultPracticeSettings(): PracticeSettings {
+  return copyPracticeSettings(DEFAULT_PRACTICE_SETTINGS);
+}
+
+export function decodePracticeSettings(value: unknown): PracticeSettings {
+  if (!isRecord(value) || !hasOnlyKeys(value, PRACTICE_KEYS)
+    || value.schemaVersion !== PRACTICE_SCHEMA_VERSION
+    || !isCounter(value.revision)
+    || !isCounter(value.epoch)
+    || typeof value.enabled !== "boolean"
+    || (value.consentedAt !== undefined && !isTimestamp(value.consentedAt))
+    || (value.snoozedUntil !== undefined && !isTimestamp(value.snoozedUntil))) {
+    throw new Error("Invalid practice settings");
+  }
+
+  const targets = canonicalizePracticeTargets(value.targets);
+  return {
+    schemaVersion: PRACTICE_SCHEMA_VERSION,
+    revision: value.revision,
+    epoch: value.epoch,
+    enabled: value.enabled,
+    targets,
+    ...(value.consentedAt === undefined ? {} : { consentedAt: value.consentedAt }),
+    ...(value.snoozedUntil === undefined ? {} : { snoozedUntil: value.snoozedUntil }),
+  };
+}
+
+export function isGloballySnoozed(settings: PracticeSettings, now = Date.now()): boolean {
+  return settings.snoozedUntil !== undefined && settings.snoozedUntil > now;
+}
+
+export interface PracticeSessionSnoozeEntry {
+  schemaVersion: typeof PRACTICE_SCHEMA_VERSION;
+  epoch: number;
+  sessionHash: string;
+}
+
+export interface CustomSessionEntryLike {
+  type: string;
+  customType?: string;
+  data?: unknown;
+}
+
+export function hashPracticeSessionFile(sessionFile: string): string {
+  return createHash("sha256").update(sessionFile).digest("hex");
+}
+
+function decodeSessionSnooze(value: unknown): PracticeSessionSnoozeEntry | undefined {
+  if (!isRecord(value) || !hasOnlyKeys(value, SESSION_SNOOZE_KEYS)
+    || value.schemaVersion !== PRACTICE_SCHEMA_VERSION
+    || !isCounter(value.epoch)
+    || typeof value.sessionHash !== "string"
+    || !/^[a-f0-9]{64}$/.test(value.sessionHash)) return undefined;
+  return {
+    schemaVersion: PRACTICE_SCHEMA_VERSION,
+    epoch: value.epoch,
+    sessionHash: value.sessionHash,
+  };
+}
+
+/** Runtime owner for durable session-file snooze and ephemeral-session fallback. */
+export class PracticeSessionSnooze {
+  private ephemeralEpoch: number | undefined;
+
+  restore(entries: readonly CustomSessionEntryLike[], sessionFile: string | undefined, epoch: number): boolean {
+    if (sessionFile === undefined) return this.ephemeralEpoch === epoch;
+    const expectedHash = hashPracticeSessionFile(sessionFile);
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+      const entry = entries[index]!;
+      if (entry.type !== "custom"
+        || (entry.customType !== PRACTICE_SESSION_ENTRY_TYPE
+          && entry.customType !== PRACTICE_SESSION_RESUME_ENTRY_TYPE)) continue;
+      const data = decodeSessionSnooze(entry.data);
+      if (data?.epoch !== epoch || data.sessionHash !== expectedHash) continue;
+      return entry.customType === PRACTICE_SESSION_ENTRY_TYPE;
+    }
+    return false;
+  }
+
+  snooze(
+    sessionFile: string | undefined,
+    epoch: number,
+    appendEntry: (customType: string, data: PracticeSessionSnoozeEntry) => void,
+  ): void {
+    if (sessionFile === undefined) {
+      this.ephemeralEpoch = epoch;
+      return;
+    }
+    appendEntry(PRACTICE_SESSION_ENTRY_TYPE, {
+      schemaVersion: PRACTICE_SCHEMA_VERSION,
+      epoch,
+      sessionHash: hashPracticeSessionFile(sessionFile),
+    });
+  }
+
+  resume(
+    sessionFile: string | undefined,
+    epoch: number,
+    appendEntry: (customType: string, data: PracticeSessionSnoozeEntry) => void,
+  ): void {
+    if (sessionFile === undefined) {
+      this.ephemeralEpoch = undefined;
+      return;
+    }
+    appendEntry(PRACTICE_SESSION_RESUME_ENTRY_TYPE, {
+      schemaVersion: PRACTICE_SCHEMA_VERSION,
+      epoch,
+      sessionHash: hashPracticeSessionFile(sessionFile),
+    });
+  }
+}

package/extensions/pi-fluency/setup.ts

@@ -16,7 +16,7 @@ export async function runSetup(
   if (!model) return false;
   const approved = await ctx.ui.confirm(
     "Enable Pi Fluency?",
-    `User-authored prose will be sent to ${sanitizeTerminalLabel(model.provider, 100) || "unknown-provider"}/${sanitizeTerminalLabel(model.id, 100) || "unknown-model"}. Code, commands, assistant text, and tool output are excluded. Raw prompt bodies are not stored; bounded sanitized excerpts may equal a short prompt.`,
+    `User-authored prose will be sent to ${sanitizeTerminalLabel(model.provider, 100) || "unknown-provider"}/${sanitizeTerminalLabel(model.id, 100) || "unknown-model"} for background analytics after Pi Fluency allows a prompt. Code, commands, assistant text, and tool output are excluded. Raw prompt bodies are not stored; bounded sanitized excerpts may equal a short prompt. Optional preflight practice is off and requires a separate disclosure before first activation.`,
   );
   if (!approved) return false;
   await store.updateSettings({

package/extensions/pi-fluency/status.ts

@@ -9,6 +9,7 @@ export type StatusState =
     ratePerThousand: number | undefined;
   }
   | { kind: "initial-loading" }
+  | { kind: "practice-check" }
   | { kind: "error"; reason: StatusErrorReason }
   | { kind: "hidden" };
 
@@ -31,6 +32,8 @@ export function formatStatus(state: StatusState): string | undefined {
     }
     case "initial-loading":
       return `󰇰 …  󰌵 …  ${EMPTY_SPARKLINE} —/k`;
+    case "practice-check":
+      return "󰌵 CHECK";
     case "error":
       return `󰅙 ERR ${state.reason}`;
     case "hidden":

package/extensions/pi-fluency/store.ts

@@ -1,10 +1,12 @@
 import { randomUUID } from "node:crypto";
-import { appendFile, chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { mkdir as mkdirCallback, realpath, rmdir, rmdirSync, stat, utimes } from "node:fs";
+import { appendFile, chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { lock, type LockOptions } from "proper-lockfile";
 import {
   DEFAULT_SETTINGS,
   HISTORY_SCHEMA_VERSION,
+  PRACTICE_SCHEMA_VERSION,
   SCHEMA_VERSION,
   type AnalysisResult,
   type CollectedPrompt,
@@ -13,6 +15,9 @@ import {
   type FluencySettings,
   type FluencyState,
   type MistakePattern,
+  type PracticePolicySnapshot,
+  type PracticeSettings,
+  type PracticeTarget,
   type ReviewPattern,
 } from "./types.js";
 import {
@@ -40,7 +45,15 @@ import {
   decodeHistoryGenerationMarker,
   encodeHistoryGenerationMarker,
 } from "./generation-marker.js";
-
+import {
+  FIVE_HOURS_MS,
+  canonicalizePracticeTargets,
+  copyPracticeSettings,
+  decodePracticeSettings,
+  defaultPracticeSettings,
+} from "./practice-settings.js";
+
+const lockFs = { mkdir: mkdirCallback, realpath, rmdir, rmdirSync, stat, utimes };
 const HISTORY_SCHEMA_WARNING = "History migration required; run /fluency clear";
 const HISTORY_GENERATION_FILE = "history-generation";
 const PRIVATE_DIRECTORY_MODE = 0o700;
@@ -57,6 +70,18 @@ const LOCK_RETRIES = {
 
 type LockProvider = (file: string, options: LockOptions) => Promise<() => Promise<void>>;
 type FileReplacer = (temporary: string, destination: string) => Promise<void>;
+type PolicyFileReader = (path: string) => Promise<string>;
+
+export interface AnalysisCommitFence {
+  historyGeneration: string;
+  enabled: boolean;
+  consentedAt?: number;
+  provider?: string;
+  modelId?: string;
+  minimumConfidence: number;
+}
+
+export type ConditionalAppendResult = "committed" | "generation-stale" | "authorization-stale" | "analyzer-stale";
 
 const errantCategorySet = new Set<string>(ERRANT_CATEGORIES);
 
@@ -116,9 +141,12 @@ function decodeSettings(value: unknown): FluencySettings {
 }
 
 export class FluencyStore {
-  private static lockProvider: LockProvider = lock;
+  private static lockProvider: LockProvider = (file, options) =>
+    lock(file, { ...options, fs: lockFs });
   private static settingsFileReplacer: FileReplacer = rename;
+  private static practiceFileReplacer: FileReplacer = rename;
   private static historyFileReplacer: FileReplacer = rename;
+  private static policyFileReader: PolicyFileReader = (path) => readFile(path, "utf8");
 
   private readonly state = createFluencyState();
   private readonly warnings: string[] = [];
@@ -127,12 +155,14 @@ export class FluencyStore {
   private eventsSinceCompact = 0;
   private historyResetRequired = false;
   private settings: FluencySettings = copySettings(DEFAULT_SETTINGS);
+  private practice: PracticeSettings = defaultPracticeSettings();
   private mutationQueue: Promise<void> = Promise.resolve();
 
   private constructor(
     private readonly rootDir: string,
     private readonly historyPath: string,
     private readonly settingsPath: string,
+    private readonly practicePath: string,
     private readonly historyGenerationPath: string,
   ) {}
 
@@ -143,6 +173,7 @@ export class FluencyStore {
       rootDir,
       join(rootDir, "history.jsonl"),
       join(rootDir, "settings.json"),
+      join(rootDir, "practice.json"),
       join(rootDir, HISTORY_GENERATION_FILE),
     );
     await store.withGlobalLock(async (signal) => {
@@ -169,10 +200,22 @@ export class FluencyStore {
 
   requiresHistoryReset(): boolean { return this.historyResetRequired; }
   getSettings(): FluencySettings { return copySettings(this.settings); }
+  getPracticeSettings(): PracticeSettings { return copyPracticeSettings(this.practice); }
   getWarnings(): string[] { return [...this.warnings]; }
 
+  captureAnalysisCommitFence(settings: FluencySettings = this.settings): AnalysisCommitFence {
+    return {
+      historyGeneration: this.historyGeneration,
+      enabled: settings.enabled,
+      minimumConfidence: settings.minimumConfidence,
+      ...(settings.consentedAt === undefined ? {} : { consentedAt: settings.consentedAt }),
+      ...(settings.provider === undefined ? {} : { provider: settings.provider }),
+      ...(settings.modelId === undefined ? {} : { modelId: settings.modelId }),
+    };
+  }
+
   private async hardenExistingFiles(): Promise<void> {
-    for (const path of [this.historyPath, this.settingsPath, this.historyGenerationPath]) {
+    for (const path of [this.historyPath, this.settingsPath, this.practicePath, this.historyGenerationPath]) {
       try {
         await chmod(path, PRIVATE_FILE_MODE);
       } catch (error) {
@@ -294,6 +337,18 @@ export class FluencyStore {
       }
     }
 
+    try {
+      const parsed = JSON.parse(await readFile(this.practicePath, { encoding: "utf8", signal })) as unknown;
+      signal.throwIfAborted();
+      this.practice = decodePracticeSettings(parsed);
+    } catch (error) {
+      signal.throwIfAborted();
+      this.practice = defaultPracticeSettings();
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT" && recordWarnings) {
+        this.warnings.push("Could not read practice settings; defaults loaded");
+      }
+    }
+
     let history: string;
     try {
       history = await readFile(this.historyPath, { encoding: "utf8", signal });
@@ -423,6 +478,204 @@ export class FluencyStore {
     }));
   }
 
+  /** Read one stable authorization/configuration/generation snapshot without taking mutation lock. */
+  async getFreshPolicySnapshot(deadline: number, signal?: AbortSignal): Promise<PracticePolicySnapshot> {
+    if (!Number.isFinite(deadline)) throw new Error("Invalid practice policy deadline");
+    const deadlineError = (): Error => new Error("Practice policy read deadline exceeded");
+    const abortError = (): unknown => signal?.reason ?? new DOMException("Aborted", "AbortError");
+    const readOptional = async (path: string): Promise<string | undefined> => {
+      signal?.throwIfAborted();
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) throw deadlineError();
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      let onAbort: (() => void) | undefined;
+      try {
+        const cancelled = signal === undefined
+          ? new Promise<never>(() => undefined)
+          : new Promise<never>((_resolve, reject) => {
+            onAbort = () => reject(abortError());
+            signal.addEventListener("abort", onAbort, { once: true });
+            if (signal.aborted) onAbort();
+          });
+        const value = await Promise.race([
+          FluencyStore.policyFileReader(path),
+          new Promise<never>((_resolve, reject) => { timer = setTimeout(() => reject(deadlineError()), remaining); }),
+          cancelled,
+        ]);
+        signal?.throwIfAborted();
+        if (Date.now() >= deadline) throw deadlineError();
+        return value;
+      } catch (error) {
+        if (signal?.aborted) throw abortError();
+        if (Date.now() >= deadline || (error instanceof Error && error.message === deadlineError().message)) {
+          throw deadlineError();
+        }
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+        throw error;
+      } finally {
+        if (timer !== undefined) clearTimeout(timer);
+        if (onAbort !== undefined) signal?.removeEventListener("abort", onAbort);
+      }
+    };
+
+    while (Date.now() < deadline) {
+      signal?.throwIfAborted();
+      const settingsFirst = await readOptional(this.settingsPath);
+      const practiceFirst = await readOptional(this.practicePath);
+      const generationFirst = await readOptional(this.historyGenerationPath);
+      const settingsSecond = await readOptional(this.settingsPath);
+      const practiceSecond = await readOptional(this.practicePath);
+      const generationSecond = await readOptional(this.historyGenerationPath);
+      if (settingsFirst !== settingsSecond || practiceFirst !== practiceSecond || generationFirst !== generationSecond) continue;
+
+      let settings = copySettings(DEFAULT_SETTINGS);
+      let practice = defaultPracticeSettings();
+      try {
+        if (settingsSecond !== undefined) settings = decodeSettings(JSON.parse(settingsSecond) as unknown);
+      } catch { /* Corrupt complete file has safe effective defaults. */ }
+      try {
+        if (practiceSecond !== undefined) practice = decodePracticeSettings(JSON.parse(practiceSecond) as unknown);
+      } catch { /* Corrupt complete file has safe effective defaults. */ }
+      if (generationSecond === undefined) throw new Error("History generation unavailable");
+      const marker = decodeHistoryGenerationMarker(generationSecond);
+      if (marker.resetPending) throw new Error("History clear in progress");
+      return {
+        settings: copySettings(settings),
+        practice: copyPracticeSettings(practice),
+        historyGeneration: marker.generation,
+      };
+    }
+    throw deadlineError();
+  }
+
+  private updatePractice(
+    mutator: (practice: PracticeSettings) => PracticeSettings,
+  ): Promise<void> {
+    return this.enqueueMutation(async (signal) => {
+      await this.savePracticeUnsafe(mutator(copyPracticeSettings(this.practice)), signal);
+    });
+  }
+
+  recordPracticeConsent(consentedAt: number): Promise<void> {
+    return this.updatePractice((practice) => ({
+      ...practice,
+      revision: practice.revision + 1,
+      consentedAt,
+    }));
+  }
+
+  /** Atomically records first-use consent, optional first target, and enabled state. */
+  activatePractice(consentedAt: number, firstTarget?: PracticeTarget): Promise<void> {
+    if (!Number.isFinite(consentedAt) || consentedAt < 0) {
+      return Promise.reject(new Error("Invalid practice consent"));
+    }
+    let canonicalTarget: PracticeTarget | undefined;
+    try {
+      canonicalTarget = firstTarget === undefined
+        ? undefined
+        : canonicalizePracticeTargets([firstTarget])[0]!;
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    return this.updatePractice((practice) => {
+      const remaining = canonicalTarget === undefined
+        ? practice.targets
+        : practice.targets.filter((item) => item.explanation !== canonicalTarget.explanation);
+      const targets = canonicalTarget === undefined
+        ? remaining
+        : canonicalizePracticeTargets([...remaining, canonicalTarget]);
+      return {
+        ...practice,
+        revision: practice.revision + 1,
+        consentedAt,
+        enabled: true,
+        targets,
+      };
+    });
+  }
+
+  setPracticeEnabled(enabled: boolean): Promise<void> {
+    return this.updatePractice((practice) => ({
+      ...practice,
+      revision: practice.revision + 1,
+      enabled,
+    }));
+  }
+
+  setPracticeTarget(target: PracticeTarget, selected: boolean): Promise<void> {
+    let canonicalTarget: PracticeTarget;
+    try {
+      canonicalTarget = canonicalizePracticeTargets([target])[0]!;
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    return this.updatePractice((practice) => {
+      const remaining = practice.targets.filter((item) => item.explanation !== canonicalTarget.explanation);
+      const targets = canonicalizePracticeTargets(selected ? [...remaining, canonicalTarget] : remaining);
+      return { ...practice, revision: practice.revision + 1, targets };
+    });
+  }
+
+  /** Revision/deadline-fenced modal action. False means no sidecar replacement occurred. */
+  snoozePracticeForFiveHours(
+    expectedRevision: number,
+    operationDeadline: number,
+    now = Date.now(),
+  ): Promise<boolean> {
+    if (!Number.isFinite(operationDeadline) || !Number.isFinite(now) || now < 0) {
+      return Promise.reject(new Error("Invalid practice snooze"));
+    }
+    return this.enqueueMutation(async (signal) => {
+      if (Date.now() >= operationDeadline || this.practice.revision !== expectedRevision) return false;
+      return this.savePracticeUnsafe({
+        ...this.practice,
+        revision: this.practice.revision + 1,
+        snoozedUntil: now + FIVE_HOURS_MS,
+      }, signal, operationDeadline);
+    });
+  }
+
+  resumePractice(): Promise<void> {
+    return this.updatePractice((practice) => {
+      const { snoozedUntil: _snoozedUntil, ...rest } = practice;
+      return { ...rest, revision: practice.revision + 1 };
+    });
+  }
+
+  resetPractice(): Promise<void> {
+    return this.updatePractice((practice) => ({
+      schemaVersion: PRACTICE_SCHEMA_VERSION,
+      revision: practice.revision + 1,
+      epoch: practice.epoch + 1,
+      enabled: false,
+      targets: [],
+    }));
+  }
+
+  private async savePracticeUnsafe(
+    practice: PracticeSettings,
+    signal: AbortSignal,
+    operationDeadline?: number,
+  ): Promise<boolean> {
+    const copied = decodePracticeSettings(practice);
+    const temporary = `${this.practicePath}.${process.pid}.${randomUUID()}.tmp`;
+    signal.throwIfAborted();
+    await writeFile(temporary, `${JSON.stringify(copied, null, 2)}\n`, {
+      encoding: "utf8",
+      mode: PRIVATE_FILE_MODE,
+      signal,
+    });
+    signal.throwIfAborted();
+    if (operationDeadline !== undefined && Date.now() >= operationDeadline) {
+      await rm(temporary, { force: true });
+      return false;
+    }
+    await FluencyStore.practiceFileReplacer(temporary, this.practicePath);
+    signal.throwIfAborted();
+    this.practice = copied;
+    return true;
+  }
+
   updateSettings(
     patchOrMutator: Partial<FluencySettings> | ((settings: FluencySettings) => Partial<FluencySettings>),
   ): Promise<void> {
@@ -455,24 +708,27 @@ export class FluencyStore {
     this.settings = copied;
   }
 
-  appendAnalysis(prompt: CollectedPrompt, result: AnalysisResult): Promise<void> {
+  private analysisEvent(prompt: CollectedPrompt, result: AnalysisResult): FluencyEvent {
     const copiedPrompt: CollectedPrompt = {
       promptHash: prompt.promptHash,
       prose: prompt.prose,
       observedAt: prompt.observedAt,
     };
+    if (result.schemaVersion !== 3) throw new Error("Invalid schema-v4 history event");
+    return decodeHistoryLine({
+      schemaVersion: HISTORY_SCHEMA_VERSION,
+      type: "analysis",
+      at: copiedPrompt.observedAt,
+      prompt: copiedPrompt,
+      wordCount: countEnglishWords(copiedPrompt.prose),
+      result: copyAnalysisResult(result),
+    });
+  }
+
+  appendAnalysis(prompt: CollectedPrompt, result: AnalysisResult): Promise<void> {
     let event: FluencyEvent;
     try {
-      if (result.schemaVersion !== 3) throw new Error("Invalid schema-v4 history event");
-      const sanitizedResult = copyAnalysisResult(result);
-      event = decodeHistoryLine({
-        schemaVersion: HISTORY_SCHEMA_VERSION,
-        type: "analysis",
-        at: copiedPrompt.observedAt,
-        prompt: copiedPrompt,
-        wordCount: countEnglishWords(copiedPrompt.prose),
-        result: sanitizedResult,
-      });
+      event = this.analysisEvent(prompt, result);
     } catch (error) {
       return Promise.reject(error);
     }
@@ -482,6 +738,34 @@ export class FluencyStore {
     });
   }
 
+  /** Append precomputed result only while clear generation and analyzer authorization remain exact. */
+  conditionalAppendAnalysis(
+    fence: AnalysisCommitFence,
+    prompt: CollectedPrompt,
+    result: AnalysisResult,
+  ): Promise<ConditionalAppendResult> {
+    let event: FluencyEvent;
+    try {
+      event = this.analysisEvent(prompt, result);
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    return this.enqueueMutation(async (signal) => {
+      if (this.historyGeneration !== fence.historyGeneration) return "generation-stale";
+      const current = this.settings;
+      if (!current.enabled
+        || current.consentedAt === undefined
+        || current.enabled !== fence.enabled
+        || current.consentedAt !== fence.consentedAt) return "authorization-stale";
+      if (current.provider !== fence.provider
+        || current.modelId !== fence.modelId
+        || current.minimumConfidence !== fence.minimumConfidence) return "analyzer-stale";
+      this.assertHistoryReady();
+      await this.appendUnsafe(event, signal);
+      return "committed";
+    });
+  }
+
   private reviewPatternBatch(
     patternId: string,
     decision: "accepted" | "dismissed",