create-principles-disciple 1.144.11 → 1.144.13

package/_release/product-identity.json

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

package/codex-adapter/dist/pd-hook.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { readFileSync, realpathSync } from 'node:fs';
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { pathToFileURL, fileURLToPath } from 'node:url';
@@ -195,11 +196,27 @@ export async function processHookInvocation(rawStdin, _env = process.env, cwd =
         const nextAction = error instanceof CodexDecoderError ? error.nextAction : 'Inspect the Codex 0.147 hook payload.';
         return { stdout: {}, exitCode: 0, stderr: [diagnostic(reason, nextAction)] };
     }
-    // Codex 0.147 supplies the invocation cwd. It is the authoritative starting
-    // point; a process-global environment variable can otherwise route one
-    // Workspace's hook into another Workspace's business state.
+    // Initializing the user workspace explicitly opts Codex into shared
+    // governance. Otherwise preserve the existing per-project resolution.
     const requestedCwd = event.context.workspaceDir || cwd;
-    const resolution = resolveNearestPdWorkspace(requestedCwd);
+    if (!path.isAbsolute(requestedCwd))
+        return { stdout: {}, exitCode: 0, stderr: [diagnostic('cwd_not_absolute', 'Provide the absolute Codex project directory.')] };
+    // Resolve like pd-locate.cjs does: a relative CODEX_HOME must yield the same
+    // absolute workspace for hooks and owner scripts, or resolveNearestPdWorkspace
+    // rejects it after the config check already accepted it.
+    const userWorkspace = path.join(path.resolve(_env.CODEX_HOME || path.join(os.homedir(), '.codex')), 'pd-workspace');
+    let userWorkspaceInitialized = false;
+    try {
+        userWorkspaceInitialized = statSync(path.join(userWorkspace, '.pd', 'config.yaml')).isFile();
+        if (!userWorkspaceInitialized)
+            return { stdout: {}, exitCode: 0, stderr: [diagnostic('user_workspace_config_invalid', 'Repair the user workspace .pd/config.yaml; project configuration was not used.')] };
+    }
+    catch (error) {
+        if (!(error instanceof Error && Object.hasOwn(error, 'code') && Reflect.get(error, 'code') === 'ENOENT')) {
+            return { stdout: {}, exitCode: 0, stderr: [diagnostic('user_workspace_config_unreadable', 'Restore access to the user workspace .pd/config.yaml; project configuration was not used.')] };
+        }
+    }
+    const resolution = resolveNearestPdWorkspace(userWorkspaceInitialized ? userWorkspace : requestedCwd);
     if (!resolution.ok)
         return { stdout: {}, exitCode: 0, stderr: [diagnostic(resolution.reason, resolution.nextAction)] };
     event = { ...event, context: { ...event.context, workspaceDir: resolution.workspaceDir } };
@@ -242,6 +259,7 @@ export async function processHookInvocation(rawStdin, _env = process.env, cwd =
         // the Codex adapter stays independent of the OpenClaw plugin). The line
         // writer appends synchronously — no flush/dispose needed for the subprocess.
         const result = await createProductionHostRuntime({
+            projectDir: requestedCwd,
             hostKind: 'codex',
             toolSemantics: CODEX_TOOL_SEMANTICS,
             events: codexEventEmitter(path.join(resolution.workspaceDir, '.state')),

package/codex-adapter/dist/worker/workspace-worker.d.ts

@@ -13,6 +13,12 @@ export interface CodexWorkerCycleStepReport {
         readonly errorCategory?: string;
         /** PRI-638 P1-C: recovery action for capability-disabled pauses. */
         readonly nextAction?: string;
+        /**
+         * PRI-917 v0.3.3 review fix (P2-2): candidates parked by the Reuse Review
+         * Gate (suspected duplicates awaiting the Owner). Forwarded per-candidate
+         * so the report shows WHAT awaits the Owner, not just a degraded status.
+         */
+        readonly reuseReviewRequiredCandidateIds?: readonly string[];
     } | null;
     readonly downstream: InternalizationConsumerCycleOutcome | null;
 }

package/codex-adapter/dist/worker/workspace-worker.js

@@ -156,11 +156,18 @@ export async function runCodexWorkspaceWorkerCycle(options) {
                         getEnvVar: (name) => process.env[name],
                     });
                     const executed = await bridge.executePendingDiagnosis({ taskId: candidate.taskId });
+                    // PRI-917 v0.3.3 review fix (P2-2): forward the parked-candidate
+                    // dispositions so the Owner sees the pending items instead of a bare
+                    // degraded status with no subject.
+                    const reuseReviewRequired = (executed.candidateOutcomes ?? [])
+                        .filter((outcome) => outcome.reason === 'reuse_review_required')
+                        .map((outcome) => outcome.candidateId);
                     diagnostician = {
                         taskId: candidate.taskId,
                         status: executed.status,
                         ...(executed.message !== undefined ? { message: executed.message.slice(0, 200) } : {}),
                         ...(executed.errorCategory !== undefined ? { errorCategory: executed.errorCategory } : {}),
+                        ...(reuseReviewRequired.length > 0 ? { reuseReviewRequiredCandidateIds: reuseReviewRequired } : {}),
                     };
                     // The bridge stays cached per workspace (bounded: one per workspace
                     // per worker process, exactly like the OpenClaw plugin host) — no

package/codex-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/codex-adapter",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "description": "Codex CLI host adapter for Principles Disciple — implements HostAdapter interface for OpenAI Codex CLI's stdin/stdout JSON hook model (ADR-0020).",
   "type": "module",
   "main": "./dist/index.js",

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",
@@ -43,7 +43,7 @@
     "js-yaml": "^5.4.1",
     "lucide-react": "^1.28.0",
     "postcss": "^8.5.14",
-    "postcss-cli": "^11.0.1",
+    "postcss-cli": "^12.0.0",
     "principles-disciple": "file:../plugin",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
@@ -61,7 +61,7 @@
     "@types/node": "^26.4.1",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
-    "@types/semver": "^7.7.1",
+    "@types/semver": "^7.8.0",
     "esbuild": "^0.28.2",
     "tsx": "^4.23.12",
     "typescript": "^7.0.2",

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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"}