create-principles-disciple 1.144.11 → 1.144.12

package/_release/product-identity.json

@@ -1,5 +1,5 @@
 {
   "schemaVersion": 1,
   "productVersion": "2.2.0",
-  "sourceCommit": "9b993151f65b075845e56a4f19dd523eac9810da"
+  "sourceCommit": "332de78574839e4970145fc34617ed4b8abf743a"
 }

package/console/dist/server/models/ApprovalsConsoleModel.d.ts

@@ -66,7 +66,7 @@ export declare class ApprovalsConsoleModel {
      * principles. A projection error is also surfaced (never silent) but must
      * not fail the approve.
      *
-     * PRI-935 — the console holds no session, so it cannot supply the production
+     * PR-1894 — the console holds no session, so it cannot supply the production
      * round key and the projection runs `legacy_fifo_prefix_v1`. That is NOT a
      * conservative forecast: FIFO structurally drops the newest activation from
      * every truncated selection, while the live plugin route rotates and injects

package/console/dist/server/models/ApprovalsConsoleModel.js

@@ -156,7 +156,7 @@ export class ApprovalsConsoleModel {
         // The prompt surface renders active activations under a hard char cap;
         // when the budget is saturated the newest Owner approval may not reach
         // agent behavior on THIS turn. Surface it as a non-fatal warning (rc-9)
-        // instead — the activation stays committed. PRI-935: whether "not on this
+        // instead — the activation stays committed. PR-1894: whether "not on this
         // turn" means "queued behind rotation" or genuinely starved depends on the
         // selection policy, which checkPromptInjectionBudget now reports honestly.
         let injectionWarning;
@@ -182,7 +182,7 @@ export class ApprovalsConsoleModel {
      * principles. A projection error is also surfaced (never silent) but must
      * not fail the approve.
      *
-     * PRI-935 — the console holds no session, so it cannot supply the production
+     * PR-1894 — the console holds no session, so it cannot supply the production
      * round key and the projection runs `legacy_fifo_prefix_v1`. That is NOT a
      * conservative forecast: FIFO structurally drops the newest activation from
      * every truncated selection, while the live plugin route rotates and injects
@@ -211,7 +211,7 @@ export class ApprovalsConsoleModel {
             // that instead of blaming the budget.
             return `injection_excluded_non_budget: the activation is committed but excluded from the prompt injection projection for a non-budget reason.${projectionDetail} nextAction=inspect the artifact/activation pair via pd runtime activation list`;
         }
-        // PRI-935: fair rotation is the live plugin-local policy (PRI-904). An
+        // PR-1894: fair rotation is the live plugin-local policy (PRI-904). An
         // activation that SOME round does inject is rotated out of the current
         // window, not starved — report that bounded fact instead of the old FIFO
         // starvation claim. The shared route genuinely does not rotate, so its
@@ -220,7 +220,7 @@ export class ApprovalsConsoleModel {
             const window = projection.eligibleCount;
             return `injection_budget_queued: the activation is committed but sits outside the CURRENT prompt injection window (${projection.budget}c; ${projection.injectedActivationIds.length} of ${window} eligible activations injected this round; production selection policy fair_rotation_v1). Fair rotation advances the window by one position per recorded user turn, so this principle WILL enter agent behavior within at most ${window} consecutive user turns of a continuously advancing session — deactivating older principles is NOT required. nextAction=none; verify presence via the activations page or the prompt injection telemetry`;
         }
-        // PRI-935: report the PRODUCTION policy, not the policy this forecast
+        // PR-1894: report the PRODUCTION policy, not the policy this forecast
         // happened to run. The console holds no session round key, so its own
         // projection is always `legacy_fifo_prefix_v1` even on a route where
         // production rotates — labelling that value "the current production

package/console/dist/server/models/ApprovalsGroupedConsoleModel.d.ts

@@ -8,9 +8,9 @@ export interface ApprovalGroup {
     candidateDescription?: string;
     status: 'pending' | 'approved' | 'rejected';
     /**
-     * PRI-935: whether this candidate's own serialized prompt entry fits the
+     * PR-1894: whether this candidate's own serialized prompt entry fits the
      * injection budget on its own. `false` means the entry is oversized, so fair
-     * rotation can NEVER inject it �?the pre-approval badge must not promise it
+     * rotation can NEVER inject it �?the pre-approval badge must not promise it
      * will come around. Computed server-side with the production serializer
      * (the client has no access to the escaped, serialized size).
      */
@@ -36,11 +36,11 @@ export declare class ApprovalsGroupedConsoleModel {
     getApprovalsGrouped(): Promise<ApprovalsGroupedResponse>;
     /**
      * PRI-908: recompute the production prompt injection projection so the
-     * focus page can forecast "approved �?effective" BEFORE the Owner decides.
+     * focus page can forecast "approved �?effective" BEFORE the Owner decides.
      * PR #1844 follow-up: the forecast follows the workspace's REAL injection
-     * route (`buildLivePromptInjectionProjection` �?legacy trimToBudget vs
+     * route (`buildLivePromptInjectionProjection` �?legacy trimToBudget vs
      * shared render via abstraction_layer_v1), matching the PRI-890 approve-time
-     * check. Advisory only: a projection failure omits the field �?the
+     * check. Advisory only: a projection failure omits the field �?the
      * approve-time warning remains the fail-loud exclusion report (rc-9), so
      * this must never fail the grouped read.
      */

package/console/dist/server/models/ApprovalsGroupedConsoleModel.js

@@ -17,7 +17,7 @@ function isMissingTableError(err) {
 /**
  * Wave 7: Extract a human-readable description from a PIArtifact's contentJson.
  *
- * The artifact kinds have different contentJson shapes �?this function unifies
+ * The artifact kinds have different contentJson shapes �?this function unifies
  * them into a single description string the Owner can actually read to make a
  * review decision, instead of staring at a fabricated principleId.
  *
@@ -50,7 +50,7 @@ function extractCandidateDescription(contentJson) {
         const principleText = principleRaw ? principleRaw.trim() : null;
         const ruleText = ruleRaw ? ruleRaw.trim() : null;
         if (principleText && ruleText)
-            return `${principleText} �?${ruleText}`;
+            return `${principleText} �?${ruleText}`;
         if (ruleText)
             return ruleText;
         if (principleText)
@@ -65,7 +65,7 @@ function extractCandidateDescription(contentJson) {
         const title = typeof draft.title === 'string' ? draft.title.trim() : '';
         const statement = typeof draft.statement === 'string' ? draft.statement.trim() : '';
         if (title && statement)
-            return `${title} �?${statement}`;
+            return `${title} �?${statement}`;
         if (title)
             return title;
         if (statement)
@@ -90,7 +90,7 @@ function extractCandidateDescription(contentJson) {
     return null;
 }
 /**
- * PRI-935: would this candidate's own prompt entry fit the injection budget if
+ * PR-1894: would this candidate's own prompt entry fit the injection budget if
  * it were the ONLY entry?
  *
  * Uses the production text resolver and the production entry format/escaping
@@ -101,13 +101,13 @@ function extractCandidateDescription(contentJson) {
  * fair rotation cannot deliver it.
  *
  * Degrades to `false` (do not promise rotation) whenever the real size cannot be
- * determined �?an unknown size must never become a promise (rc-9).
+ * determined �?an unknown size must never become a promise (rc-9).
  */
 function candidateFitsPromptBudget(artifact) {
     if (!artifact?.contentJson)
         return false;
     // The pending candidate has no activation row yet, but the resolver only
-    // needs the artifact plus an id pair �?this mirrors what approve will do.
+    // needs the artifact plus an id pair �?this mirrors what approve will do.
     const resolved = resolvePrincipleFromArtifact({
         artifact_id: artifact.artifactId,
         artifact_kind: artifact.artifactKind,
@@ -139,7 +139,7 @@ export class ApprovalsGroupedConsoleModel {
     async getApprovalsGrouped() {
         const stateDbPath = path.join(this.workspaceDir, '.pd', 'state.db');
         if (!fs.existsSync(stateDbPath)) {
-            return { groups: [], generatedAt: new Date().toISOString(), note: 'state.db not found �?workspace may not be initialized' };
+            return { groups: [], generatedAt: new Date().toISOString(), note: 'state.db not found �?workspace may not be initialized' };
         }
         const conn = new SqliteConnection({ workspaceDir: this.workspaceDir, readonly: true });
         try {
@@ -152,21 +152,21 @@ export class ApprovalsGroupedConsoleModel {
             }
             catch (err) {
                 if (isMissingTableError(err)) {
-                    return { groups: [], generatedAt: new Date().toISOString(), note: 'approval table not found �?workspace may not be initialized' };
+                    return { groups: [], generatedAt: new Date().toISOString(), note: 'approval table not found �?workspace may not be initialized' };
                 }
                 throw err;
             }
-            // Build artifactId �?sourcePrincipleId map AND artifactId �?candidateDescription map.
+            // Build artifactId �?sourcePrincipleId map AND artifactId �?candidateDescription map.
             // Wave 7: candidateDescription lets FocusPage show human-readable content
             // instead of a fabricated principleId.
             //
             // PRI-768 v5 follow-up (F3): sourcePrincipleId is null for most scribe
             // artifacts, which used to collapse every group to `unlinked:<id>` and
             // dead-end the owner decision UI. When the column is missing, fall back
-            // to the shared lineage resolver (scribe �?dreamer seed �?candidateId �?      // ledger derivedFromPainIds) so groups bind to the REAL ledger id.
+            // to the shared lineage resolver (scribe �?dreamer seed �?candidateId �?      // ledger derivedFromPainIds) so groups bind to the REAL ledger id.
             const artifactPrincipleMap = new Map();
             const artifactDescriptionMap = new Map();
-            // PRI-935: per-artifact "does this entry fit the budget alone" fact, so
+            // PR-1894: per-artifact "does this entry fit the budget alone" fact, so
             // the pre-approval badge never promises rotation for an entry that is
             // oversized (rotation cannot rescue a per-entry overflow).
             const artifactFitsBudgetMap = new Map();
@@ -207,9 +207,9 @@ export class ApprovalsGroupedConsoleModel {
                 }
             }
             catch {
-                // Ledger not available �?will fall back to principleId
+                // Ledger not available �?will fall back to principleId
             }
-            // Group by principleId (null �?"unlinked")
+            // Group by principleId (null �?"unlinked")
             const groupMap = new Map();
             for (const approval of allApprovals) {
                 const mappedPrincipleId = artifactPrincipleMap.get(approval.artifactId);
@@ -253,7 +253,7 @@ export class ApprovalsGroupedConsoleModel {
                     principleTitle,
                     candidateDescription,
                     status,
-                    // PRI-935: undefined-safe �?absent when the artifact could not be
+                    // PR-1894: undefined-safe �?absent when the artifact could not be
                     // read, which the UI treats as "do not promise rotation".
                     ...(firstArtifactId !== undefined && artifactFitsBudgetMap.has(firstArtifactId)
                         ? { fitsPromptBudget: artifactFitsBudgetMap.get(firstArtifactId) === true }
@@ -276,11 +276,11 @@ export class ApprovalsGroupedConsoleModel {
     }
     /**
      * PRI-908: recompute the production prompt injection projection so the
-     * focus page can forecast "approved �?effective" BEFORE the Owner decides.
+     * focus page can forecast "approved �?effective" BEFORE the Owner decides.
      * PR #1844 follow-up: the forecast follows the workspace's REAL injection
-     * route (`buildLivePromptInjectionProjection` �?legacy trimToBudget vs
+     * route (`buildLivePromptInjectionProjection` �?legacy trimToBudget vs
      * shared render via abstraction_layer_v1), matching the PRI-890 approve-time
-     * check. Advisory only: a projection failure omits the field �?the
+     * check. Advisory only: a projection failure omits the field �?the
      * approve-time warning remains the fail-loud exclusion report (rc-9), so
      * this must never fail the grouped read.
      */
@@ -292,7 +292,7 @@ export class ApprovalsGroupedConsoleModel {
                     budget: projection.budget,
                     usedChars: projection.usedChars,
                     truncated: projection.truncated,
-                    // PRI-935: the badge must describe what the PRODUCTION route will do,
+                    // PR-1894: the badge must describe what the PRODUCTION route will do,
                     // not which policy this session-less forecast happened to run.
                     // Without it the UI can only say "will queue", which under fair
                     // rotation reads as permanent starvation and pushes the Owner to

package/console/dist/shared/prompt-injection-contract.d.ts

@@ -19,19 +19,19 @@ export interface PromptInjectionBudgetStatus {
     usedChars: number;
     /**
      * True when the CURRENT projection already truncated — the newly approved
-     * principle may not enter the prompt on this turn. PRI-935: this is
+     * principle may not enter the prompt on this turn. PR-1894: this is
      * policy-dependent (see `selectionPolicy`); the badge copy must not imply
      * permanent starvation when rotation is in play.
      */
     truncated: boolean;
     /**
-     * PRI-935: whether the PRODUCTION route rotates. This — not the forecast's
+     * PR-1894: whether the PRODUCTION route rotates. This — not the forecast's
      * own selection policy — decides whether an out-of-window approval is queued
      * behind rotation or genuinely starved, and therefore which badge copy is
-     * truthful. Optional so a pre-PRI-935 payload still validates; absent
-     * behaves as `false` (the conservative pre-PRI-935 reading).
+     * truthful. Optional so a pre-PR-1894 payload still validates; absent
+     * behaves as `false` (the conservative pre-PR-1894 reading).
      */
     productionRotates?: boolean;
-    /** PRI-935: eligible activations that reached the selector. */
+    /** PR-1894: eligible activations that reached the selector. */
     eligibleCount?: number;
 }

package/console/dist/ui/pages/focus/FocusPage.js

@@ -148,7 +148,7 @@ function PendingReviewCard({ group, actionsLockedReason, onDecisionApplied, prom
     function notifySuccessWarnings(successWarnings) {
         const segments = successWarnings.flatMap((warning) => splitApprovalWarnings(warning));
         const localized = segments.map((warning) => localizeApprovalWarning(warning, t));
-        // PRI-935: the raw server text is still preserved verbatim (rc-9 — never
+        // PR-1894: the raw server text is still preserved verbatim (rc-9 — never
         // dropped), but it is operator-facing English, not Owner-facing prose. It
         // used to be appended flat under the localized body, so the toast rendered
         // as one mixed Chinese/English block and the machine text visually

package/console/dist/ui/pages/focus/focus-validation.js

@@ -54,7 +54,7 @@ function validateApprovalGroup(raw) {
             return null;
         candidateDescription = description;
     }
-    // PRI-935: fitsPromptBudget is optional. ERR-009 discipline — present but
+    // PR-1894: fitsPromptBudget is optional. ERR-009 discipline — present but
     // wrong type fails loud; absent stays undefined, which the badge treats as
     // "unknown size → do not promise rotation".
     let fitsPromptBudget;

package/console/dist/ui/utils/approval-warning-localization.js

@@ -65,7 +65,7 @@ export function localizeApprovalWarning(warning, t) {
             activationAction: true,
         };
     }
-    // PRI-935: the activation is merely rotated out of the CURRENT window, not
+    // PR-1894: the activation is merely rotated out of the CURRENT window, not
     // starved. This is the common case on a live fair-rotation workspace and the
     // copy must NOT tell the Owner to deactivate healthy older principles.
     if (code === 'injection_budget_queued') {

package/console/dist/ui/utils/validators.d.ts

@@ -637,7 +637,7 @@ export interface ApprovalGroupData {
     /** Wave 7: human-readable principle text from artifact contentJson, if available */
     candidateDescription?: string;
     /**
-     * PRI-935: whether this candidate's own serialized prompt entry fits the
+     * PR-1894: whether this candidate's own serialized prompt entry fits the
      * injection budget alone. Absent = unknown, which the badge treats as
      * "do not promise rotation".
      */

package/console/dist/ui/utils/validators.js

@@ -1646,7 +1646,7 @@ function validateApprovalGroup(v) {
     if (Object.hasOwn(v, 'candidateDescription') && isString(v.candidateDescription) && v.candidateDescription.length > 0) {
         result.candidateDescription = v.candidateDescription;
     }
-    // PRI-935: optional fitsPromptBudget. Only a real boolean is propagated; a
+    // PR-1894: optional fitsPromptBudget. Only a real boolean is propagated; a
     // present-but-wrong value is dropped (rc-1/rc-2) so the badge falls back to
     // copy that promises nothing rather than rendering an unverified claim.
     if (Object.hasOwn(v, 'fitsPromptBudget') && typeof v.fitsPromptBudget === 'boolean') {
@@ -1666,7 +1666,7 @@ export function validatePromptInjectionBudgetStatus(v) {
         return null;
     }
     const result = { budget, usedChars, truncated };
-    // PRI-935: these are optional so a pre-PRI-935 server payload still
+    // PR-1894: these are optional so a pre-PR-1894 server payload still
     // validates (backward compatibility). A present-but-invalid value is
     // DROPPED, never propagated (rc-1/rc-2): the UI then falls back to
     // policy-agnostic copy rather than rendering an unverified policy claim.

package/console/package.json

@@ -22,7 +22,7 @@
     "verify:build": "node scripts/verify-build.mjs"
   },
   "dependencies": {
-    "@fontsource/jetbrains-mono": "^5.2.8",
+    "@fontsource/jetbrains-mono": "^5.3.0",
     "@principles/core": "file:../core",
     "@principles/host-runtime": "file:../host-runtime",
     "@principles/install-layout": "file:../install-layout",

package/core/dist/principle-tree-ledger.d.ts

@@ -16,7 +16,9 @@
 import type { Principle, Rule, Implementation, PrincipleValueMetrics, LedgerPrinciple, LedgerRule, LedgerTreeStore, LegacyPrincipleTrainingState, LegacyPrincipleTrainingStore, HybridLedgerStore } from './runtime-v2/types/ledger-store.js';
 import { TREE_NAMESPACE } from './runtime-v2/types/ledger-store.js';
 import type { ImplementationLifecycleState } from './runtime-v2/types/principle-enums.js';
+import type { ReuseEvidenceActor, ReuseEvidenceEntry } from './runtime-v2/types/principle-schema.js';
 export type { Principle, Rule, Implementation, PrincipleValueMetrics, LedgerPrinciple, LedgerRule, LedgerTreeStore, LegacyPrincipleTrainingState, LegacyPrincipleTrainingStore, HybridLedgerStore, ImplementationLifecycleState, };
+export type { ReuseEvidenceActor, ReuseEvidenceEntry };
 export { TREE_NAMESPACE };
 export declare class LockAcquisitionError extends Error {
     readonly filePath: string;
@@ -43,6 +45,54 @@ export declare function loadLedger(stateDir: string): HybridLedgerStore;
 export declare function saveLedger(stateDir: string, store: HybridLedgerStore): void;
 export declare function addPrincipleToLedger(stateDir: string, principle: LedgerPrinciple): LedgerPrinciple;
 export declare function updatePrinciple(stateDir: string, principleId: string, updates: Partial<LedgerPrinciple>): LedgerPrinciple;
+/**
+ * Thrown when the ledger file's content is not trustworthy for a read-modify-
+ * write: it parses to an empty principles tree while the file exists on disk
+ * (empty, corrupt, or truncated), or an entity's persisted reuseEvidence field
+ * has a malformed shape. Unlike a missing principle, writing over this state
+ * would DESTROY ledger content, so the write refuses instead of proceeding
+ * (rc-3).
+ */
+export declare class LedgerIntegrityError extends Error {
+    readonly filePath: string;
+    constructor(message: string, filePath: string);
+}
+/**
+ * Append one reuse-evidence entry to an existing Principle (PRI-917 PR3B,
+ * SPEC v0.2.1 §12). The ONLY writer for `Principle.reuseEvidence`.
+ *
+ * Runs entirely inside the single-writer file lock via mutateLedger —
+ * read → integrity guard → dedupe → append → save — so a concurrent append
+ * can never be lost, and there is no load-then-update window between
+ * processes. Do NOT implement appends via addPrincipleToLedger (it replaces
+ * the whole entry and would silently drop existing evidence) or via an
+ * external loadLedger+updatePrinciple sequence (read outside the lock).
+ *
+ * Fail-closed:
+ *   - a ledger file that exists but parses to an empty principles tree (empty
+ *     file, corrupt, or truncated) is treated as corruption — the write
+ *     refuses rather than risk replacing the corpus with the new entry alone
+ *     (LedgerIntegrityError);
+ *   - a missing principleId refuses the write (no file mutation);
+ *   - a malformed entry refuses the write.
+ *
+ * Idempotency key: (principleId, entry.candidateId). A candidate resolves
+ * into a principle at most once, so replaying the same decision is a no-op
+ * that returns the existing evidence with `appended: false` (INV-R07). A
+ * no-op still goes through the normal save path, so the tree's lastUpdated
+ * is refreshed; the ledger content itself is unchanged.
+ *
+ * Append-only (INV-R05): no other Principle field — including updatedAt —
+ * is touched, and existing entries are never rewritten or removed. Target
+ * eligibility (e.g. archived/deprecated exclusion, SPEC §15) is the
+ * retrieval/proposal layer's invariant; this writer records the decision
+ * verbatim.
+ */
+export declare function appendReuseEvidence(stateDir: string, principleId: string, entry: ReuseEvidenceEntry): {
+    principleId: string;
+    reuseEvidence: ReuseEvidenceEntry[];
+    appended: boolean;
+};
 export declare function updatePrincipleValueMetrics(stateDir: string, principleId: string, metrics: PrincipleValueMetrics): PrincipleValueMetrics;
 export declare function getLedgerFilePathPublic(stateDir: string): string;
 export interface PrincipleSubtree {

package/core/dist/principle-tree-ledger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"principle-tree-ledger.d.ts","sourceRoot":"","sources":["../src/principle-tree-ledger.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"principle-tree-ledger.d.ts","sourceRoot":"","sources":["../src/principle-tree-ledger.ts"],"names":[],"mappings":"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"}

package/core/dist/principle-tree-ledger.js

@@ -17,7 +17,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { TREE_NAMESPACE } from './runtime-v2/types/ledger-store.js';
 // PRI-443: Pure parse/serialize functions extracted to codec module
-import { uniqueStrings, createEmptyTree, parseHybridLedger, serializeLedger, } from './runtime-v2/principle-tree/ledger-codec.js';
+import { isRecord, uniqueStrings, createEmptyTree, parseHybridLedger, serializeLedger, } from './runtime-v2/principle-tree/ledger-codec.js';
 export { TREE_NAMESPACE };
 const PRINCIPLE_TRAINING_FILE = 'principle_training_state.json';
 // ---------------------------------------------------------------------------
@@ -391,6 +391,138 @@ export function updatePrinciple(stateDir, principleId, updates) {
         return next;
     });
 }
+// ---------------------------------------------------------------------------
+// PRI-917 PR3B: reuse evidence append (SPEC v0.2.1 §12)
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when the ledger file's content is not trustworthy for a read-modify-
+ * write: it parses to an empty principles tree while the file exists on disk
+ * (empty, corrupt, or truncated), or an entity's persisted reuseEvidence field
+ * has a malformed shape. Unlike a missing principle, writing over this state
+ * would DESTROY ledger content, so the write refuses instead of proceeding
+ * (rc-3).
+ */
+export class LedgerIntegrityError extends Error {
+    filePath;
+    constructor(message, filePath) {
+        super(message);
+        this.name = 'LedgerIntegrityError';
+        this.filePath = filePath;
+    }
+}
+const REUSE_EVIDENCE_KEYS = [
+    'painId',
+    'candidateId',
+    'decision',
+    'actor',
+    'reason',
+    'decidedAt',
+    'decisionId',
+];
+/**
+ * Runtime shape check for an untrusted reuse evidence entry (rc-1/rc-2/rc-3).
+ * The caller-side decision surface parses owner/model output, so the ledger
+ * writer re-validates at this boundary: any malformed or unexpected field
+ * refuses the write — a half-valid evidence row must never land in the ledger.
+ */
+function validateReuseEvidenceEntry(entry) {
+    const refuse = (detail) => {
+        throw new Error(`appendReuseEvidence: malformed reuse evidence entry (${detail}) — refusing to write (fail closed).`);
+    };
+    if (!isRecord(entry))
+        refuse(`expected an object, got ${typeof entry}`);
+    for (const key of Object.keys(entry)) {
+        if (!REUSE_EVIDENCE_KEYS.includes(key))
+            refuse(`unknown field "${key}"`);
+    }
+    if (typeof entry.painId !== 'string' || entry.painId.trim() === '')
+        refuse('painId must be a non-empty string');
+    if (typeof entry.candidateId !== 'string' || entry.candidateId.trim() === '') {
+        refuse('candidateId must be a non-empty string');
+    }
+    if (entry.decision !== 'reuse')
+        refuse('decision must be exactly "reuse"');
+    if (!isRecord(entry.actor))
+        refuse('actor must be an object');
+    if (entry.actor.kind !== 'owner' && entry.actor.kind !== 'ai_owner') {
+        refuse('actor.kind must be "owner" or "ai_owner"');
+    }
+    if (typeof entry.actor.id !== 'string' || entry.actor.id.trim() === '')
+        refuse('actor.id must be a non-empty string');
+    if (typeof entry.reason !== 'string' || entry.reason.trim() === '')
+        refuse('reason must be a non-empty string');
+    if (typeof entry.decidedAt !== 'string' || entry.decidedAt.trim() === '' || Number.isNaN(Date.parse(entry.decidedAt))) {
+        refuse('decidedAt must be a parseable date string');
+    }
+    if (entry.decisionId !== undefined && (typeof entry.decisionId !== 'string' || entry.decisionId.trim() === '')) {
+        refuse('decisionId, when present, must be a non-empty string');
+    }
+}
+/**
+ * Append one reuse-evidence entry to an existing Principle (PRI-917 PR3B,
+ * SPEC v0.2.1 §12). The ONLY writer for `Principle.reuseEvidence`.
+ *
+ * Runs entirely inside the single-writer file lock via mutateLedger —
+ * read → integrity guard → dedupe → append → save — so a concurrent append
+ * can never be lost, and there is no load-then-update window between
+ * processes. Do NOT implement appends via addPrincipleToLedger (it replaces
+ * the whole entry and would silently drop existing evidence) or via an
+ * external loadLedger+updatePrinciple sequence (read outside the lock).
+ *
+ * Fail-closed:
+ *   - a ledger file that exists but parses to an empty principles tree (empty
+ *     file, corrupt, or truncated) is treated as corruption — the write
+ *     refuses rather than risk replacing the corpus with the new entry alone
+ *     (LedgerIntegrityError);
+ *   - a missing principleId refuses the write (no file mutation);
+ *   - a malformed entry refuses the write.
+ *
+ * Idempotency key: (principleId, entry.candidateId). A candidate resolves
+ * into a principle at most once, so replaying the same decision is a no-op
+ * that returns the existing evidence with `appended: false` (INV-R07). A
+ * no-op still goes through the normal save path, so the tree's lastUpdated
+ * is refreshed; the ledger content itself is unchanged.
+ *
+ * Append-only (INV-R05): no other Principle field — including updatedAt —
+ * is touched, and existing entries are never rewritten or removed. Target
+ * eligibility (e.g. archived/deprecated exclusion, SPEC §15) is the
+ * retrieval/proposal layer's invariant; this writer records the decision
+ * verbatim.
+ */
+export function appendReuseEvidence(stateDir, principleId, entry) {
+    validateReuseEvidenceEntry(entry);
+    const filePath = getLedgerFilePath(stateDir);
+    // Stat captured just before the lock as a hint; the authoritative check is
+    // the in-lock one below against the parsed store. A file created between
+    // this stat and the lock cannot trip the guard (it only fires when the
+    // file already existed at stat time AND the parsed tree is empty).
+    const statBefore = fs.existsSync(filePath) ? fs.statSync(filePath) : null;
+    return mutateLedger(stateDir, (store) => {
+        if (statBefore !== null && Object.keys(store.tree.principles).length === 0) {
+            throw new LedgerIntegrityError(`Ledger file ${filePath} exists (${statBefore.size} bytes) but parsed to an empty principles tree — ` +
+                'the file is likely corrupt or truncated. Refusing to append reuse evidence, because the save ' +
+                'below would replace the ledger with this write alone. Restore the ledger file first (fail closed).', filePath);
+        }
+        const principle = store.tree.principles[principleId];
+        if (!principle) {
+            throw new Error(`Cannot append reuse evidence: principle "${principleId}" does not exist in the ledger.`);
+        }
+        const existing = principle.reuseEvidence;
+        if (existing !== undefined && !Array.isArray(existing)) {
+            throw new LedgerIntegrityError(`Principle "${principleId}" has a malformed reuseEvidence field (expected an array, got ${typeof existing}). ` +
+                'Refusing to append — fix or restore the ledger entry first (fail closed).', filePath);
+        }
+        const current = existing ?? [];
+        if (current.some((e) => isRecord(e) && e.candidateId === entry.candidateId)) {
+            // Idempotent replay (INV-R07): this candidate already resolved into
+            // this principle. No new entry, no new logical decision.
+            return { principleId, reuseEvidence: current, appended: false };
+        }
+        const next = [...current, entry];
+        principle.reuseEvidence = next;
+        return { principleId, reuseEvidence: next, appended: true };
+    });
+}
 export function updatePrincipleValueMetrics(stateDir, principleId, metrics) {
     return mutateLedger(stateDir, (store) => {
         const next = { ...metrics, principleId };