create-principles-disciple 1.121.7 → 1.121.9

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

@@ -0,0 +1,305 @@
+/**
+ * Governance Experience Snapshot collector — PRI-585 (SPEC v1.5.1).
+ *
+ * Batch source reader for the read-only governance experience layer:
+ *   Batch Source Reader (4 queries + 1 ledger read + 1 config read, once)
+ *     → group facts in memory per principle (GovernanceProjectionCollector.buildFacts)
+ *     → deriveOwnerGovernanceView() per principle (existing projection, zero duplication)
+ *     → deriveGovernanceExperienceSnapshot() aggregate (principles-core pure function)
+ *
+ * Forbidden by SPEC and absent here: `for (principle) { collect() }` — the four
+ * table reads happen exactly once per snapshot regardless of principle count.
+ * The snapshot explains; it never authorizes (ERR-102).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createHash } from 'node:crypto';
+import { deriveGovernanceExperienceSnapshot, deriveOwnerGovernanceView, } from '@principles/core/runtime-v2';
+import { GovernanceProjectionCollector, isRecord, readOwnString, } from './GovernanceProjectionCollector.js';
+import { loadPdConfig } from '../config/pd-config-store.js';
+const EMPTY_TABLES = { artifactRows: [], taskRows: [], approvalRows: [], activationRows: [] };
+const UNLINKED_SAMPLE_LIMIT = 10;
+/**
+ * Stable, path-safe workspace hash for snapshotId (SPEC §13): never exposes the
+ * raw path and is never persisted. Windows normalization: backslashes become
+ * forward slashes and the drive letter is case-folded, so `D:\a\b`, `d:/a/b/`
+ * and `D:/a/b` hash identically. POSIX path case is intentionally preserved.
+ */
+export function hashWorkspacePath(workspaceDir) {
+    const resolved = path.resolve(workspaceDir).replace(/\\/g, '/').replace(/\/+$/, '');
+    const normalized = resolved.replace(/([A-Za-z]):/, (match, _drive) => match.toUpperCase());
+    return createHash('sha256').update(normalized).digest('hex').slice(0, 16);
+}
+export class GovernanceExperienceCollector {
+    workspaceDir;
+    constructor(workspaceDir) {
+        this.workspaceDir = workspaceDir;
+    }
+    collectSnapshot(options) {
+        return deriveGovernanceExperienceSnapshot(this.buildInputs(options));
+    }
+    buildInputs(options) {
+        const asOf = options.asOf ?? new Date().toISOString();
+        const sourceAvailability = [];
+        const dataQualityInputs = [];
+        // ── Principle ledger: read once, validate every entry ────────────────────
+        const ledger = this.scanLedger();
+        sourceAvailability.push({
+            sourceId: 'principle_ledger',
+            available: ledger.available,
+            ...(ledger.reasonCode !== undefined ? { reasonCode: ledger.reasonCode } : {}),
+        });
+        if (ledger.invalidPrincipleRefs.length > 0) {
+            dataQualityInputs.push({
+                source: 'principle',
+                reasonCode: 'principle_ledger_entry_invalid',
+                count: ledger.invalidPrincipleRefs.length,
+                sampleRefs: ledger.invalidPrincipleRefs.slice(0, UNLINKED_SAMPLE_LIMIT),
+            });
+        }
+        // ── state.db: existence check + one batched table read ───────────────────
+        const dbPath = path.join(this.workspaceDir, '.pd', 'state.db');
+        let tables = EMPTY_TABLES;
+        let stateDbAvailable = true;
+        let stateDbReasonCode;
+        if (!fs.existsSync(dbPath)) {
+            stateDbAvailable = false;
+            stateDbReasonCode = 'state_db_missing';
+        }
+        else {
+            try {
+                tables = (options.tableReader ?? GovernanceProjectionCollector.readTables)(this.workspaceDir);
+            }
+            catch {
+                stateDbAvailable = false;
+                stateDbReasonCode = 'state_db_read_failed';
+                tables = EMPTY_TABLES;
+            }
+        }
+        sourceAvailability.push({
+            sourceId: 'state_db',
+            available: stateDbAvailable,
+            ...(stateDbReasonCode !== undefined ? { reasonCode: stateDbReasonCode } : {}),
+        });
+        // ── Views: reuse the existing projection per principle, in memory ────────
+        const views = [];
+        const claimedTaskIds = new Set();
+        const principleIds = [...ledger.facts.keys()].sort();
+        for (const principleId of principleIds) {
+            const principle = ledger.facts.get(principleId);
+            if (principle === undefined)
+                continue;
+            const issues = [...(ledger.issuesByPrinciple.get(principleId) ?? [])];
+            try {
+                // state.db unavailable mirrors collect()'s degraded facts shape exactly
+                const facts = stateDbAvailable
+                    ? GovernanceProjectionCollector.buildFacts({ principleId, asOf, principle, tables, collectionIssues: issues })
+                    : GovernanceProjectionCollector.factsForUnavailableSource({ principleId, asOf, principle, collectionIssues: issues });
+                for (const task of facts.tasks) {
+                    if (task.taskId !== undefined)
+                        claimedTaskIds.add(task.taskId);
+                }
+                views.push({ view: deriveOwnerGovernanceView(facts), lineageConfidence: facts.lineage.confidence });
+            }
+            catch {
+                // A principle whose facts/view fail validation never blocks the snapshot;
+                // it surfaces as a bounded data-quality group (fail loud, keep going).
+                dataQualityInputs.push({
+                    source: 'principle',
+                    reasonCode: 'projection_derivation_failed',
+                    count: 1,
+                    sampleRefs: [{ type: 'principle', id: principleId }],
+                });
+            }
+        }
+        // ── Linkage indexes + evidence + unlinked records (same batched rows) ────
+        const parsedTasks = [];
+        const parseIssues = []; // malformed rows are attributed per-principle by buildFacts; not double-counted here
+        if (stateDbAvailable) {
+            for (const row of tables.taskRows) {
+                const parsed = GovernanceProjectionCollector.parseTaskRow(row, parseIssues);
+                if (parsed !== null)
+                    parsedTasks.push(parsed);
+            }
+        }
+        // SPEC §9: unlinked records never enter activity classification. Evidence
+        // counts require an established relationship: a task must have produced an
+        // artifact row (task↔artifact), a RuleCode decision's artifact must exist
+        // AND belong to a principle present in the ledger (artifact↔principle).
+        const artifactIds = new Set();
+        const taskIdsWithArtifact = new Set();
+        const artifactOwnerKnown = new Map();
+        if (stateDbAvailable) {
+            for (const row of tables.artifactRows) {
+                if (!isRecord(row))
+                    continue;
+                const artifactId = readOwnString(row, 'artifact_id');
+                if (artifactId === undefined)
+                    continue;
+                artifactIds.add(artifactId);
+                const sourceTaskId = readOwnString(row, 'source_task_id');
+                if (sourceTaskId !== undefined)
+                    taskIdsWithArtifact.add(sourceTaskId);
+                const sourcePrincipleId = readOwnString(row, 'source_principle_id');
+                artifactOwnerKnown.set(artifactId, sourcePrincipleId !== undefined && ledger.available && ledger.presentPrincipleIds.has(sourcePrincipleId));
+            }
+        }
+        const activeTasks = stateDbAvailable
+            ? parsedTasks.filter(task => task.status !== 'succeeded' && taskIdsWithArtifact.has(task.taskId))
+            : [];
+        // RuleCode owner decisions awaiting action (SPEC §8.3 source): non-deactivated
+        // shadow activations with verified linkage; unlinked ones degrade to data
+        // quality instead of inflating the decision count.
+        const rulecodePendingRefs = [];
+        let rulecodePendingCount = 0;
+        const unlinkedRulecodeRefs = [];
+        let unlinkedRulecodeCount = 0;
+        if (stateDbAvailable) {
+            for (const row of tables.activationRows) {
+                if (!isRecord(row))
+                    continue;
+                const action = readOwnString(row, 'action');
+                const deactivatedAt = readOwnString(row, 'deactivated_at');
+                if (action !== 'code_tool_hook_shadow_activate' || deactivatedAt !== undefined)
+                    continue;
+                const artifactId = readOwnString(row, 'artifact_id');
+                const activationId = readOwnString(row, 'activation_id');
+                const ref = activationId === undefined ? undefined : { type: 'activation', id: activationId };
+                if (artifactId !== undefined && artifactOwnerKnown.get(artifactId) === true) {
+                    rulecodePendingCount += 1;
+                    if (ref !== undefined && rulecodePendingRefs.length < UNLINKED_SAMPLE_LIMIT)
+                        rulecodePendingRefs.push(ref);
+                }
+                else {
+                    unlinkedRulecodeCount += 1;
+                    if (ref !== undefined && unlinkedRulecodeRefs.length < UNLINKED_SAMPLE_LIMIT)
+                        unlinkedRulecodeRefs.push(ref);
+                }
+            }
+        }
+        if (unlinkedRulecodeCount > 0) {
+            dataQualityInputs.push({ source: 'activation', reasonCode: 'unlinked_record', count: unlinkedRulecodeCount, sampleRefs: unlinkedRulecodeRefs });
+        }
+        if (stateDbAvailable) {
+            const unlinkedApprovalRefs = [];
+            let unlinkedApprovalCount = 0;
+            for (const row of tables.approvalRows) {
+                if (!isRecord(row))
+                    continue;
+                const artifactId = readOwnString(row, 'artifact_id');
+                const approvalId = readOwnString(row, 'approval_id');
+                if (artifactId !== undefined && !artifactIds.has(artifactId)) {
+                    unlinkedApprovalCount += 1;
+                    if (approvalId !== undefined && unlinkedApprovalRefs.length < UNLINKED_SAMPLE_LIMIT) {
+                        unlinkedApprovalRefs.push({ type: 'approval', id: approvalId });
+                    }
+                }
+            }
+            if (unlinkedApprovalCount > 0) {
+                dataQualityInputs.push({ source: 'approval', reasonCode: 'unlinked_record', count: unlinkedApprovalCount, sampleRefs: unlinkedApprovalRefs });
+            }
+            if (ledger.available) {
+                const unlinkedArtifactRefs = [];
+                let unlinkedArtifactCount = 0;
+                for (const row of tables.artifactRows) {
+                    if (!isRecord(row))
+                        continue;
+                    const sourcePrincipleId = readOwnString(row, 'source_principle_id');
+                    const artifactId = readOwnString(row, 'artifact_id');
+                    if (sourcePrincipleId !== undefined && !ledger.presentPrincipleIds.has(sourcePrincipleId)) {
+                        unlinkedArtifactCount += 1;
+                        if (artifactId !== undefined && unlinkedArtifactRefs.length < UNLINKED_SAMPLE_LIMIT) {
+                            unlinkedArtifactRefs.push({ type: 'artifact', id: artifactId });
+                        }
+                    }
+                }
+                if (unlinkedArtifactCount > 0) {
+                    dataQualityInputs.push({ source: 'artifact', reasonCode: 'unlinked_record', count: unlinkedArtifactCount, sampleRefs: unlinkedArtifactRefs });
+                }
+            }
+            const unlinkedTaskRefs = [];
+            let unlinkedTaskCount = 0;
+            for (const task of parsedTasks) {
+                if (claimedTaskIds.has(task.taskId))
+                    continue;
+                unlinkedTaskCount += 1;
+                if (unlinkedTaskRefs.length < UNLINKED_SAMPLE_LIMIT)
+                    unlinkedTaskRefs.push({ type: 'task', id: task.taskId });
+            }
+            if (unlinkedTaskCount > 0) {
+                dataQualityInputs.push({ source: 'task', reasonCode: 'unlinked_record', count: unlinkedTaskCount, sampleRefs: unlinkedTaskRefs });
+            }
+        }
+        // ── Workspace config environment (PRI-587) via the unified validator ─────
+        const configResult = loadPdConfig(this.workspaceDir);
+        const environment = configResult.ok ? configResult.effective.config.workspace?.environment : undefined;
+        const environmentContext = configResult.ok
+            ? environment !== undefined
+                ? { environment, source: 'workspace_config' }
+                : { environment: 'unknown', source: 'missing' }
+            : { environment: 'unknown', source: 'missing', configIssue: 'config_invalid' };
+        return {
+            schemaVersion: '1',
+            asOf,
+            workspaceHash: hashWorkspacePath(this.workspaceDir),
+            governanceViews: views,
+            ownerConfigSnapshot: options.ownerConfig,
+            environmentContext,
+            sourceAvailability,
+            dataQualityInputs,
+            ...(stateDbAvailable
+                ? {
+                    frontierEvidence: { sourceId: 'state_db', activeTaskCount: activeTasks.length, sampleRefs: activeTasks.slice(0, UNLINKED_SAMPLE_LIMIT).map(task => ({ type: 'task', id: task.taskId })) },
+                    rulecodeDecisionEvidence: { pendingCount: rulecodePendingCount, sampleRefs: rulecodePendingRefs },
+                }
+                : {}),
+        };
+    }
+    /**
+     * Reads the principle ledger once and validates every entry. A readable file
+     * with a malformed tree counts as an unavailable ledger source (no views can
+     * be built); individual invalid entries degrade to data-quality groups.
+     */
+    scanLedger() {
+        const scan = {
+            available: true,
+            presentPrincipleIds: new Set(),
+            facts: new Map(),
+            issuesByPrinciple: new Map(),
+            invalidPrincipleRefs: [],
+        };
+        let parsed;
+        try {
+            parsed = GovernanceProjectionCollector.parsePrincipleLedgerFile(this.workspaceDir);
+        }
+        catch {
+            scan.available = false;
+            scan.reasonCode = 'ledger_unreadable';
+            return scan;
+        }
+        if (!isRecord(parsed)) {
+            scan.available = false;
+            scan.reasonCode = 'ledger_tree_malformed';
+            return scan;
+        }
+        const principlesTree = GovernanceProjectionCollector.principleTreeFromLedger(parsed);
+        if (principlesTree === null) {
+            scan.available = false;
+            scan.reasonCode = 'ledger_tree_malformed';
+            return scan;
+        }
+        for (const principleId of Object.keys(principlesTree).sort()) {
+            scan.presentPrincipleIds.add(principleId);
+            const issues = [];
+            try {
+                const fact = GovernanceProjectionCollector.principleFactFromLedger(parsed, principleId, issues);
+                scan.facts.set(principleId, fact);
+                scan.issuesByPrinciple.set(principleId, issues);
+            }
+            catch {
+                scan.invalidPrincipleRefs.push({ type: 'principle', id: principleId });
+            }
+        }
+        return scan;
+    }
+}

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

