@msn-control/liftoff 0.9.9 → 0.10.0

package/dist/governance-activation/source-of-truth.d.ts

@@ -0,0 +1,164 @@
+import type { ActivationIdentity, GraphReconciliationRecord, ManagedPhaseGraph, PhaseEvidenceRecord, PhaseId, SupersessionRecord, UserActivationState } from './types.js';
+import type { LiftoffManifest, SpecWorkflowId } from '../types.js';
+export declare const governanceChangeMetadataFileName: 'liftoff-governance.json';
+export declare const governanceSupersessionPathParts: readonly ['governance', 'supersessions'];
+export declare const governanceReconciliationPathParts: readonly ['governance', 'reconciliation'];
+export declare const governanceSourceOfTruthMarker: 'liftoff-governance-source-of-truth';
+export declare const governanceChangeMetadataSchemaVersion: 1;
+export interface GovernancePhaseTaskMapping {
+    phaseId: PhaseId;
+    taskId: string;
+    marker: `<!-- liftoff-phase: ${PhaseId} -->`;
+    policy: 'evidence-projection-v1';
+}
+export interface GovernanceChangeMetadata {
+    schemaVersion: typeof governanceChangeMetadataSchemaVersion;
+    marker: typeof governanceSourceOfTruthMarker;
+    changeId: string;
+    workflowKind: SpecWorkflowId;
+    activationIdentity: ActivationIdentity;
+    phaseGraphHash: string;
+    baselineSha: string;
+    phaseTaskMapping: readonly GovernancePhaseTaskMapping[];
+    currentPolicy: {
+        phaseAuthority: 'managed-phase-graph';
+        taskCompletion: 'authoritative-evidence-projection';
+        approvalPolicy: 'approval-envelope-required-for-gated-phases';
+    };
+    createdFrom: {
+        kind: 'approved-phase-0-facts';
+        approvedFactDigest: string;
+        evidenceIds: readonly string[];
+    };
+    acknowledgedAt: string;
+    owner: string;
+}
+export interface ApprovedPhase0Fact {
+    id: string;
+    value: string | number | boolean | null;
+}
+export interface ApprovedPhase0Facts {
+    projectName: string;
+    repositoryId: string;
+    repositoryName: string;
+    defaultBranch: string;
+    workflowKind: SpecWorkflowId;
+    baselineSha: string;
+    evidenceIds: readonly string[];
+    approvedFacts: readonly ApprovedPhase0Fact[];
+    approvedAt: string;
+    approver: string;
+}
+export interface GovernanceChangeFilePlan {
+    pathParts: readonly string[];
+    content: string;
+}
+export interface GovernanceChangeWritePlan {
+    changeId: string;
+    workflowKind: SpecWorkflowId;
+    metadata: GovernanceChangeMetadata;
+    files: readonly GovernanceChangeFilePlan[];
+    transactionalWrite: {
+        functionName: 'writeGovernanceChangeArtifacts';
+        writesAllFilesOrThrows: true;
+    };
+}
+export type ActiveGovernanceCandidateStatus = 'compatible' | 'identity-mismatch' | 'invalid-metadata' | 'missing-metadata';
+export interface ActiveGovernanceCandidate {
+    changeId: string;
+    workflowKind: SpecWorkflowId;
+    pathParts: readonly string[];
+    status: ActiveGovernanceCandidateStatus;
+    metadata?: GovernanceChangeMetadata;
+    issues: readonly string[];
+}
+export type GovernanceSourceOfTruthInspection = {
+    status: 'seed-blocked';
+    seedChangeId: string;
+    blockers: readonly string[];
+    selected: null;
+    candidates: readonly ActiveGovernanceCandidate[];
+} | {
+    status: 'none';
+    selected: null;
+    candidates: readonly ActiveGovernanceCandidate[];
+    createPlan: GovernanceCreateChangePlanPreview;
+} | {
+    status: 'selected';
+    selected: ActiveGovernanceCandidate;
+    candidates: readonly ActiveGovernanceCandidate[];
+    recordActiveChangeOnNextMutation: boolean;
+    reconciliation: GovernanceActiveReconciliationResult;
+    supersession: GovernanceSupersessionInspection;
+} | {
+    status: 'ambiguous';
+    selected: null;
+    candidates: readonly ActiveGovernanceCandidate[];
+    blockers: readonly string[];
+    supersession: GovernanceSupersessionInspection;
+} | {
+    status: 'incompatible';
+    selected: null;
+    candidates: readonly ActiveGovernanceCandidate[];
+    blockers: readonly string[];
+    reconciliation: GovernanceActiveReconciliationResult;
+};
+export interface GovernanceCreateChangePlanPreview {
+    status: 'ready' | 'blocked';
+    reason: string;
+    changeId: string;
+    workflowKind: SpecWorkflowId;
+    requiredFacts: readonly string[];
+}
+export interface GovernanceSupersessionInspection {
+    records: readonly SupersessionRecord[];
+    invalidRecords: readonly string[];
+    selectedChangeId: string | null;
+    issues: readonly string[];
+}
+export type GovernanceActiveReconciliationResult = {
+    status: 'not-required';
+    approvalRequired: false;
+    preservedPhaseIds: readonly PhaseId[];
+    invalidPhaseIds: readonly PhaseId[];
+    issues: readonly string[];
+} | {
+    status: 'required';
+    approvalRequired: true;
+    fromIdentity: ActivationIdentity;
+    toIdentity: ActivationIdentity;
+    record: GraphReconciliationRecord;
+    preservedPhaseIds: readonly PhaseId[];
+    invalidPhaseIds: readonly PhaseId[];
+    evidenceToReview: readonly string[];
+    issues: readonly string[];
+} | {
+    status: 'blocked';
+    approvalRequired: false;
+    issues: readonly string[];
+    preservedPhaseIds: readonly PhaseId[];
+    invalidPhaseIds: readonly PhaseId[];
+};
+export declare function validateGovernanceChangeMetadata(value: unknown): GovernanceChangeMetadata;
+export declare function governancePhaseTaskMappings(): GovernancePhaseTaskMapping[];
+export declare function approvedPhase0FactDigest(facts: ApprovedPhase0Facts): string;
+export declare function deterministicGovernanceChangeId(facts: Pick<ApprovedPhase0Facts, 'projectName' | 'baselineSha' | 'workflowKind'>): string;
+export declare function renderGovernanceChangeWritePlan(facts: ApprovedPhase0Facts): GovernanceChangeWritePlan;
+export declare function writeGovernanceChangeArtifacts(projectRoot: string, plan: GovernanceChangeWritePlan): Promise<void>;
+export declare function buildApprovedPhase0FactsFromState(manifest: LiftoffManifest, state: UserActivationState, evidence: readonly PhaseEvidenceRecord[]): ApprovedPhase0Facts | undefined;
+export declare function reconcileActiveGovernanceChange(input: {
+    metadata: GovernanceChangeMetadata;
+    evidence: readonly PhaseEvidenceRecord[];
+    fromGraph?: ManagedPhaseGraph;
+    toGraph?: ManagedPhaseGraph;
+    toIdentity?: ActivationIdentity;
+    recognizedGraphHashes?: ReadonlySet<string>;
+    reconciledAt?: string;
+}): GovernanceActiveReconciliationResult;
+export declare function stateWithSelectedActiveChange(state: UserActivationState, selected: ActiveGovernanceCandidate): UserActivationState;
+export declare function inspectGovernanceSourceOfTruth(input: {
+    projectRoot: string;
+    manifest: LiftoffManifest;
+    state: UserActivationState;
+    evidence: readonly PhaseEvidenceRecord[];
+}): Promise<GovernanceSourceOfTruthInspection>;