vgxness 1.20.5 → 1.20.7

package/dist/sdd/sdd-workflow-service.js

@@ -1,822 +1 @@
-import { summarizePayloadContent } from '../payload/payload-summary.js';
-import { normalizeSddArtifact, normalizeSddPhaseInput, sddPhases, sddPrerequisites, sddTopicKey, } from './schema.js';
-const defaultContext = { actor: 'sdd-workflow-service' };
-const validChangePattern = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-function readAutoAdvanceFromEnv() {
-    const value = process.env.VGXNESS_SDD_AUTO_ADVANCE;
-    return value === 'true' || value === '1';
-}
-function isPrerequisiteSatisfied(status) {
-    if (status === undefined)
-        return false;
-    if (status.legacy === true)
-        return false;
-    if (status.accepted === true)
-        return true;
-    if (status.state === 'draft')
-        return true;
-    return false;
-}
-export class SddWorkflowService {
-    memory;
-    context;
-    options;
-    constructor(memory, context = defaultContext, options = {}) {
-        this.memory = memory;
-        this.context = context;
-        this.options = {
-            ...options,
-            autoAdvance: options.autoAdvance ?? readAutoAdvanceFromEnv(),
-        };
-    }
-    getWorkflow(change) {
-        return sddPhases.map((phase) => ({
-            phase,
-            topicKey: sddTopicKey(change, phase),
-            prerequisites: [...sddPrerequisites[phase]],
-        }));
-    }
-    getReady(input) {
-        const validated = this.validatePhaseInput(input);
-        if (!validated.ok)
-            return validated;
-        const snapshot = this.loadPhaseSnapshot(validated.value.project, validated.value.change);
-        if (!snapshot.ok)
-            return snapshot;
-        const phases = snapshot.value.phases;
-        const readiness = getReadinessFromStatuses(validated.value.change, validated.value.phase, phases, this.options);
-        return {
-            ok: true,
-            value: {
-                change: validated.value.change,
-                phase: validated.value.phase,
-                ...readiness,
-                gates: readinessGatesForPhase(validated.value.change, validated.value.phase, phases, readiness),
-            },
-        };
-    }
-    getStatus(input) {
-        const validated = validateProjectAndChange(input.project, input.change);
-        if (!validated.ok)
-            return validated;
-        const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
-        if (!phases.ok)
-            return phases;
-        return statusFromPhases(validated.value.change, phases.value, this.options);
-    }
-    getNext(input) {
-        const validated = validateProjectAndChange(input.project, input.change);
-        if (!validated.ok)
-            return validated;
-        const phases = this.getPhaseStatuses(validated.value.project, validated.value.change);
-        if (!phases.ok)
-            return phases;
-        return ok(nextDecisionFromStatuses(validated.value.change, phases.value, this.options));
-    }
-    getCockpit(input) {
-        const validated = validateProjectAndChange(input.project, input.change);
-        if (!validated.ok)
-            return validated;
-        const snapshot = this.loadPhaseSnapshot(validated.value.project, validated.value.change);
-        if (!snapshot.ok)
-            return snapshot;
-        return ok(this.cockpitFromSnapshot(snapshot.value));
-    }
-    getContinuationContext(input) {
-        const validated = validateProjectAndChange(input.project, input.change);
-        if (!validated.ok)
-            return validated;
-        const snapshot = this.loadPhaseSnapshot(validated.value.project, validated.value.change);
-        if (!snapshot.ok)
-            return snapshot;
-        const cockpit = this.cockpitFromSnapshot(snapshot.value);
-        return ok({ next: cockpit.next, cockpit });
-    }
-    getGovernanceSnapshot(input) {
-        const validated = validateProjectAndChange(input.project, input.change);
-        if (!validated.ok)
-            return validated;
-        const snapshot = this.loadPhaseSnapshot(validated.value.project, validated.value.change);
-        if (!snapshot.ok)
-            return snapshot;
-        const phases = snapshot.value.phases;
-        const status = statusFromPhases(validated.value.change, phases, this.options);
-        if (!status.ok)
-            return status;
-        const warnings = [];
-        const artifacts = phases.flatMap((phase) => {
-            if (phase.artifact === undefined)
-                return [];
-            const envelope = normalizeSddArtifact(phase.artifact);
-            warnings.push(...envelope.warnings);
-            if ((input.payloadMode ?? 'compact') === 'compact') {
-                const compactArtifact = compactGovernanceArtifact(envelope.artifact);
-                return [
-                    {
-                        phase: phase.phase,
-                        topicKey: phase.topicKey,
-                        artifact: compactArtifact,
-                        envelope: { ...envelope, artifact: compactArtifact },
-                    },
-                ];
-            }
-            return [{ phase: phase.phase, topicKey: phase.topicKey, artifact: phase.artifact, envelope }];
-        });
-        const readiness = input.phase === undefined ? undefined : { change: validated.value.change, phase: input.phase, ...getReadinessFromStatuses(validated.value.change, input.phase, phases, this.options) };
-        return ok({ status: status.value, artifacts, ...(readiness === undefined ? {} : { readiness }), warnings });
-    }
-    saveArtifact(input) {
-        const validated = this.validatePhaseInput(input);
-        if (!validated.ok)
-            return validated;
-        if (input.content.trim().length === 0)
-            return validationFailure('SDD artifact content must not be empty');
-        const { project, change, phase } = validated.value;
-        const topicKey = sddTopicKey(change, phase);
-        const existing = this.memory.getArtifact(project, topicKey, this.context);
-        if (existing.ok) {
-            const envelope = normalizeSddArtifact(existing.value);
-            const status = envelope.metadata.status;
-            if (status === 'accepted')
-                return validationFailure('Cannot overwrite an accepted SDD artifact; supersede it under a new topic key.');
-            if (status === 'rejected')
-                return validationFailure('Rejected SDD artifact must be re-opened via SddWorkflowService.reopenArtifact before saving.');
-            if (status === 'superseded')
-                return validationFailure('Cannot overwrite a superseded SDD artifact.');
-        }
-        return this.memory.saveArtifact({ project, topicKey, phase, content: input.content, metadata: { status: 'draft' } }, this.context);
-    }
-    acceptArtifact(input) {
-        const validated = this.validatePhaseInput(input);
-        if (!validated.ok)
-            return validated;
-        if (input.acceptedBy === undefined)
-            return validationFailure('SDD artifact acceptance requires an explicit human actor');
-        if (input.acceptedBy.type !== 'human')
-            return validationFailure('SDD artifact acceptance must be performed by a human actor');
-        if (input.acceptedBy.id === undefined || input.acceptedBy.id.trim().length === 0)
-            return validationFailure('SDD artifact acceptance human actor id must not be empty');
-        const topicKey = sddTopicKey(validated.value.change, validated.value.phase);
-        const existing = this.memory.getArtifact(validated.value.project, topicKey, this.context);
-        if (!existing.ok)
-            return existing;
-        const existingEnvelope = normalizeSddArtifact(existing.value);
-        const existingStatus = existingEnvelope.metadata.status;
-        if (existingStatus === 'rejected')
-            return validationFailure('Rejected SDD artifact must be re-opened via SddWorkflowService.reopenArtifact before accepting.');
-        if (existingStatus === 'superseded')
-            return validationFailure('Cannot accept a superseded SDD artifact; create a new artifact under a different topic key instead.');
-        const acceptance = {
-            actor: {
-                type: 'human',
-                id: input.acceptedBy.id,
-                ...(input.acceptedBy.displayName === undefined ? {} : { displayName: input.acceptedBy.displayName }),
-            },
-            acceptedAt: input.acceptedAt ?? new Date().toISOString(),
-            ...(input.note === undefined ? {} : { note: input.note }),
-        };
-        return this.memory.saveArtifact({
-            project: existing.value.project,
-            topicKey: existing.value.topicKey,
-            phase: existing.value.phase,
-            content: existing.value.content,
-            metadata: {
-                ...existingEnvelope.metadata,
-                status: 'accepted',
-                acceptance,
-                updatedAt: acceptance.acceptedAt,
-            },
-        }, this.context);
-    }
-    reopenArtifact(input) {
-        const validated = this.validatePhaseInput(input);
-        if (!validated.ok)
-            return validated;
-        if (input.reopenedBy === undefined)
-            return validationFailure('SDD artifact reopen requires an explicit human actor');
-        if (input.reopenedBy.type !== 'human')
-            return validationFailure('SDD artifact reopen must be performed by a human actor');
-        if (input.reopenedBy.id === undefined || input.reopenedBy.id.trim().length === 0)
-            return validationFailure('SDD artifact reopen human actor id must not be empty');
-        const topicKey = sddTopicKey(validated.value.change, validated.value.phase);
-        const existing = this.memory.getArtifact(validated.value.project, topicKey, this.context);
-        if (!existing.ok)
-            return existing;
-        const existingEnvelope = normalizeSddArtifact(existing.value);
-        const existingStatus = existingEnvelope.metadata.status;
-        if (existingStatus !== 'rejected')
-            return validationFailure(`SDD artifact reopen is only valid for rejected artifacts (current status: ${existingStatus}).`);
-        const reopenedAt = input.reopenedAt ?? new Date().toISOString();
-        const reopenRecord = {
-            actor: {
-                type: 'human',
-                id: input.reopenedBy.id,
-                ...(input.reopenedBy.displayName === undefined ? {} : { displayName: input.reopenedBy.displayName }),
-            },
-            reopenedAt,
-            ...(input.note === undefined ? {} : { note: input.note }),
-        };
-        return this.memory.saveArtifact({
-            project: existing.value.project,
-            topicKey: existing.value.topicKey,
-            phase: existing.value.phase,
-            content: existing.value.content,
-            metadata: {
-                ...existingEnvelope.metadata,
-                status: 'draft',
-                reopen: reopenRecord,
-                updatedAt: reopenedAt,
-            },
-        }, this.context);
-    }
-    getArtifact(input) {
-        const validated = this.validatePhaseInput(input);
-        if (!validated.ok)
-            return validated;
-        const artifact = this.memory.getArtifact(validated.value.project, sddTopicKey(validated.value.change, validated.value.phase), this.context);
-        if (!artifact.ok)
-            return artifact;
-        if (input.payloadMode !== 'compact')
-            return artifact;
-        const statuses = this.getPhaseStatuses(validated.value.project, validated.value.change);
-        if (!statuses.ok)
-            return statuses;
-        return ok(compactArtifactProjection(artifact.value, validated.value.change, validated.value.phase, getReadinessFromStatuses(validated.value.change, validated.value.phase, statuses.value, this.options)));
-    }
-    listArtifacts(input) {
-        const validated = validateProjectAndChange(input.project, input.change);
-        if (!validated.ok)
-            return validated;
-        if (input.payloadMode === 'compact') {
-            const snapshot = this.loadPhaseSnapshot(validated.value.project, validated.value.change);
-            if (!snapshot.ok)
-                return snapshot;
-            return ok({
-                project: validated.value.project,
-                change: validated.value.change,
-                artifacts: snapshot.value.phases.flatMap((phase) => {
-                    if (phase.artifact === undefined)
-                        return [];
-                    return [compactArtifactProjection(phase.artifact, validated.value.change, phase.phase, getReadinessFromStatuses(validated.value.change, phase.phase, snapshot.value.phases, this.options))];
-                }),
-                fullRetrieval: {
-                    tool: 'vgxness_sdd_list_artifacts',
-                    payloadMode: 'verbose',
-                    input: { project: validated.value.project, change: validated.value.change },
-                },
-            });
-        }
-        const snapshot = this.loadPhaseSnapshot(validated.value.project, validated.value.change);
-        if (!snapshot.ok)
-            return snapshot;
-        const artifacts = snapshot.value.phases.flatMap((phase) => (phase.artifact === undefined ? [] : [phase.artifact]));
-        return ok({ project: validated.value.project, change: validated.value.change, artifacts });
-    }
-    validatePhaseInput(input) {
-        const validated = validateProjectAndChange(input.project, input.change);
-        if (!validated.ok)
-            return validated;
-        const phase = normalizeSddPhaseInput(input.phase);
-        if (phase === undefined)
-            return validationFailure(`Unknown SDD phase: ${input.phase}`);
-        return { ok: true, value: { ...validated.value, phase } };
-    }
-    getPhaseStatuses(project, change) {
-        const snapshot = this.loadPhaseSnapshot(project, change);
-        if (!snapshot.ok)
-            return snapshot;
-        return ok(snapshot.value.phases.map(({ artifact, acceptance, createdAt, updatedAt, warnings, ...status }) => status));
-    }
-    loadPhaseSnapshot(project, change) {
-        const listed = this.memory.listArtifactsByTopicPrefixNoTrace(project, `sdd/${change}/`);
-        if (!listed.ok)
-            return listed;
-        const artifactsByTopicKey = new Map(listed.value.map((artifact) => [artifact.topicKey, artifact]));
-        const phases = sddPhases.map((phase) => {
-            const topicKey = sddTopicKey(change, phase);
-            const artifact = artifactsByTopicKey.get(topicKey);
-            if (artifact === undefined)
-                return { phase, topicKey, present: false, state: 'missing', accepted: false, legacy: false, warnings: [] };
-            const envelope = normalizeSddArtifact(artifact);
-            return {
-                phase,
-                topicKey,
-                present: true,
-                state: envelope.metadata.status,
-                accepted: envelope.metadata.status === 'accepted',
-                legacy: envelope.warnings.includes('legacy-artifact-defaulted-to-draft'),
-                artifactId: artifact.id,
-                artifact,
-                ...(envelope.metadata.acceptance === undefined ? {} : { acceptance: envelope.metadata.acceptance }),
-                createdAt: artifact.createdAt,
-                updatedAt: artifact.updatedAt,
-                warnings: envelope.warnings,
-            };
-        });
-        return ok({ project, change, phases });
-    }
-    cockpitFromSnapshot(snapshot) {
-        const phases = snapshot.phases;
-        const next = nextDecisionFromStatuses(snapshot.change, phases, this.options);
-        const cockpitPhases = phases.map((phaseStatus) => {
-            const readiness = {
-                change: snapshot.change,
-                phase: phaseStatus.phase,
-                ...getReadinessFromStatuses(snapshot.change, phaseStatus.phase, phases, this.options),
-            };
-            const artifact = phaseStatus.present ? cockpitArtifactSummaryFromSnapshotItem(phaseStatus) : undefined;
-            const blockers = cockpitBlockersForPhase(phaseStatus, readiness);
-            const gates = phaseGateFromStatus(phaseStatus, readiness);
-            return {
-                phase: phaseStatus.phase,
-                topicKey: phaseStatus.topicKey,
-                present: phaseStatus.present,
-                accepted: phaseStatus.accepted === true,
-                legacy: phaseStatus.legacy === true,
-                state: phaseStatus.state ?? 'missing',
-                readiness,
-                ...(artifact === undefined ? {} : { artifact }),
-                blockers,
-                gates,
-            };
-        });
-        const artifacts = cockpitPhases.map((phase) => phase.artifact).filter((artifact) => artifact !== undefined);
-        const aggregateBlockers = dedupeCockpitBlockers([
-            ...cockpitPhases.flatMap((phase) => phase.blockers),
-            ...(next.missingPrerequisiteTopicKeys ?? []).map((topicKey) => blockerFromTopicKey(snapshot.change, topicKey)),
-            ...(next.blockedPrerequisites ?? []).map((blocker) => ({
-                kind: 'readiness',
-                phase: blocker.phase,
-                topicKey: blocker.topicKey,
-                reason: blocker.reason,
-                ...(blocker.artifactId === undefined ? {} : { artifactId: blocker.artifactId }),
-            })),
-        ]);
-        return {
-            project: snapshot.project,
-            change: snapshot.change,
-            ...(next.nextPhase === undefined ? {} : { actionablePhase: next.nextPhase }),
-            next,
-            recommendedAction: cockpitRecommendedAction(next, aggregateBlockers),
-            phases: cockpitPhases,
-            artifacts,
-            acceptedCount: cockpitPhases.filter((phase) => phase.accepted).length,
-            legacyCount: cockpitPhases.filter((phase) => phase.legacy).length,
-            aggregateBlockers,
-            gates: cockpitGatesFromPhases(cockpitPhases, next),
-            inspectCommand: `vgxness sdd cockpit --project ${snapshot.project} --change ${snapshot.change} --json`,
-        };
-    }
-}
-export function nextDecisionFromStatuses(change, phases, options = {}) {
-    const blockedPresentPhase = phases.find((status) => {
-        if (!status.present)
-            return false;
-        return (getReadinessFromStatuses(change, status.phase, phases, options).blockedPrerequisites ?? []).length > 0;
-    });
-    if (blockedPresentPhase !== undefined) {
-        const readiness = getReadinessFromStatuses(change, blockedPresentPhase.phase, phases, options);
-        const blockers = readiness.blockedPrerequisites ?? [];
-        return {
-            change,
-            status: 'blocked',
-            nextPhase: blockedPresentPhase.phase,
-            missingArtifactTopicKeys: readiness.missingArtifactTopicKeys,
-            missingPrerequisiteTopicKeys: readiness.missingPrerequisiteTopicKeys ?? [],
-            blockedPrerequisites: blockers,
-            blockerGuidance: readiness.blockerGuidance ?? [],
-            reason: `${blockedPresentPhase.phase} is blocked by prerequisite artifacts that are not accepted: ${formatBlockers(blockers)}.`,
-            recommendedAction: blockedRecommendedAction(readiness, 'continuing'),
-        };
-    }
-    const nextMissingPhase = phases.find((status) => !status.present)?.phase;
-    if (nextMissingPhase === undefined) {
-        const firstUnacceptedPhase = phases.find((status) => !status.accepted);
-        if (firstUnacceptedPhase !== undefined) {
-            return {
-                change,
-                status: 'blocked',
-                nextPhase: firstUnacceptedPhase.phase,
-                missingArtifactTopicKeys: [firstUnacceptedPhase.topicKey],
-                missingPrerequisiteTopicKeys: [],
-                blockedPrerequisites: [
-                    {
-                        phase: firstUnacceptedPhase.phase,
-                        topicKey: firstUnacceptedPhase.topicKey,
-                        reason: blockerReasonForStatus(firstUnacceptedPhase),
-                        ...(firstUnacceptedPhase.artifactId === undefined ? {} : { artifactId: firstUnacceptedPhase.artifactId }),
-                    },
-                ],
-                blockerGuidance: [blockerGuidanceForPhaseStatus(firstUnacceptedPhase)],
-                reason: `${firstUnacceptedPhase.phase} is present but ${firstUnacceptedPhase.state ?? 'draft'}; accepted governance status is required before the change is complete.`,
-                recommendedAction: `${blockerActionForStatus(firstUnacceptedPhase)} before archiving this SDD change.`,
-            };
-        }
-        return {
-            change,
-            status: 'complete',
-            missingArtifactTopicKeys: [],
-            blockedPrerequisites: [],
-            reason: 'All canonical SDD phases are complete.',
-            recommendedAction: 'No next SDD phase remains for this change.',
-        };
-    }
-    const readiness = getReadinessFromStatuses(change, nextMissingPhase, phases, options);
-    if (!readiness.ready) {
-        const blockers = readiness.blockedPrerequisites ?? [];
-        return {
-            change,
-            status: 'blocked',
-            nextPhase: nextMissingPhase,
-            missingArtifactTopicKeys: readiness.missingArtifactTopicKeys,
-            missingPrerequisiteTopicKeys: readiness.missingPrerequisiteTopicKeys ?? [],
-            blockedPrerequisites: blockers,
-            blockerGuidance: readiness.blockerGuidance ?? [],
-            reason: `${nextMissingPhase} is blocked by prerequisite artifacts that are not accepted: ${formatBlockers(blockers)}.`,
-            recommendedAction: blockedRecommendedAction(readiness, `running ${nextMissingPhase}`),
-        };
-    }
-    return {
-        change,
-        status: 'runnable',
-        nextPhase: nextMissingPhase,
-        missingArtifactTopicKeys: [],
-        blockedPrerequisites: [],
-        reason: `${nextMissingPhase} is ready to run.`,
-        recommendedAction: `Run the ${nextMissingPhase} SDD phase for ${change}.`,
-    };
-}
-function statusFromPhases(change, phases, options = {}) {
-    const nextReadyPhase = sddPhases.find((phase) => {
-        if (phases.find((status) => status.phase === phase)?.present)
-            return false;
-        return getReadinessFromStatuses(change, phase, phases, options).ready;
-    });
-    const status = { change, phases };
-    if (nextReadyPhase !== undefined)
-        status.nextReadyPhase = nextReadyPhase;
-    return { ok: true, value: status };
-}
-function getReadinessFromStatuses(change, phase, phases, options = {}) {
-    const satisfiedPrerequisites = [];
-    const missingArtifactTopicKeys = [];
-    const missingPrerequisiteTopicKeys = [];
-    const blockedPrerequisites = [];
-    const blockerGuidance = [];
-    const useAutoAdvance = options.autoAdvance === true;
-    for (const prerequisite of sddPrerequisites[phase]) {
-        const status = phases.find((candidate) => candidate.phase === prerequisite);
-        const satisfied = useAutoAdvance ? isPrerequisiteSatisfied(status) : status?.accepted === true;
-        if (satisfied) {
-            satisfiedPrerequisites.push(prerequisite);
-            continue;
-        }
-        const topicKey = status?.topicKey ?? sddTopicKey(change, prerequisite);
-        const reason = status === undefined ? 'missing' : blockerReasonForStatus(status);
-        missingArtifactTopicKeys.push(topicKey);
-        if (reason === 'missing')
-            missingPrerequisiteTopicKeys.push(topicKey);
-        const blocker = {
-            phase: prerequisite,
-            topicKey,
-            reason,
-            ...(status?.artifactId === undefined ? {} : { artifactId: status.artifactId }),
-        };
-        blockedPrerequisites.push(blocker);
-        blockerGuidance.push(blockerGuidanceForBlocker(blocker, phase));
-    }
-    return {
-        ready: blockedPrerequisites.length === 0,
-        satisfiedPrerequisites,
-        missingArtifactTopicKeys,
-        missingPrerequisiteTopicKeys,
-        blockedPrerequisites,
-        blockerGuidance,
-    };
-}
-function compactArtifactProjection(artifact, change, phase, readiness) {
-    const envelope = normalizeSddArtifact(artifact);
-    const summary = summarizePayloadContent(artifact.content);
-    return {
-        id: artifact.id,
-        topicKey: artifact.topicKey,
-        project: artifact.project,
-        change,
-        phase,
-        present: true,
-        state: envelope.metadata.status,
-        accepted: envelope.metadata.status === 'accepted',
-        legacy: envelope.warnings.includes('legacy-artifact-defaulted-to-draft'),
-        ...(envelope.metadata.acceptance === undefined ? {} : { acceptance: envelope.metadata.acceptance }),
-        ...summary,
-        fullRetrieval: { tool: 'vgxness_sdd_get_artifact', payloadMode: 'verbose', input: { project: artifact.project, change, phase } },
-        readiness: { change, phase, ...readiness },
-        observationId: artifact.observationId,
-        createdAt: artifact.createdAt,
-        updatedAt: artifact.updatedAt,
-    };
-}
-function cockpitArtifactSummaryFromSnapshotItem(item) {
-    if (item.artifact === undefined || item.artifactId === undefined || item.createdAt === undefined || item.updatedAt === undefined)
-        return undefined;
-    return {
-        phase: item.phase,
-        topicKey: item.topicKey,
-        present: true,
-        accepted: item.accepted === true,
-        legacy: item.legacy === true,
-        state: item.state ?? 'draft',
-        artifactId: item.artifactId,
-        ...(item.acceptance === undefined ? {} : { acceptance: item.acceptance }),
-        createdAt: item.createdAt,
-        updatedAt: item.updatedAt,
-    };
-}
-function readinessGatesForPhase(change, phase, phases, readiness) {
-    const targetStatus = phases.find((candidate) => candidate.phase === phase) ?? { phase, topicKey: sddTopicKey(change, phase), present: false, state: 'missing', accepted: false, legacy: false, warnings: [] };
-    const targetGate = phaseGateFromStatus(targetStatus, readiness);
-    const prerequisites = sddPrerequisites[phase].map((prerequisite) => {
-        const prerequisiteStatus = phases.find((candidate) => candidate.phase === prerequisite) ?? {
-            phase: prerequisite,
-            topicKey: sddTopicKey(change, prerequisite),
-            present: false,
-            state: 'missing',
-            accepted: false,
-            legacy: false,
-            warnings: [],
-        };
-        const blocker = readiness.blockedPrerequisites?.find((candidate) => candidate.phase === prerequisite);
-        return phaseGateFromStatus(prerequisiteStatus, {
-            ready: blocker === undefined,
-            blockedPrerequisites: blocker === undefined ? [] : [blocker],
-        });
-    });
-    const blockedReasons = [...targetGate.blockedReasons, ...prerequisites.flatMap((gate) => gate.blockedReasons)];
-    return {
-        phase: targetGate,
-        prerequisites,
-        runnable: readiness.ready,
-        blocked: !readiness.ready,
-        blockedReasons: [...new Set(blockedReasons)],
-        humanOnly: targetGate.humanOnly || prerequisites.some((gate) => gate.humanOnly),
-        preflightRequired: targetGate.preflightRequired,
-        agentCallable: true,
-        canDraft: targetGate.canDraft,
-        canMarkReady: targetGate.canMarkReady,
-        canAccept: targetGate.canAccept || prerequisites.some((gate) => gate.canAccept),
-        canReopen: targetGate.canReopen || prerequisites.some((gate) => gate.canReopen),
-        nextAllowedActions: [...new Set([targetGate, ...prerequisites].flatMap((gate) => gate.nextAllowedActions))],
-        requiresProviderWriteConsent: false,
-    };
-}
-function cockpitGatesFromPhases(phases, next) {
-    const phaseGates = phases.map((phase) => phase.gates ?? phaseGateFromStatus(phase, phase.readiness));
-    const blockedTransitions = phaseGates.filter((gate) => gate.blocked);
-    const blockedReasons = [...new Set(blockedTransitions.flatMap((gate) => gate.blockedReasons))];
-    const runnableNextPhases = phaseGates.filter((gate) => gate.runnable && !gate.artifactPresent).map((gate) => gate.phase);
-    return {
-        phases: phaseGates,
-        changeComplete: phases.length === sddPhases.length && phases.every((phase) => phase.accepted),
-        ...(next.nextPhase === undefined ? {} : { nextPhase: next.nextPhase }),
-        nextPhaseRunnable: next.status === 'runnable',
-        runnableNextPhases,
-        blockedTransitions,
-        blockedReasons,
-        requiresHumanAcceptance: phaseGates.some((gate) => gate.requiresHumanAcceptance),
-        humanOnly: phaseGates.some((gate) => gate.humanOnly),
-        preflightRequired: next.status === 'runnable',
-        agentCallable: true,
-        canDraft: phaseGates.some((gate) => gate.canDraft),
-        canMarkReady: phaseGates.some((gate) => gate.canMarkReady),
-        canAccept: phaseGates.some((gate) => gate.canAccept),
-        canReopen: phaseGates.some((gate) => gate.canReopen),
-        nextAllowedActions: [...new Set(phaseGates.flatMap((gate) => gate.nextAllowedActions))],
-        requiresProviderWriteConsent: false,
-    };
-}
-function phaseGateFromStatus(status, readiness) {
-    const artifactStatus = status.state ?? (status.present ? 'draft' : 'missing');
-    const acceptedByHuman = status.accepted === true && status.acceptance?.actor.type === 'human';
-    const blockedPrerequisite = readiness.blockedPrerequisites?.[0];
-    const blockedReasons = [
-        ...((readiness.blockedPrerequisites ?? []).map((blocker) => `${blocker.phase}:${blocker.reason}`)),
-        ...(status.present && status.accepted !== true ? [`${status.phase}:${blockerReasonForStatus(status)}`] : []),
-        ...(status.legacy === true ? [`${status.phase}:legacy`] : []),
-    ];
-    const requiresHumanAcceptance = status.present && !acceptedByHuman && artifactStatus !== 'missing';
-    const canDraft = readiness.ready && !status.present;
-    const canMarkReady = readiness.ready;
-    const canAccept = status.present && !acceptedByHuman && status.legacy !== true && (artifactStatus === 'draft' || artifactStatus === 'accepted');
-    const canReopen = status.present && artifactStatus === 'rejected';
-    const nextAllowedActions = phaseNextAllowedActions({ canDraft, canMarkReady, canAccept, canReopen, present: status.present });
-    return {
-        phase: status.phase,
-        topicKey: status.topicKey,
-        artifactPresent: status.present,
-        artifactStatus,
-        artifactState: status.legacy === true ? 'legacy' : artifactStatus,
-        accepted: status.accepted === true,
-        acceptedByHuman,
-        agentCallable: true,
-        requiresHumanAcceptance,
-        draftPresent: artifactStatus === 'draft',
-        contentFrozen: acceptedByHuman,
-        runnable: readiness.ready && !status.present,
-        blocked: !readiness.ready || status.legacy === true || (status.present && status.accepted !== true),
-        blockedReasons: [...new Set(blockedReasons)],
-        humanOnly: requiresHumanAcceptance,
-        preflightRequired: readiness.ready && !status.present,
-        requiresPreflight: readiness.ready && !status.present,
-        requiresProviderWriteConsent: false,
-        canDraft,
-        canMarkReady,
-        canAccept,
-        canReopen,
-        nextAllowedActions,
-        ...(blockedPrerequisite === undefined ? {} : { requiredPriorPhase: blockedPrerequisite.phase, blockerReason: blockedPrerequisite.reason }),
-    };
-}
-function phaseNextAllowedActions(input) {
-    const actions = ['vgxness_sdd_get_readiness', 'vgxness_sdd_cockpit'];
-    if (input.canDraft)
-        actions.push('vgxness_sdd_save_artifact');
-    if (input.canMarkReady)
-        actions.push('vgxness_sdd_ready');
-    if (input.present)
-        actions.push('vgxness_sdd_get_artifact');
-    if (input.canAccept)
-        actions.push('vgxness_sdd_accept_artifact');
-    if (input.canReopen)
-        actions.push('vgxness_sdd_reopen_artifact');
-    return [...new Set(actions)];
-}
-function compactGovernanceArtifact(artifact) {
-    return {
-        id: artifact.id,
-        project: artifact.project,
-        topicKey: artifact.topicKey,
-        phase: artifact.phase,
-        observationId: artifact.observationId,
-        createdAt: artifact.createdAt,
-        updatedAt: artifact.updatedAt,
-        contentLength: artifact.content.length,
-        contentOmitted: true,
-    };
-}
-function cockpitBlockersForPhase(status, readiness) {
-    const blockers = [];
-    if (!status.present)
-        blockers.push({
-            kind: 'missing-topic-key',
-            phase: status.phase,
-            topicKey: status.topicKey,
-            reason: 'Canonical SDD artifact is missing.',
-            action: blockerActionForBlocker({ phase: status.phase, topicKey: status.topicKey, reason: 'missing' }),
-        });
-    if (status.present && status.accepted !== true)
-        blockers.push({
-            kind: 'unaccepted-phase',
-            phase: status.phase,
-            topicKey: status.topicKey,
-            reason: `${status.phase} is ${status.state ?? 'draft'}; explicit human acceptance is required.`,
-            action: blockerActionForStatus(status),
-            ...(status.artifactId === undefined ? {} : { artifactId: status.artifactId }),
-        });
-    if (status.legacy === true)
-        blockers.push({
-            kind: 'legacy-artifact',
-            phase: status.phase,
-            topicKey: status.topicKey,
-            reason: 'Artifact has legacy or missing governance metadata and is treated as not accepted.',
-            action: blockerActionForStatus(status),
-            ...(status.artifactId === undefined ? {} : { artifactId: status.artifactId }),
-        });
-    for (const blocker of readiness.blockedPrerequisites ?? []) {
-        blockers.push({
-            kind: 'readiness',
-            phase: blocker.phase,
-            topicKey: blocker.topicKey,
-            reason: blocker.reason,
-            action: blockerActionForBlocker(blocker),
-            ...(blocker.artifactId === undefined ? {} : { artifactId: blocker.artifactId }),
-        });
-    }
-    return blockers;
-}
-function blockerFromTopicKey(change, topicKey) {
-    const phase = phaseFromTopicKey(change, topicKey);
-    return {
-        kind: 'missing-topic-key',
-        phase,
-        topicKey,
-        reason: 'Required SDD topic key is missing or not accepted.',
-        action: blockerActionForBlocker({ phase, topicKey, reason: 'missing' }),
-    };
-}
-function dedupeCockpitBlockers(blockers) {
-    const seen = new Set();
-    return blockers.filter((blocker) => {
-        const key = `${blocker.kind}:${blocker.phase}:${blocker.topicKey}:${blocker.reason}`;
-        if (seen.has(key))
-            return false;
-        seen.add(key);
-        return true;
-    });
-}
-function cockpitRecommendedAction(next, blockers) {
-    if (next.status === 'complete')
-        return next.recommendedAction;
-    if (next.status === 'runnable')
-        return next.recommendedAction;
-    const legacy = blockers.find((blocker) => blocker.kind === 'legacy-artifact');
-    if (legacy !== undefined)
-        return legacy.action ?? `Inspect and explicitly accept or replace legacy artifact ${legacy.topicKey}.`;
-    const unaccepted = blockers.find((blocker) => blocker.kind === 'unaccepted-phase');
-    if (unaccepted !== undefined)
-        return unaccepted.action ?? `Accept or replace ${unaccepted.topicKey} before continuing.`;
-    return next.recommendedAction;
-}
-function blockedRecommendedAction(readiness, context) {
-    const firstGuidance = readiness.blockerGuidance?.[0];
-    if (firstGuidance !== undefined)
-        return `${firstGuidance.action} before ${context}.`;
-    const firstBlocker = readiness.blockedPrerequisites?.[0];
-    if (firstBlocker !== undefined)
-        return `${blockerActionForBlocker(firstBlocker)} before ${context}.`;
-    return `Resolve prerequisite blockers before ${context}.`;
-}
-function blockerGuidanceForPhaseStatus(status) {
-    return blockerGuidanceForBlocker({
-        phase: status.phase,
-        topicKey: status.topicKey,
-        reason: blockerReasonForStatus(status),
-        ...(status.artifactId === undefined ? {} : { artifactId: status.artifactId }),
-    });
-}
-function blockerGuidanceForBlocker(blocker, blockedPhase) {
-    return {
-        phase: blocker.phase,
-        topicKey: blocker.topicKey,
-        reason: blocker.reason,
-        action: blockerActionForBlocker(blocker, blockedPhase),
-        ...(blocker.artifactId === undefined ? {} : { artifactId: blocker.artifactId }),
-    };
-}
-function blockerActionForStatus(status) {
-    return blockerActionForBlocker({
-        phase: status.phase,
-        topicKey: status.topicKey,
-        reason: blockerReasonForStatus(status),
-        ...(status.artifactId === undefined ? {} : { artifactId: status.artifactId }),
-    });
-}
-function blockerActionForBlocker(blocker, blockedPhase) {
-    switch (blocker.reason) {
-        case 'missing':
-            return `Run or create the ${blocker.phase} SDD phase artifact at ${blocker.topicKey}`;
-        case 'draft':
-            if (blockedPhase !== undefined && isDraftRunPlanningPhase(blockedPhase))
-                return `Accept ${blocker.topicKey} if it is ready, or continue planning ${blockedPhase} in OpenCode with VGXNESS MCP after explicitly acknowledging that human acceptance is still required and apply-progress remains gated`;
-            return `Accept ${blocker.topicKey}, or continue and re-run the ${blocker.phase} phase if the draft is incomplete`;
-        case 'accepted':
-            return `Inspect ${blocker.topicKey}; it is marked accepted but still appears in blocker data`;
-        case 'legacy':
-            return `Inspect ${blocker.topicKey} and explicitly accept or replace the legacy artifact`;
-        case 'rejected':
-            return `Reopen ${blocker.topicKey} for revision, or replace it with a new accepted artifact`;
-        case 'superseded':
-            return `Use the current replacement for ${blocker.topicKey}, or create and accept a new canonical ${blocker.phase} artifact`;
-    }
-}
-function isDraftRunPlanningPhase(phase) {
-    return phase === 'explore' || phase === 'proposal' || phase === 'spec' || phase === 'design' || phase === 'tasks';
-}
-function phaseFromTopicKey(change, topicKey) {
-    const suffix = topicKey.slice(`sdd/${change}/`.length);
-    const phase = normalizeSddPhaseInput(suffix);
-    if (phase !== undefined)
-        return phase;
-    return 'explore';
-}
-function blockerReasonForStatus(status) {
-    if (status.legacy === true)
-        return 'legacy';
-    const state = status.state ?? (status.present ? 'draft' : 'missing');
-    return state;
-}
-function formatBlockers(blockers) {
-    return blockers.map((blocker) => `${blocker.phase} (${blocker.reason}: ${blocker.topicKey})`).join(', ');
-}
-function validateProjectAndChange(project, change) {
-    if (project.trim().length === 0)
-        return validationFailure('Project must not be empty');
-    if (!validChangePattern.test(change))
-        return validationFailure(`Invalid SDD change id: ${change}`);
-    return { ok: true, value: { project, change } };
-}
-function validationFailure(message) {
-    return { ok: false, error: { code: 'validation_failed', message } };
-}
-function ok(value) {
-    return { ok: true, value };
-}
+export * from '../application/sdd/sdd-workflow-service.js';