@@ -1,16 +1,74 @@
-import type { GovernanceFacts } from '@principles/core/runtime-v2';
+import type Database from 'better-sqlite3';
+import type { DataQualityIssue, GovernanceFacts, GovernanceChannel, RevisionIdentity, RunnerVerdictFact, TaskFact } from '@principles/core/runtime-v2';
+export declare const GOVERNANCE_TASK_KINDS: Set<string>;
+export declare const GOVERNANCE_TASK_STATUSES: Set<string>;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function readOwnString(record: Record<string, unknown>, key: string): string | undefined;
 export declare class GovernanceProjectionCollectionError extends Error {
     readonly reasonCode: 'principle_not_found' | 'governance_projection_error';
     readonly nextActionCode: string;
     constructor(reasonCode: 'principle_not_found' | 'governance_projection_error', nextActionCode: string);
 }
+export interface ValidTaskRow {
+    taskId: string;
+    taskKind: TaskFact['taskKind'];
+    status: TaskFact['status'];
+    createdAt: string;
+    updatedAt: string;
+    leaseExpiresAt?: string;
+    attemptCount: number;
+    maxAttempts: number;
+    lastErrorCategory?: TaskFact['lastErrorCategory'];
+    channel: GovernanceChannel;
+    dependencyTaskIds: string[];
+    revisionIdentity?: RevisionIdentity;
+    completionIntent?: TaskFact['completionIntent'];
+    runnerDecision?: RunnerVerdictFact['outcome'];
+}
+/**
+ * Raw rows for the four tables the projection reads. Populated once per
+ * workspace by `readTables` and grouped per principle in memory by
+ * `buildFacts` — the batch experience collector (PRI-585) reuses the same
+ * rows so a workspace snapshot costs 4 queries total, not 4 per principle.
+ */
+export interface GovernanceProjectionTables {
+    artifactRows: unknown[];
+    taskRows: unknown[];
+    approvalRows: unknown[];
+    activationRows: unknown[];
+}
 export declare class GovernanceProjectionCollector {
     private readonly workspaceDir;
     constructor(workspaceDir: string);
     collect(principleId: string, asOf: string): Promise<GovernanceFacts>;
+    /** Degraded facts shape used when state.db is unavailable (shared by single + batch collectors). */
+    static factsForUnavailableSource(input: {
+        principleId: string;
+        asOf: string;
+        principle: GovernanceFacts['principle'];
+        collectionIssues: DataQualityIssue[];
+    }): GovernanceFacts;
+    /** Reads the four projection tables once. Closes its own connection unless one is injected (caller then owns closing). */
+    static readTables(workspaceDir: string, injected?: {
+        getDb(): Database.Database;
+    }): GovernanceProjectionTables;
+    /** Groups pre-fetched raw rows into GovernanceFacts for ONE principle. Pure in-memory. */
+    static buildFacts(input: {
+        principleId: string;
+        asOf: string;
+        principle: GovernanceFacts['principle'];
+        tables: GovernanceProjectionTables;
+        collectionIssues: DataQualityIssue[];
+    }): GovernanceFacts;
     private readPrinciple;
+    /** Reads and JSON-parses the principle ledger file (shared by single + batch collectors). */
+    static parsePrincipleLedgerFile(workspaceDir: string): unknown;
+    /** Extracts the principles record from a parsed ledger; null when the tree is absent/malformed. */
+    static principleTreeFromLedger(parsed: unknown): Record<string, unknown> | null;
+    /** Validates one principle entry from an already-parsed ledger (shared by single + batch collectors). */
+    static principleFactFromLedger(parsed: unknown, principleId: string, issues: DataQualityIssue[]): GovernanceFacts['principle'];
     private static parseStringArrayJson;
-    private static parseTaskRow;
+    static parseTaskRow(row: unknown, issues: DataQualityIssue[]): ValidTaskRow | null;
     private static connectedTaskIds;
     private static finish;
 }