create-principles-disciple 1.94.0 → 1.95.0

package/plugin/dist/core/intent-doc-reader.js

@@ -0,0 +1,189 @@
+/**
+ * PRI-467 — safeReadIntentDoc: plugin I/O wrapper for reading INTENT.md.
+ *
+ * Reads `.principles/INTENT.md` with:
+ * - Feature flag check FIRST (SPEC §12: flag off → flag_disabled without fs)
+ * - TTL + mtime cache (60s TTL, mtime check) mirroring prompt.ts cachedReadFile
+ * - 32KB size cap (INTENT_MAX_BYTES)
+ * - Never throws — all errors return structured `reason` + `nextAction`
+ *
+ * Trust boundary (SPEC §12.2):
+ * - Raw content is returned for the pure builder to escape; this reader does
+ *   NOT escape or bound the content for prompt injection. The pure builder
+ *   `buildIntentFrictionBlock` handles escaping + bounding.
+ *
+ * ERR checklist:
+ * EP-01 / ERR-001, ERR-005: raw content validated with typeof, never `as`
+ * EP-02 / ERR-025, ERR-070: production path; plugin I/O file in the whitelist
+ * EP-03 / ERR-002, ERR-014: every degraded path returns structured reason + nextAction
+ * EP-09: tests use real fs writes in temp dirs
+ *
+ * Architecture: this file is I/O (fs, path). It is whitelisted in
+ * architecture-regression.test.ts KNOWN_PLUGIN_CORE_FILES.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { INTENT_MAX_BYTES, parseIntentDocSections, computeIntentContentHash, validateIntentDocSections, } from '@principles/core/runtime-v2';
+import { loadFeatureFlagFromConfig } from './pd-config-loader.js';
+// ── Constants ────────────────────────────────────────────────────────────────
+const INTENT_FILENAME = 'INTENT.md';
+const INTENT_DIR = '.principles';
+const INTENT_CACHE_TTL_MS = 60_000; // 1 minute (SPEC §12.1)
+// ── Module-level cache (per-workspace) ───────────────────────────────────────
+const _intentDocCache = new Map();
+/**
+ * Reset the intent doc cache for test isolation.
+ * Call in beforeEach() to ensure tests don't pollute each other.
+ */
+export function resetIntentDocCacheForTest(workspaceDir) {
+    if (workspaceDir) {
+        _intentDocCache.delete(workspaceDir);
+    }
+    else {
+        _intentDocCache.clear();
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function getIntentFilePath(workspaceDir) {
+    return path.join(workspaceDir, INTENT_DIR, INTENT_FILENAME);
+}
+function buildDocFromRaw(raw, filePath, readAt) {
+    const sections = parseIntentDocSections(raw);
+    const warnings = validateIntentDocSections(sections);
+    const contentHash = computeIntentContentHash(raw);
+    return {
+        raw,
+        sections,
+        contentHash,
+        path: filePath,
+        readAt,
+        warnings,
+    };
+}
+// ── Main entrypoint ──────────────────────────────────────────────────────────
+/**
+ * Safely read INTENT.md for prompt injection.
+ *
+ * Contract (SPEC §12):
+ * 1. Flag check FIRST via loadFeatureFlagFromConfig. Flag off → flag_disabled
+ *    WITHOUT any fs access to INTENT.md.
+ * 2. Flag on → check TTL + mtime cache. If cached and fresh → return cached.
+ * 3. Otherwise → stat the file (oversized check), read, parse, validate, cache.
+ * 4. Never throws — all errors return structured reason + nextAction.
+ *
+ * @param workspaceDir - Absolute path to the workspace root
+ * @param options - Optional logger for debug-level diagnostics
+ * @returns SafeReadIntentDocResult (never throws)
+ */
+export function safeReadIntentDoc(workspaceDir, options) {
+    // SPEC §12 — Flag check FIRST. Flag off → no fs access, no cache access.
+    const flagResult = loadFeatureFlagFromConfig(workspaceDir, 'intent_engineering', options?.logger);
+    if (!flagResult.enabled) {
+        return {
+            ok: false,
+            found: false,
+            flagEnabled: false,
+            reason: 'flag_disabled',
+            nextAction: 'Enable the intent_engineering feature flag in .pd/config.yaml to read INTENT.md.',
+            warnings: [],
+        };
+    }
+    const filePath = getIntentFilePath(workspaceDir);
+    const now = Date.now();
+    // Check cache freshness (TTL + mtime)
+    const cached = _intentDocCache.get(workspaceDir);
+    if (cached && (now - cached.loadedAt) < INTENT_CACHE_TTL_MS) {
+        // Cache is within TTL. Verify mtime hasn't changed.
+        try {
+            const stat = fs.statSync(filePath);
+            if (stat.mtimeMs === cached.mtime) {
+                // Cache hit — return cached doc
+                return {
+                    ok: true,
+                    found: true,
+                    flagEnabled: true,
+                    doc: cached.doc,
+                    warnings: cached.doc.warnings,
+                };
+            }
+        }
+        catch {
+            // File may have been deleted since caching. Fall through to not_found path.
+            // Don't return cached doc if the file no longer exists.
+        }
+    }
+    // Fresh read path
+    try {
+        // Check existence first
+        if (!fs.existsSync(filePath)) {
+            // Invalidate stale cache entry if any
+            _intentDocCache.delete(workspaceDir);
+            return {
+                ok: false,
+                found: false,
+                flagEnabled: true,
+                reason: 'not_found',
+                nextAction: 'Create .principles/INTENT.md using "pd intent init".',
+                warnings: [],
+            };
+        }
+        const stat = fs.statSync(filePath);
+        // SPEC §12 — 32KB size cap
+        if (stat.size > INTENT_MAX_BYTES) {
+            _intentDocCache.delete(workspaceDir);
+            return {
+                ok: false,
+                found: true,
+                flagEnabled: true,
+                reason: 'oversized',
+                nextAction: `INTENT.md exceeds ${INTENT_MAX_BYTES} bytes (${stat.size} bytes). Reduce content.`,
+                warnings: [],
+            };
+        }
+        const raw = fs.readFileSync(filePath, 'utf8');
+        // PRI-467 review fix (P2): TOCTOU guard — re-check actual byte length
+        // after readFileSync. The file may have grown between statSync() and
+        // readFileSync(), bypassing the stat.size oversized check. Without this,
+        // an oversized file would enter parse/hash/cache as ok:true.
+        const actualBytes = Buffer.byteLength(raw, 'utf8');
+        if (actualBytes > INTENT_MAX_BYTES) {
+            _intentDocCache.delete(workspaceDir);
+            return {
+                ok: false,
+                found: true,
+                flagEnabled: true,
+                reason: 'oversized',
+                nextAction: `INTENT.md exceeds ${INTENT_MAX_BYTES} bytes (${actualBytes} bytes after read). Reduce content.`,
+                warnings: [],
+            };
+        }
+        const doc = buildDocFromRaw(raw, filePath, new Date(now).toISOString());
+        // Update cache
+        _intentDocCache.set(workspaceDir, {
+            doc,
+            mtime: stat.mtimeMs,
+            loadedAt: now,
+        });
+        return {
+            ok: true,
+            found: true,
+            flagEnabled: true,
+            doc,
+            warnings: doc.warnings,
+        };
+    }
+    catch (err) {
+        // ERR-002 — graceful degradation with reason + nextAction
+        _intentDocCache.delete(workspaceDir);
+        const message = err instanceof Error ? err.message : String(err);
+        options?.logger?.warn?.(`[PD:Intent] safeReadIntentDoc failed: workspace=${workspaceDir}, error=${message}`);
+        return {
+            ok: false,
+            found: false,
+            flagEnabled: true,
+            reason: 'read_error',
+            nextAction: 'Check filesystem permissions for .principles/INTENT.md.',
+            warnings: [],
+        };
+    }
+}

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

@@ -1,82 +1,30 @@
-import type { Implementation, ImplementationLifecycleState, Principle, PrincipleTreeStore, PrincipleValueMetrics, Rule } from '../types/principle-tree-schema.js';
-export declare const TREE_NAMESPACE = "_tree";
-export interface LegacyPrincipleTrainingState {
-    principleId: string;
-    evaluability: 'deterministic' | 'weak_heuristic' | 'manual_only';
-    applicableOpportunityCount: number;
-    observedViolationCount: number;
-    complianceRate: number;
-    violationTrend: number;
-    generatedSampleCount: number;
-    approvedSampleCount: number;
-    includedTrainRunIds: string[];
-    deployedCheckpointIds: string[];
-    lastEvalScore?: number;
-    internalizationStatus: 'prompt_only' | 'needs_training' | 'in_training' | 'deployed_pending_eval' | 'internalized' | 'regressed';
-}
-export type LegacyPrincipleTrainingStore = Record<string, LegacyPrincipleTrainingState>;
-export interface LedgerPrinciple extends Principle {
-    suggestedRules?: string[];
-}
-export interface LedgerRule extends Rule {
-    implementationIds: string[];
-}
-export interface LedgerTreeStore extends Omit<PrincipleTreeStore, 'principles' | 'rules'> {
-    principles: Record<string, LedgerPrinciple>;
-    rules: Record<string, LedgerRule>;
-}
-export interface HybridLedgerStore {
-    trainingStore: LegacyPrincipleTrainingStore;
-    tree: LedgerTreeStore;
-}
-export interface PrincipleSubtree {
-    principle: LedgerPrinciple;
-    rules: {
-        rule: LedgerRule;
-        implementations: Implementation[];
-    }[];
-}
-export declare function getLedgerFilePath(stateDir: string): string;
-export declare function loadLedger(stateDir: string): HybridLedgerStore;
-export declare function saveLedger(stateDir: string, store: HybridLedgerStore): void;
-export declare function saveLedgerAsync(stateDir: string, store: HybridLedgerStore): Promise<void>;
-export declare function updateTrainingStore(stateDir: string, mutate: (store: LegacyPrincipleTrainingStore) => void): void;
 /**
- * Add a new principle directly to the ledger tree.
- * This is the companion to updatePrinciple() — use this when creating a NEW
- * principle so the compiler can find it in tree.principles.
+ * Principle Tree Ledger — plugin adapter (re-export) over @principles/core.
  *
- * Idempotent: if the principle already exists, overwrites (update semantics).
- */
-export declare function addPrincipleToLedger(stateDir: string, principle: LedgerPrinciple): LedgerPrinciple;
-export declare function createRule(stateDir: string, rule: LedgerRule): LedgerRule;
-export declare function createImplementation(stateDir: string, implementation: Implementation): Implementation;
-export declare function updatePrinciple(stateDir: string, principleId: string, updates: Partial<LedgerPrinciple>): LedgerPrinciple;
-export declare function updateRule(stateDir: string, ruleId: string, updates: Partial<LedgerRule>): LedgerRule;
-export declare function deleteRule(stateDir: string, ruleId: string): LedgerRule | undefined;
-export declare function updateImplementation(stateDir: string, implementationId: string, updates: Partial<Implementation>): Implementation;
-export declare function deleteImplementation(stateDir: string, implementationId: string): Implementation | undefined;
-export declare function listImplementationsForRule(stateDir: string, ruleId: string): Implementation[];
-export declare function getPrincipleSubtree(stateDir: string, principleId: string): PrincipleSubtree | undefined;
-export declare function updatePrincipleValueMetrics(stateDir: string, principleId: string, metrics: PrincipleValueMetrics): PrincipleValueMetrics;
-/**
- * Validate a lifecycle state transition.
- * Returns true if the transition is valid, false otherwise.
- */
-export declare function isValidLifecycleTransition(from: ImplementationLifecycleState, to: ImplementationLifecycleState): boolean;
-/**
- * Get allowed transitions for a given lifecycle state.
- */
-export declare function getAllowedTransitions(from: ImplementationLifecycleState): ImplementationLifecycleState[];
-/**
- * Transition an implementation's lifecycle state with validation.
- * Throws on invalid transitions */
-export declare function transitionImplementationState(stateDir: string, implementationId: string, newState: ImplementationLifecycleState): Implementation;
-/**
- * Get implementations in a specific lifecycle state for a given rule.
- */
-export declare function listRuleImplementationsByState(stateDir: string, ruleId: string, state: ImplementationLifecycleState): Implementation[];
-/**
- * Find active implementation for a rule (helper for rule host lookup).
+ * PRI-459: This file WAS a full duplicate implementation of
+ * principle_training_state.json parsing / serialization / mutation (~600
+ * lines of inlined parsers, serializers, mutators, and a parallel codec).
+ * That dual ownership caused two real failure classes:
+ *
+ *   1. Lost updates — core wrote the file UNLOCKED, the plugin wrote it WITH
+ *      a lock, and neither knew the other's lock. Concurrent writers (e.g.
+ *      evolution-worker async + a pd-cli command) could silently drop edits.
+ *   2. Silent field loss — the two codecs parsed the same bytes at different
+ *      strictness; a field one side persisted could be dropped on the next
+ *      load by the other.
+ *
+ * Both are now fixed by converging on a SINGLE source of truth in core:
+ *   - parse/serialize: @principles/core/runtime-v2/principle-tree/ledger-codec
+ *   - mutation (with cross-process file lock): @principles/core/principle-tree-ledger
+ *
+ * This file is now a thin re-export so existing relative imports
+ * (`from './principle-tree-ledger.js'`) keep resolving. Consumers get the
+ * exact same API surface, now backed by the locked core implementation.
+ *
+ * Do NOT reintroduce parsing / serialization / mutation logic here. The
+ * architecture-regression guard "PRI-459: single principle_training_state
+ * ledger implementation" enforces this.
  */
-export declare function findActiveImplementation(stateDir: string, ruleId: string): Implementation | null;
+export { type Principle, type Rule, type Implementation, type PrincipleValueMetrics, type LedgerPrinciple, type LedgerRule, type LedgerTreeStore, type LegacyPrincipleTrainingState, type LegacyPrincipleTrainingStore, type HybridLedgerStore, type ImplementationLifecycleState, type PrincipleSubtree, TREE_NAMESPACE, LockAcquisitionError, loadLedger, saveLedger, saveLedgerAsync, updateTrainingStore, addPrincipleToLedger, createRule, createImplementation, updatePrinciple, updateRule, deleteRule, updateImplementation, deleteImplementation, listImplementationsForRule, getPrincipleSubtree, updatePrincipleValueMetrics, isValidLifecycleTransition, getAllowedTransitions, transitionImplementationState, listRuleImplementationsByState, findActiveImplementation, } from '@principles/core/principle-tree-ledger';
+import { getLedgerFilePathPublic } from '@principles/core/principle-tree-ledger';
+export declare const getLedgerFilePath: typeof getLedgerFilePathPublic;