create-principles-disciple 1.114.0 → 1.115.0

package/console/dist/server/index.js

@@ -209,9 +209,11 @@ async function initServices(workspaceDir, authConfig) {
     const pdFlags = computeFlagsFromLoadResult(configResult);
     const feedbackChannelEnabled = pdFlags.flags.feedback_channel?.enabled ?? false;
     const failedTasksObservabilityEnabled = pdFlags.flags.failed_tasks_observability?.enabled ?? true;
+    const governanceProjectionEnabled = pdFlags.flags.principle_governance_projection_v2?.enabled ?? false;
     const feedbackFlags = {
         feedback_channel: { enabled: feedbackChannelEnabled },
         failed_tasks_observability: { enabled: failedTasksObservabilityEnabled },
+        principle_governance_projection_v2: { enabled: governanceProjectionEnabled },
     };
     if (!configResult.ok) {
         console.warn('[pd-console] PD config loading failed (using defaults for feedback channel):', configResult.errors.map(e => e.reason).join('; '));
@@ -322,6 +324,12 @@ function handleRequest(services) {
                 asyncHandler(() => handlePrinciplesRoute({ req, res, workspaceDir: services.workspaceDir, subPath }))(req, res);
                 return;
             }
+            // GET /api/v1/principles/:id/governance
+            if (urlPath.startsWith('/api/v1/principles/')) {
+                const subPath = urlPath.slice('/api/v1/principles'.length);
+                asyncHandler(() => handlePrinciplesRoute({ req, res, workspaceDir: services.workspaceDir, subPath, featureFlags: services.feedbackFlags }))(req, res);
+                return;
+            }
             // Workspace management routes
             if (urlPath === '/api/workspaces' || urlPath.startsWith('/api/workspaces/')) {
                 const subPath = urlPath.slice('/api/workspaces'.length);

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

@@ -0,0 +1,16 @@
+import type { GovernanceFacts } from '@principles/core/runtime-v2';
+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 declare class GovernanceProjectionCollector {
+    private readonly workspaceDir;
+    constructor(workspaceDir: string);
+    collect(principleId: string, asOf: string): Promise<GovernanceFacts>;
+    private readPrinciple;
+    private static parseStringArrayJson;
+    private static parseTaskRow;
+    private static connectedTaskIds;
+    private static finish;
+}

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

@@ -0,0 +1,540 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { Value } from '@sinclair/typebox/value';
+import { GovernanceFactsSchema, SqliteConnection, isPDErrorCategory, parsePITaskMetadata, } from '@principles/core/runtime-v2';
+const GOVERNANCE_TASK_KINDS = new Set([
+    'dreamer', 'philosopher', 'scribe', 'artificer', 'evaluator', 'rollout_reviewer',
+]);
+const GOVERNANCE_TASK_STATUSES = new Set([
+    'pending', 'leased', 'succeeded', 'retry_wait', 'failed', 'needs_human_review',
+]);
+const PRINCIPLE_STATES = new Set(['candidate', 'active', 'archived', 'deprecated', 'probation']);
+const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+const MAX_LINEAGE_NODES = 500;
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function readOwnString(record, key) {
+    if (!Object.hasOwn(record, key))
+        return undefined;
+    const value = record[key];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function isTimestamp(value) {
+    if (value === undefined || !ISO_UTC.test(value))
+        return false;
+    const parsed = new Date(value);
+    if (!Number.isFinite(parsed.getTime()))
+        return false;
+    return parsed.toISOString() === (value.includes('.') ? value : value.replace('Z', '.000Z'));
+}
+function isGovernanceChannel(value) {
+    return value === 'prompt' || value === 'code_tool_hook' || value === 'defer_archive';
+}
+function issue(value) {
+    return value;
+}
+export class GovernanceProjectionCollectionError extends Error {
+    reasonCode;
+    nextActionCode;
+    constructor(reasonCode, nextActionCode) {
+        super(reasonCode);
+        this.reasonCode = reasonCode;
+        this.nextActionCode = nextActionCode;
+        this.name = 'GovernanceProjectionCollectionError';
+    }
+}
+export class GovernanceProjectionCollector {
+    workspaceDir;
+    constructor(workspaceDir) {
+        this.workspaceDir = workspaceDir;
+    }
+    async collect(principleId, asOf) {
+        if (principleId.length === 0 || !isTimestamp(asOf)) {
+            throw new GovernanceProjectionCollectionError('governance_projection_error', 'check_request_parameters');
+        }
+        const collectionIssues = [];
+        const principle = this.readPrinciple(principleId, collectionIssues);
+        const dbPath = path.join(this.workspaceDir, '.pd', 'state.db');
+        if (!fs.existsSync(dbPath)) {
+            collectionIssues.push(issue({ source: 'lineage', reasonCode: 'source_unavailable', nextActionCode: 'initialize_runtime_state' }));
+            return GovernanceProjectionCollector.finish({ principleId, asOf, principle, collectionIssues });
+        }
+        const connection = new SqliteConnection({ workspaceDir: this.workspaceDir, readonly: true });
+        try {
+            const db = connection.getDb();
+            const artifactIds = [];
+            const rootTaskIds = [];
+            const sourceRefs = [{ type: 'principle', id: principleId }];
+            const artifactRows = db.prepare(`
+        SELECT artifact_id, source_task_id, source_principle_id, lineage_artifact_ids, updated_at
+        FROM pi_artifacts ORDER BY artifact_id ASC
+      `).all();
+            const validArtifacts = new Map();
+            for (const row of artifactRows) {
+                if (!isRecord(row)) {
+                    collectionIssues.push(issue({ source: 'artifact', reasonCode: 'metadata_malformed', nextActionCode: 'repair_artifact_metadata' }));
+                    continue;
+                }
+                const artifactId = readOwnString(row, 'artifact_id');
+                const sourceTaskId = readOwnString(row, 'source_task_id');
+                const sourcePrincipleId = readOwnString(row, 'source_principle_id');
+                const updatedAt = readOwnString(row, 'updated_at');
+                const lineageJson = readOwnString(row, 'lineage_artifact_ids');
+                const lineageArtifactIds = GovernanceProjectionCollector.parseStringArrayJson(lineageJson);
+                const artifactRef = artifactId === undefined ? undefined : { type: 'artifact', id: artifactId };
+                if (artifactId === undefined || sourceTaskId === undefined || !isTimestamp(updatedAt)
+                    || lineageArtifactIds === null) {
+                    if (sourcePrincipleId === principleId) {
+                        collectionIssues.push(issue(artifactRef === undefined
+                            ? { source: 'artifact', reasonCode: 'metadata_malformed', nextActionCode: 'repair_artifact_metadata' }
+                            : { source: 'artifact', reasonCode: 'metadata_malformed', nextActionCode: 'repair_artifact_metadata', sourceRef: artifactRef }));
+                    }
+                    continue;
+                }
+                validArtifacts.set(artifactId, {
+                    artifactId, sourceTaskId, lineageArtifactIds,
+                    ...(sourcePrincipleId === undefined ? {} : { sourcePrincipleId }),
+                });
+            }
+            const strongArtifactIds = new Set([...validArtifacts.values()].filter(row => row.sourcePrincipleId === principleId).map(row => row.artifactId));
+            let addedArtifact = true;
+            while (addedArtifact) {
+                addedArtifact = false;
+                for (const row of validArtifacts.values()) {
+                    if (!strongArtifactIds.has(row.artifactId) && row.lineageArtifactIds.some(id => strongArtifactIds.has(id))) {
+                        strongArtifactIds.add(row.artifactId);
+                        addedArtifact = true;
+                    }
+                }
+            }
+            for (const artifactId of [...strongArtifactIds].sort()) {
+                const artifact = validArtifacts.get(artifactId);
+                if (artifact === undefined)
+                    continue;
+                artifactIds.push(artifactId);
+                rootTaskIds.push(artifact.sourceTaskId);
+                sourceRefs.push({ type: 'artifact', id: artifactId });
+            }
+            if (artifactIds.length === 0) {
+                collectionIssues.push(issue({ source: 'lineage', reasonCode: 'lineage_not_available', nextActionCode: 'wait_for_durable_lineage' }));
+                return GovernanceProjectionCollector.finish({ principleId, asOf, principle, collectionIssues });
+            }
+            const validTasks = new Map();
+            const taskRowIssues = [];
+            const taskRows = db.prepare('SELECT * FROM tasks ORDER BY task_id ASC').all();
+            for (const row of taskRows) {
+                const parsed = GovernanceProjectionCollector.parseTaskRow(row, taskRowIssues);
+                if (parsed !== null)
+                    validTasks.set(parsed.taskId, parsed);
+            }
+            const connected = GovernanceProjectionCollector.connectedTaskIds(rootTaskIds, validTasks, collectionIssues);
+            const taskLineageConfidence = collectionIssues.some(item => item.reasonCode === 'lineage_cycle' || item.reasonCode === 'lineage_limit_exceeded') ? 'weak' : 'strong';
+            for (const taskIssue of taskRowIssues) {
+                if (taskIssue.sourceRef?.type === 'task' && connected.has(taskIssue.sourceRef.id)) {
+                    collectionIssues.push(taskIssue);
+                }
+            }
+            const tasks = [];
+            const runnerVerdicts = [];
+            const derivedRelations = [];
+            const revisionIdentities = [];
+            const timelineEvents = [];
+            const materializedRevisionSources = new Set();
+            for (const taskId of connected) {
+                const task = validTasks.get(taskId);
+                if (task === undefined) {
+                    collectionIssues.push(issue({ source: 'task', reasonCode: 'metadata_malformed', nextActionCode: 'repair_task_metadata', sourceRef: { type: 'task', id: taskId } }));
+                    continue;
+                }
+                if (task.revisionIdentity !== undefined) {
+                    const identity = task.revisionIdentity;
+                    const sourceTaskId = identity.kind === 'evaluator_repair'
+                        ? identity.sourceEvaluatorTaskId
+                        : identity.kind === 'rollout_reopen' ? identity.sourceRolloutTaskId : undefined;
+                    const sourceArtifactId = identity.kind === 'evaluator_repair'
+                        ? identity.sourceArtificerArtifactId
+                        : identity.kind === 'rollout_reopen' ? identity.sourceArtifactId : undefined;
+                    if (sourceTaskId === undefined || sourceArtifactId === undefined
+                        || !connected.has(sourceTaskId) || !strongArtifactIds.has(sourceArtifactId)) {
+                        collectionIssues.push(issue({
+                            source: 'lineage', reasonCode: 'lineage_conflict', nextActionCode: 'repair_revision_lineage',
+                            sourceRef: { type: 'task', id: task.taskId },
+                        }));
+                        continue;
+                    }
+                    revisionIdentities.push(identity);
+                    materializedRevisionSources.add(sourceTaskId);
+                    derivedRelations.push({
+                        schemaVersion: '1', family: 'derived_relation', sourceRef: { type: 'task', id: task.taskId }, principleId,
+                        taskId: task.taskId, lineageConfidence: taskLineageConfidence, recordedAt: task.updatedAt,
+                        revisionIdentity: identity, relation: 'revision_materialized',
+                        evidenceRefs: [
+                            { type: 'task', id: sourceTaskId },
+                            { type: 'artifact', id: sourceArtifactId },
+                            { type: 'task', id: task.taskId },
+                        ],
+                    });
+                    timelineEvents.push({
+                        code: 'revision_reopened', occurredAt: task.createdAt, recordedAt: task.updatedAt,
+                        summaryCode: 'governance.timeline.revision_reopened', sourceRef: { type: 'task', id: task.taskId },
+                        lineageConfidence: taskLineageConfidence,
+                    });
+                }
+                const fact = {
+                    schemaVersion: '1', family: 'task', sourceRef: { type: 'task', id: task.taskId }, principleId,
+                    taskId: task.taskId, lineageConfidence: taskLineageConfidence, recordedAt: task.updatedAt,
+                    occurredAt: task.createdAt, taskKind: task.taskKind, channel: task.channel, status: task.status,
+                    attemptCount: task.attemptCount, maxAttempts: task.maxAttempts,
+                };
+                if (task.leaseExpiresAt !== undefined)
+                    fact.leaseExpiresAt = task.leaseExpiresAt;
+                if (task.lastErrorCategory !== undefined)
+                    fact.lastErrorCategory = task.lastErrorCategory;
+                if (task.revisionIdentity !== undefined) {
+                    fact.revisionIdentity = task.revisionIdentity;
+                }
+                if (task.completionIntent !== undefined)
+                    fact.completionIntent = task.completionIntent;
+                tasks.push(fact);
+                sourceRefs.push(fact.sourceRef);
+                if ((task.taskKind === 'evaluator' || task.taskKind === 'rollout_reviewer') && task.runnerDecision !== undefined) {
+                    runnerVerdicts.push({
+                        schemaVersion: '1', family: 'runner_verdict', sourceRef: fact.sourceRef, principleId,
+                        taskId: task.taskId, lineageConfidence: taskLineageConfidence, recordedAt: task.updatedAt,
+                        runnerKind: task.taskKind, outcome: task.runnerDecision,
+                    });
+                    timelineEvents.push({
+                        code: 'review_started', occurredAt: task.createdAt, recordedAt: task.updatedAt,
+                        summaryCode: 'governance.timeline.review_started', sourceRef: fact.sourceRef, lineageConfidence: taskLineageConfidence,
+                    });
+                    if (task.runnerDecision === 'needs_revision') {
+                        timelineEvents.push({
+                            code: 'revision_requested', occurredAt: task.updatedAt, recordedAt: task.updatedAt,
+                            summaryCode: 'governance.timeline.revision_requested', sourceRef: fact.sourceRef, lineageConfidence: taskLineageConfidence,
+                        });
+                    }
+                }
+                else if ((task.taskKind === 'evaluator' || task.taskKind === 'rollout_reviewer') && task.status === 'succeeded') {
+                    derivedRelations.push({
+                        schemaVersion: '1', family: 'derived_relation', sourceRef: fact.sourceRef, principleId,
+                        taskId: task.taskId, lineageConfidence: taskLineageConfidence, recordedAt: task.updatedAt,
+                        relation: 'verdict_missing', evidenceRefs: [fact.sourceRef],
+                    });
+                }
+                if (task.status === 'failed' || task.status === 'needs_human_review') {
+                    const code = task.status === 'failed' ? 'failed' : 'human_review';
+                    timelineEvents.push({
+                        code, occurredAt: task.updatedAt, recordedAt: task.updatedAt,
+                        summaryCode: `governance.timeline.${code}`, sourceRef: fact.sourceRef, lineageConfidence: taskLineageConfidence,
+                    });
+                }
+            }
+            tasks.sort((left, right) => (left.taskId ?? '').localeCompare(right.taskId ?? ''));
+            const strongTaskIds = new Set(tasks.filter(task => task.lineageConfidence === 'strong').map(task => task.taskId).filter((taskId) => taskId !== undefined));
+            for (const task of tasks) {
+                const { taskId } = task;
+                if (taskId === undefined || task.completionIntent?.status !== 'pending' || materializedRevisionSources.has(taskId))
+                    continue;
+                derivedRelations.push({
+                    schemaVersion: '1', family: 'derived_relation', sourceRef: task.sourceRef, principleId,
+                    taskId, lineageConfidence: 'strong', recordedAt: task.recordedAt,
+                    relation: 'revision_pending', evidenceRefs: [task.sourceRef],
+                });
+            }
+            for (const successor of [...validTasks.values()].sort((left, right) => left.taskId.localeCompare(right.taskId))) {
+                if (!strongTaskIds.has(successor.taskId))
+                    continue;
+                for (const dependencyTaskId of [...successor.dependencyTaskIds].sort()) {
+                    if (!strongTaskIds.has(dependencyTaskId))
+                        continue;
+                    derivedRelations.push({
+                        schemaVersion: '1', family: 'derived_relation', sourceRef: { type: 'task', id: dependencyTaskId }, principleId,
+                        taskId: dependencyTaskId, lineageConfidence: 'strong', recordedAt: successor.updatedAt,
+                        relation: 'successor_present',
+                        evidenceRefs: [{ type: 'task', id: dependencyTaskId }, { type: 'task', id: successor.taskId }],
+                    });
+                }
+            }
+            const approvals = [];
+            const activations = [];
+            for (const row of db.prepare('SELECT * FROM approvals ORDER BY approval_id ASC').all()) {
+                if (!isRecord(row))
+                    continue;
+                const artifactId = readOwnString(row, 'artifact_id');
+                if (artifactId === undefined || !strongArtifactIds.has(artifactId))
+                    continue;
+                const approvalId = readOwnString(row, 'approval_id');
+                const channel = readOwnString(row, 'channel');
+                const outcome = readOwnString(row, 'status');
+                const requestedAt = readOwnString(row, 'requested_at');
+                const decidedAt = readOwnString(row, 'decided_at');
+                const approvalRef = approvalId === undefined ? undefined : { type: 'approval', id: approvalId };
+                if (approvalId === undefined || !isGovernanceChannel(channel) || !isTimestamp(requestedAt)
+                    || (outcome !== 'pending' && outcome !== 'approved' && outcome !== 'rejected' && outcome !== 'cancelled')
+                    || (decidedAt !== undefined && !isTimestamp(decidedAt))) {
+                    collectionIssues.push(issue(approvalRef === undefined
+                        ? { source: 'approval', reasonCode: 'metadata_malformed', nextActionCode: 'repair_approval_record' }
+                        : { source: 'approval', reasonCode: 'metadata_malformed', nextActionCode: 'repair_approval_record', sourceRef: approvalRef }));
+                    continue;
+                }
+                const strongApprovalRef = { type: 'approval', id: approvalId };
+                const fact = {
+                    schemaVersion: '1', family: 'approval', sourceRef: strongApprovalRef, principleId, artifactId,
+                    approvalId, channel, outcome, lineageConfidence: 'strong', recordedAt: decidedAt ?? requestedAt,
+                };
+                if (decidedAt !== undefined)
+                    fact.occurredAt = decidedAt;
+                approvals.push(fact);
+                sourceRefs.push(strongApprovalRef);
+                if (outcome === 'approved' || outcome === 'rejected') {
+                    timelineEvents.push({
+                        code: outcome, occurredAt: decidedAt ?? requestedAt, recordedAt: decidedAt ?? requestedAt,
+                        summaryCode: `governance.timeline.${outcome}`, sourceRef: strongApprovalRef, lineageConfidence: 'strong',
+                    });
+                }
+            }
+            for (const row of db.prepare('SELECT * FROM activations ORDER BY activated_at ASC, activation_id ASC').all()) {
+                if (!isRecord(row))
+                    continue;
+                const artifactId = readOwnString(row, 'artifact_id');
+                if (artifactId === undefined || !strongArtifactIds.has(artifactId))
+                    continue;
+                const activationId = readOwnString(row, 'activation_id');
+                const channel = readOwnString(row, 'channel');
+                const activatedAt = readOwnString(row, 'activated_at');
+                const deactivatedAt = readOwnString(row, 'deactivated_at');
+                const activationRef = activationId === undefined ? undefined : { type: 'activation', id: activationId };
+                if (activationId === undefined || !isGovernanceChannel(channel) || !isTimestamp(activatedAt)
+                    || (deactivatedAt !== undefined && !isTimestamp(deactivatedAt))) {
+                    collectionIssues.push(issue(activationRef === undefined
+                        ? { source: 'activation', reasonCode: 'metadata_malformed', nextActionCode: 'repair_activation_record' }
+                        : { source: 'activation', reasonCode: 'metadata_malformed', nextActionCode: 'repair_activation_record', sourceRef: activationRef }));
+                    continue;
+                }
+                const strongActivationRef = { type: 'activation', id: activationId };
+                const fact = {
+                    schemaVersion: '1', family: 'activation', sourceRef: strongActivationRef, principleId, artifactId,
+                    activationId, channel, outcome: deactivatedAt === undefined ? 'active' : 'deactivated',
+                    activatedAt, lineageConfidence: 'strong', recordedAt: deactivatedAt ?? activatedAt,
+                };
+                if (deactivatedAt !== undefined)
+                    fact.deactivatedAt = deactivatedAt;
+                activations.push(fact);
+                sourceRefs.push(strongActivationRef);
+                timelineEvents.push({ code: 'activated', occurredAt: activatedAt, recordedAt: activatedAt, summaryCode: 'governance.timeline.activated', sourceRef: strongActivationRef, lineageConfidence: 'strong' });
+                if (deactivatedAt !== undefined) {
+                    timelineEvents.push({ code: 'deactivated', occurredAt: deactivatedAt, recordedAt: deactivatedAt, summaryCode: 'governance.timeline.deactivated', sourceRef: strongActivationRef, lineageConfidence: 'strong' });
+                }
+            }
+            timelineEvents.sort((left, right) => {
+                const timeOrder = (left.occurredAt ?? left.recordedAt).localeCompare(right.occurredAt ?? right.recordedAt);
+                if (timeOrder !== 0)
+                    return timeOrder;
+                const typeOrder = left.sourceRef.type.localeCompare(right.sourceRef.type);
+                if (typeOrder !== 0)
+                    return typeOrder;
+                const idOrder = left.sourceRef.id.localeCompare(right.sourceRef.id);
+                return idOrder !== 0 ? idOrder : left.code.localeCompare(right.code);
+            });
+            return GovernanceProjectionCollector.finish({
+                principleId, asOf, principle, collectionIssues, artifactIds,
+                taskIds: tasks.map(task => task.taskId).filter((taskId) => taskId !== undefined).sort(), tasks, revisionIdentities, sourceRefs,
+                runnerVerdicts, derivedRelations, approvals, activations, timelineEvents,
+            });
+        }
+        catch (error) {
+            if (error instanceof GovernanceProjectionCollectionError)
+                throw error;
+            throw new GovernanceProjectionCollectionError('governance_projection_error', 'inspect_runtime_state');
+        }
+        finally {
+            connection.close();
+        }
+    }
+    readPrinciple(principleId, issues) {
+        const ledgerPath = path.join(this.workspaceDir, '.state', 'principle_training_state.json');
+        let parsed;
+        try {
+            parsed = JSON.parse(fs.readFileSync(ledgerPath, 'utf8'));
+        }
+        catch {
+            throw new GovernanceProjectionCollectionError('principle_not_found', 'check_principle_ledger');
+        }
+        if (!isRecord(parsed))
+            throw new GovernanceProjectionCollectionError('principle_not_found', 'check_principle_ledger');
+        const tree = Object.hasOwn(parsed, '_tree') ? parsed._tree : parsed.tree;
+        if (!isRecord(tree) || !isRecord(tree.principles) || !Object.hasOwn(tree.principles, principleId)) {
+            throw new GovernanceProjectionCollectionError('principle_not_found', 'check_principle_id');
+        }
+        const raw = tree.principles[principleId];
+        if (!isRecord(raw))
+            throw new GovernanceProjectionCollectionError('principle_not_found', 'repair_principle_ledger');
+        const state = readOwnString(raw, 'status');
+        const updatedAt = readOwnString(raw, 'updatedAt');
+        const createdAt = readOwnString(raw, 'createdAt');
+        if (state === undefined || !PRINCIPLE_STATES.has(state)) {
+            throw new GovernanceProjectionCollectionError('governance_projection_error', 'repair_principle_ledger');
+        }
+        const recordedAt = isTimestamp(updatedAt) ? updatedAt : createdAt;
+        if (!isTimestamp(recordedAt)) {
+            throw new GovernanceProjectionCollectionError('governance_projection_error', 'repair_principle_timestamp');
+        }
+        if (!isTimestamp(updatedAt)) {
+            issues.push(issue({ source: 'ledger', reasonCode: 'metadata_malformed', nextActionCode: 'repair_principle_updated_at', sourceRef: { type: 'principle', id: principleId } }));
+        }
+        if (state !== 'candidate' && state !== 'active' && state !== 'archived' && state !== 'deprecated' && state !== 'probation') {
+            throw new GovernanceProjectionCollectionError('governance_projection_error', 'repair_principle_status');
+        }
+        return { schemaVersion: '1', family: 'principle', sourceRef: { type: 'principle', id: principleId }, principleId, lineageConfidence: 'strong', recordedAt, state };
+    }
+    static parseStringArrayJson(value) {
+        if (value === undefined)
+            return null;
+        try {
+            const parsed = JSON.parse(value);
+            return Array.isArray(parsed) && parsed.every(item => typeof item === 'string' && item.length > 0) ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    static parseTaskRow(row, issues) {
+        if (!isRecord(row)) {
+            issues.push(issue({ source: 'task', reasonCode: 'metadata_malformed', nextActionCode: 'repair_task_metadata' }));
+            return null;
+        }
+        const taskId = readOwnString(row, 'task_id');
+        const taskRef = taskId === undefined ? undefined : { type: 'task', id: taskId };
+        const taskKind = readOwnString(row, 'task_kind');
+        const status = readOwnString(row, 'status');
+        const createdAt = readOwnString(row, 'created_at');
+        const updatedAt = readOwnString(row, 'updated_at');
+        const diagnosticJson = readOwnString(row, 'diagnostic_json');
+        const attemptCount = Object.hasOwn(row, 'attempt_count') ? row.attempt_count : undefined;
+        const maxAttempts = Object.hasOwn(row, 'max_attempts') ? row.max_attempts : undefined;
+        const metadata = diagnosticJson === undefined ? null : parsePITaskMetadata(diagnosticJson);
+        const channel = metadata?.channel;
+        if (taskId === undefined || taskKind === undefined || !GOVERNANCE_TASK_KINDS.has(taskKind)
+            || status === undefined || !GOVERNANCE_TASK_STATUSES.has(status) || !isTimestamp(createdAt)
+            || !isTimestamp(updatedAt) || !Number.isInteger(attemptCount) || !Number.isInteger(maxAttempts)
+            || typeof attemptCount !== 'number' || attemptCount < 0 || typeof maxAttempts !== 'number' || maxAttempts < 1
+            || metadata === null
+            || (channel !== 'prompt' && channel !== 'code_tool_hook' && channel !== 'defer_archive')) {
+            issues.push(issue(taskRef === undefined
+                ? { source: 'task', reasonCode: 'metadata_malformed', nextActionCode: 'repair_task_metadata' }
+                : { source: 'task', reasonCode: 'metadata_malformed', nextActionCode: 'repair_task_metadata', sourceRef: taskRef }));
+            return null;
+        }
+        if (taskKind !== 'dreamer' && taskKind !== 'philosopher' && taskKind !== 'scribe' && taskKind !== 'artificer' && taskKind !== 'evaluator' && taskKind !== 'rollout_reviewer')
+            return null;
+        if (status !== 'pending' && status !== 'leased' && status !== 'succeeded' && status !== 'retry_wait' && status !== 'failed' && status !== 'needs_human_review')
+            return null;
+        const result = { taskId, taskKind, status, createdAt, updatedAt, attemptCount, maxAttempts, channel, dependencyTaskIds: metadata.dependencyTaskIds };
+        const leaseExpiresAt = readOwnString(row, 'lease_expires_at');
+        if (leaseExpiresAt !== undefined) {
+            if (!isTimestamp(leaseExpiresAt))
+                issues.push(issue({ source: 'task', reasonCode: 'timestamp_invalid', nextActionCode: 'repair_task_timestamp', sourceRef: taskRef }));
+            else
+                result.leaseExpiresAt = leaseExpiresAt;
+        }
+        const lastError = readOwnString(row, 'last_error');
+        if (lastError !== undefined && isPDErrorCategory(lastError))
+            result.lastErrorCategory = lastError;
+        if (metadata.repairPayload !== undefined) {
+            result.revisionIdentity = { kind: 'evaluator_repair', sourceEvaluatorTaskId: metadata.repairPayload.sourceEvaluatorTaskId, sourceArtificerArtifactId: metadata.repairPayload.sourceArtificerArtifactId, repairIteration: metadata.repairPayload.repairIteration };
+        }
+        else if (metadata.rolloutRevisionPayload !== undefined && metadata.revisionCauseId !== undefined) {
+            result.revisionIdentity = { kind: 'rollout_reopen', causeId: metadata.revisionCauseId, sourceRolloutTaskId: metadata.rolloutRevisionPayload.sourceRolloutTaskId, sourceArtifactId: metadata.rolloutRevisionPayload.sourceArtifactId, revisionIteration: metadata.rolloutRevisionPayload.revisionIteration, taskRevisionEpoch: metadata.revisionCount };
+        }
+        if (metadata.completionIntent !== undefined) {
+            result.completionIntent = { status: metadata.completionIntent.status, revisionEpoch: metadata.completionIntent.revisionEpoch, effect: metadata.completionIntent.effect ?? 'governance_transition' };
+        }
+        if (metadata.runnerDecision !== undefined)
+            result.runnerDecision = metadata.runnerDecision;
+        return result;
+    }
+    static connectedTaskIds(rootIds, tasks, issues) {
+        const adjacency = new Map();
+        const successors = new Map();
+        const connect = (left, right) => {
+            if (left === right) {
+                issues.push(issue({ source: 'lineage', reasonCode: 'lineage_cycle', nextActionCode: 'repair_task_dependencies', sourceRef: { type: 'task', id: left } }));
+                return;
+            }
+            if (!adjacency.has(left))
+                adjacency.set(left, new Set());
+            if (!adjacency.has(right))
+                adjacency.set(right, new Set());
+            adjacency.get(left)?.add(right);
+            adjacency.get(right)?.add(left);
+            if (!successors.has(left))
+                successors.set(left, new Set());
+            successors.get(left)?.add(right);
+        };
+        for (const task of tasks.values())
+            for (const dependency of task.dependencyTaskIds)
+                connect(dependency, task.taskId);
+        const visited = new Set();
+        const queue = [...new Set(rootIds)].sort();
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (current === undefined || visited.has(current))
+                continue;
+            if (visited.size >= MAX_LINEAGE_NODES) {
+                issues.push(issue({ source: 'lineage', reasonCode: 'lineage_limit_exceeded', nextActionCode: 'reduce_or_repair_lineage' }));
+                break;
+            }
+            visited.add(current);
+            for (const neighbor of [...(adjacency.get(current) ?? [])].sort())
+                if (!visited.has(neighbor))
+                    queue.push(neighbor);
+        }
+        const colors = new Map();
+        let cycleId;
+        const visit = (taskId) => {
+            if (colors.get(taskId) === 'visiting') {
+                cycleId = taskId;
+                return true;
+            }
+            if (colors.get(taskId) === 'visited')
+                return false;
+            colors.set(taskId, 'visiting');
+            for (const successor of successors.get(taskId) ?? []) {
+                if (visited.has(successor) && visit(successor))
+                    return true;
+            }
+            colors.set(taskId, 'visited');
+            return false;
+        };
+        for (const taskId of [...visited].sort()) {
+            if (visit(taskId))
+                break;
+        }
+        if (cycleId !== undefined) {
+            issues.push(issue({ source: 'lineage', reasonCode: 'lineage_cycle', nextActionCode: 'repair_task_dependencies', sourceRef: { type: 'task', id: cycleId } }));
+        }
+        return visited;
+    }
+    static finish(input) {
+        const hasArtifacts = (input.artifactIds?.length ?? 0) > 0;
+        const facts = {
+            schemaVersion: '1', principleId: input.principleId, asOf: input.asOf,
+            lineage: {
+                principleId: input.principleId, artifactIds: input.artifactIds ?? [], taskIds: input.taskIds ?? [],
+                revisionIdentities: input.revisionIdentities ?? [],
+                confidence: hasArtifacts
+                    ? (input.collectionIssues.some(item => item.source === 'artifact' || item.source === 'task' || item.source === 'lineage') ? 'weak' : 'strong')
+                    : 'unknown',
+                sourceRefs: input.sourceRefs ?? [{ type: 'principle', id: input.principleId }],
+            },
+            principle: input.principle, tasks: input.tasks ?? [], runnerVerdicts: input.runnerVerdicts ?? [], derivedRelations: input.derivedRelations ?? [],
+            approvals: input.approvals ?? [], activations: input.activations ?? [],
+            timelineEvents: input.timelineEvents ?? [], collectionIssues: input.collectionIssues,
+        };
+        if (!Value.Check(GovernanceFactsSchema, facts)) {
+            throw new GovernanceProjectionCollectionError('governance_projection_error', 'inspect_projection_contract');
+        }
+        return facts;
+    }
+}

package/console/dist/server/routes/principles.d.ts

@@ -4,7 +4,11 @@ interface PrinciplesRouteParams {
     res: ServerResponse;
     workspaceDir: string;
     subPath: string;
+    featureFlags?: Record<string, {
+        enabled: boolean;
+    }>;
+    now?: () => string;
 }
-export declare function handlePrinciplesRoute({ req, res, workspaceDir, subPath, }: PrinciplesRouteParams): Promise<void>;
+export declare function handlePrinciplesRoute({ req, res, workspaceDir, subPath, featureFlags, now, }: PrinciplesRouteParams): Promise<void>;
 export declare function disposePrinciplesModels(): void;
 export {};

package/console/dist/server/routes/principles.js

@@ -2,6 +2,9 @@ import * as path from 'path';
 import * as fs from 'fs';
 import { PrinciplesConsoleModel } from '../models/PrinciplesConsoleModel.js';
 import { PrincipleTrajectoryModel } from '../models/PrincipleTrajectoryModel.js';
+import { GovernanceProjectionCollector, GovernanceProjectionCollectionError } from '../models/GovernanceProjectionCollector.js';
+import { OwnerGovernanceViewSchema, deriveOwnerGovernanceView } from '@principles/core/runtime-v2';
+import { Value } from '@sinclair/typebox/value';
 import { sendSuccess, sendError, sendNotFound } from '../utils/response.js';
 const models = new Map();
 const trajectoryModels = new Map();
@@ -72,7 +75,47 @@ async function getDecidedPrincipleIds(workspaceDir) {
         closeFn?.();
     }
 }
-export async function handlePrinciplesRoute({ req, res, workspaceDir, subPath, }) {
+export async function handlePrinciplesRoute({ req, res, workspaceDir, subPath, featureFlags, now = () => new Date().toISOString(), }) {
+    // GET /api/v1/principles/:id/governance. Gate before constructing any
+    // Console model or projection reader so flag-off is a true no-read path.
+    const governanceMatch = /^\/([^/]+)\/governance$/.exec(subPath);
+    if (req.method === 'GET' && governanceMatch) {
+        const flag = featureFlags?.principle_governance_projection_v2;
+        if (flag?.enabled !== true) {
+            sendError(res, 403, 'feature_disabled', 'Principle governance projection is disabled.', { reason: 'feature_disabled', nextAction: 'Enable features.principle_governance_projection_v2 in .pd/config.yaml.' });
+            return;
+        }
+        const [, rawPrincipleId] = governanceMatch;
+        let principleId;
+        try {
+            principleId = decodeURIComponent(rawPrincipleId ?? '');
+        }
+        catch {
+            sendError(res, 400, 'invalid_principle_id', 'Principle ID contains invalid URL encoding', { nextAction: 'Check the principle ID and retry.' });
+            return;
+        }
+        if (principleId.length === 0) {
+            sendError(res, 400, 'invalid_principle_id', 'Principle ID is missing', { nextAction: 'Provide a non-empty principle ID.' });
+            return;
+        }
+        try {
+            const facts = await new GovernanceProjectionCollector(workspaceDir).collect(principleId, now());
+            const view = deriveOwnerGovernanceView(facts);
+            if (!Value.Check(OwnerGovernanceViewSchema, view)) {
+                sendError(res, 500, 'governance_projection_error', 'Derived governance view failed contract validation.', { nextAction: 'Inspect projection diagnostics and Runtime state.' });
+                return;
+            }
+            sendSuccess(res, view);
+        }
+        catch (error) {
+            if (error instanceof GovernanceProjectionCollectionError) {
+                sendError(res, error.reasonCode === 'principle_not_found' ? 404 : 500, error.reasonCode, error.message, { nextAction: error.nextActionCode });
+                return;
+            }
+            sendError(res, 500, 'governance_projection_error', error instanceof Error ? error.message : String(error), { nextAction: 'inspect_runtime_state' });
+        }
+        return;
+    }
     const model = getModel(workspaceDir);
     // ── POST Routes ─────────────────────────────────────────────────────────────
     if (req.method === 'POST') {