@neuraloom/contracts 0.0.0-stage → 0.1.23

package/dist/workflow/film-spine-nav-aliases.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Film production public nav aliases — contracts SSOT for assurance harness.
+ *
+ * Public navigation is projected here from the channel registry so frontend,
+ * assurance, and orchestration never maintain competing film step lists.
+ */
+import type { WorkflowStepDefinition } from '../constants/workflow-registry';
+import { type WorkflowVariant } from './channel-registry';
+/** Public URL segment → internal channel stepId. */
+export declare const FILM_PUBLIC_ROUTE_TO_INTERNAL_STEP: Readonly<Record<string, string>>;
+/** Internal stepId → public nav alias segments (operator-facing labels). */
+export declare const FILM_INTERNAL_STEP_NAV_ALIASES: Readonly<Record<string, readonly string[]>>;
+/** Public spine labels in operator nav order (development is internal-only). */
+export declare const FILM_PUBLIC_SPINE_LABELS: readonly string[];
+export declare function getFilmNavAliasesForStep(stepId: string): readonly string[];
+/**
+ * Canonical operator-navigation projection for every scoped workflow variant.
+ *
+ * Execution keeps the internal film `development` step, while the human-facing
+ * plan exposes Story and Bibles as two readable views of that same step. All
+ * other fields remain derived from WorkflowChannelRegistry / WORKFLOW_STEPS.
+ */
+export declare function getWorkflowNavigationPlan(variant: WorkflowVariant): WorkflowStepDefinition[];

package/dist/workflow/film-spine-nav-aliases.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * Film production public nav aliases — contracts SSOT for assurance harness.
+ *
+ * Public navigation is projected here from the channel registry so frontend,
+ * assurance, and orchestration never maintain competing film step lists.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILM_PUBLIC_SPINE_LABELS = exports.FILM_INTERNAL_STEP_NAV_ALIASES = exports.FILM_PUBLIC_ROUTE_TO_INTERNAL_STEP = void 0;
+exports.getFilmNavAliasesForStep = getFilmNavAliasesForStep;
+exports.getWorkflowNavigationPlan = getWorkflowNavigationPlan;
+const channel_registry_1 = require("./channel-registry");
+/** Public URL segment → internal channel stepId. */
+exports.FILM_PUBLIC_ROUTE_TO_INTERNAL_STEP = {
+    story: 'development',
+    bibles: 'development',
+};
+/** Internal stepId → public nav alias segments (operator-facing labels). */
+exports.FILM_INTERNAL_STEP_NAV_ALIASES = {
+    development: ['story', 'bibles'],
+};
+/** Public spine labels in operator nav order (development is internal-only). */
+exports.FILM_PUBLIC_SPINE_LABELS = [
+    'intent',
+    'story',
+    'bibles',
+    'script',
+    'preproduction',
+    'generation',
+    'postproduction',
+    'review',
+    'release',
+];
+function getFilmNavAliasesForStep(stepId) {
+    return exports.FILM_INTERNAL_STEP_NAV_ALIASES[stepId] ?? [];
+}
+function publicLabel(stepId) {
+    return stepId.charAt(0).toUpperCase() + stepId.slice(1);
+}
+/**
+ * Canonical operator-navigation projection for every scoped workflow variant.
+ *
+ * Execution keeps the internal film `development` step, while the human-facing
+ * plan exposes Story and Bibles as two readable views of that same step. All
+ * other fields remain derived from WorkflowChannelRegistry / WORKFLOW_STEPS.
+ */
+function getWorkflowNavigationPlan(variant) {
+    const executionPlan = (0, channel_registry_1.getWorkflowPlan)(variant);
+    if (variant === 'software_app') {
+        return executionPlan;
+    }
+    const channel = (0, channel_registry_1.getWorkflowChannel)(variant);
+    const expanded = executionPlan.flatMap((planStep) => {
+        const channelStep = channel.steps.find((step) => step.stepId === planStep.id);
+        const description = channelStep?.stages.map((stage) => stage.label).join(' · ') ??
+            planStep.description;
+        const aliases = variant === 'film_production'
+            ? getFilmNavAliasesForStep(planStep.id)
+            : [];
+        if (aliases.length === 0) {
+            return [{ ...planStep, description }];
+        }
+        return aliases.map((stepId) => {
+            const label = publicLabel(stepId);
+            return {
+                ...planStep,
+                id: stepId,
+                name: label,
+                title: label,
+                description,
+                path: `/${stepId}`,
+            };
+        });
+    });
+    return expanded.map((step, index) => ({ ...step, order: index + 1 }));
+}

package/dist/workflow/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Workflow registry public surface.
+ * Import channel types and helpers from this barrel, not from individual files.
+ */
+export * from './channel-registry';
+export * from './api-route-key-resolver';
+export * from './resolve-workflow-variant';
+export * from './project-kind-normalizer';
+export * from './test-policy-registry';
+export * from './workflow-doctor-closure';
+export * from './evaluate-ingest-gate';
+export * from './evaluate-repair-specify-gate';
+export * from './normalize-workflow-execution-mode';
+export * from './evaluate-existing-codebase-readiness';
+export * from './existing-codebase-step-area-map';
+export * from './is-repository-scan-complete';
+export * from './is-code-reality-semantically-mapped';
+export * from './step-id-canonical';
+export * from './film-spine-nav-aliases';
+export * from './workflow-assurance-wiring-tiers';
+export * from './workflow-assurance-manifest';
+export * from './workflow-assurance-completion-probe-gates';
+export * from './assurance-selector-keys';

package/dist/workflow/index.js

@@ -0,0 +1,39 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Workflow registry public surface.
+ * Import channel types and helpers from this barrel, not from individual files.
+ */
+__exportStar(require("./channel-registry"), exports);
+__exportStar(require("./api-route-key-resolver"), exports);
+__exportStar(require("./resolve-workflow-variant"), exports);
+__exportStar(require("./project-kind-normalizer"), exports);
+__exportStar(require("./test-policy-registry"), exports);
+__exportStar(require("./workflow-doctor-closure"), exports);
+__exportStar(require("./evaluate-ingest-gate"), exports);
+__exportStar(require("./evaluate-repair-specify-gate"), exports);
+__exportStar(require("./normalize-workflow-execution-mode"), exports);
+__exportStar(require("./evaluate-existing-codebase-readiness"), exports);
+__exportStar(require("./existing-codebase-step-area-map"), exports);
+__exportStar(require("./is-repository-scan-complete"), exports);
+__exportStar(require("./is-code-reality-semantically-mapped"), exports);
+__exportStar(require("./step-id-canonical"), exports);
+__exportStar(require("./film-spine-nav-aliases"), exports);
+__exportStar(require("./workflow-assurance-wiring-tiers"), exports);
+__exportStar(require("./workflow-assurance-manifest"), exports);
+__exportStar(require("./workflow-assurance-completion-probe-gates"), exports);
+__exportStar(require("./assurance-selector-keys"), exports);

package/dist/workflow/is-code-reality-semantically-mapped.d.ts

@@ -0,0 +1,8 @@
+import type { CodeRealitySemanticCoverage } from '../schemas/workflow/code-reality-artifacts.schema';
+/**
+ * A repo is not "mapped" when the code-reality AST/content index is missing,
+ * capped (legacy INDEXER_CONTENT_MAX = 80), or otherwise incomplete.
+ * Incremental scans may select fewer than all eligible files; that is not a cap
+ * when `scanScope` is incremental and semanticComplete is true.
+ */
+export declare function isCodeRealitySemanticallyMapped(coverage: CodeRealitySemanticCoverage | undefined | null): boolean;

package/dist/workflow/is-code-reality-semantically-mapped.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCodeRealitySemanticallyMapped = isCodeRealitySemanticallyMapped;
+/**
+ * A repo is not "mapped" when the code-reality AST/content index is missing,
+ * capped (legacy INDEXER_CONTENT_MAX = 80), or otherwise incomplete.
+ * Incremental scans may select fewer than all eligible files; that is not a cap
+ * when `scanScope` is incremental and semanticComplete is true.
+ */
+function isCodeRealitySemanticallyMapped(coverage) {
+    if (coverage === undefined || coverage === null) {
+        return false;
+    }
+    if (coverage.bounds.contentCapped) {
+        return false;
+    }
+    if (coverage.bounds.contentMax !== undefined) {
+        return false;
+    }
+    return coverage.semanticComplete;
+}

package/dist/workflow/is-repository-scan-complete.d.ts

@@ -0,0 +1,11 @@
+import type { ExistingCodebaseRepositoryRef } from '../schemas/workflow/existing-codebase-context.schema';
+/**
+ * SSOT for "repository scan complete" — aligned with ingest gate (lastScannedAt)
+ * and repoIntelSnapshot scanStatus (`passed` | `warning` | `failed`).
+ */
+export declare function isRepositoryScanComplete(input: {
+    repository: Pick<ExistingCodebaseRepositoryRef, 'linked' | 'lastScannedAt'>;
+    scanStatus: string | null;
+    /** When false, a tree scan (lastScannedAt) is not a mapped code graph. */
+    semanticMapped?: boolean;
+}): boolean;

package/dist/workflow/is-repository-scan-complete.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRepositoryScanComplete = isRepositoryScanComplete;
+const COMPLETE_SCAN_STATUS_TOKENS = new Set([
+    'completed',
+    'success',
+    'passed',
+    'active',
+]);
+/**
+ * SSOT for "repository scan complete" — aligned with ingest gate (lastScannedAt)
+ * and repoIntelSnapshot scanStatus (`passed` | `warning` | `failed`).
+ */
+function isRepositoryScanComplete(input) {
+    const { repository, scanStatus } = input;
+    if (input.semanticMapped === false) {
+        return false;
+    }
+    if (repository.linked &&
+        repository.lastScannedAt !== null &&
+        repository.lastScannedAt.length > 0) {
+        return true;
+    }
+    if (scanStatus === null || scanStatus.length === 0) {
+        return false;
+    }
+    return COMPLETE_SCAN_STATUS_TOKENS.has(scanStatus.toLowerCase());
+}

package/dist/workflow/normalize-workflow-execution-mode.d.ts

@@ -0,0 +1,4 @@
+import { type WorkflowExecutionMode } from '../schemas/ai/workflow-execution-mode.schema';
+/** Treat legacy improve-existing as audit-existing for ingest gates. */
+export declare function normalizeWorkflowExecutionMode(raw: unknown): WorkflowExecutionMode | null;
+export declare function isAuditLikeExecutionMode(mode: WorkflowExecutionMode | null): mode is 'audit-existing';

package/dist/workflow/normalize-workflow-execution-mode.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeWorkflowExecutionMode = normalizeWorkflowExecutionMode;
+exports.isAuditLikeExecutionMode = isAuditLikeExecutionMode;
+const workflow_execution_mode_schema_1 = require("../schemas/ai/workflow-execution-mode.schema");
+/** Treat legacy improve-existing as audit-existing for ingest gates. */
+function normalizeWorkflowExecutionMode(raw) {
+    if (raw === 'improve-existing') {
+        return 'audit-existing';
+    }
+    const parsed = workflow_execution_mode_schema_1.WorkflowExecutionModeSchema.safeParse(raw);
+    return parsed.success ? parsed.data : null;
+}
+function isAuditLikeExecutionMode(mode) {
+    return mode === 'audit-existing';
+}

package/dist/workflow/project-kind-normalizer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Project creation kind normalization — SSOT for legacy `kind`, `project_kind`, and `workflow_variant`.
+ *
+ * Canonical rule:
+ *   workflow_variant = workflow spine truth
+ *   project_kind     = domain truth
+ *   kind             = legacy compatibility only (must satisfy projects_kind_check)
+ */
+import { type WorkflowKind } from '../constants/workflow-registry';
+import { type WorkflowVariant } from './channel-registry';
+export type NormalizedProjectCreationFields = {
+    /** Legacy `projects.kind` column — DB check constraint compatible. */
+    kind: WorkflowKind;
+    projectKind: string;
+    workflowVariant: WorkflowVariant;
+};
+export type ProjectCreationFieldsInput = {
+    kind?: string | null;
+    projectKind?: string | null;
+    workflowVariant?: string | null;
+};
+/** Values that must not override a more specific legacy `kind` during resolution. */
+export declare const GENERIC_PROJECT_KIND_VALUES: readonly ["software"];
+export declare function isGenericProjectKind(projectKind: string | null | undefined): boolean;
+/** Selector from UI or API — WorkflowKind string or explicit WorkflowVariant. */
+/** Workflow kinds exposed on /projects/new (non-experimental only). */
+export declare const PRODUCTION_CREATE_WORKFLOW_KINDS: readonly ["software", "book", "fiction", "nonfiction", "film", "technical_report"];
+export type ProjectCreationSelector = WorkflowKind | WorkflowVariant | string;
+/**
+ * Normalize partial or legacy create payloads into a canonical DB-safe tuple.
+ */
+export declare function normalizeProjectCreationFields(input: ProjectCreationFieldsInput): NormalizedProjectCreationFields;
+/** Convenience for /projects/new — defaults book → nonfiction_book until fiction/nonfiction picker ships. */
+export declare function normalizeProjectCreationKind(selector: ProjectCreationSelector, _subtype?: string | null): NormalizedProjectCreationFields;

package/dist/workflow/project-kind-normalizer.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * Project creation kind normalization — SSOT for legacy `kind`, `project_kind`, and `workflow_variant`.
+ *
+ * Canonical rule:
+ *   workflow_variant = workflow spine truth
+ *   project_kind     = domain truth
+ *   kind             = legacy compatibility only (must satisfy projects_kind_check)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRODUCTION_CREATE_WORKFLOW_KINDS = exports.GENERIC_PROJECT_KIND_VALUES = void 0;
+exports.isGenericProjectKind = isGenericProjectKind;
+exports.normalizeProjectCreationFields = normalizeProjectCreationFields;
+exports.normalizeProjectCreationKind = normalizeProjectCreationKind;
+const resolve_workflow_variant_1 = require("./resolve-workflow-variant");
+/** Values that must not override a more specific legacy `kind` during resolution. */
+exports.GENERIC_PROJECT_KIND_VALUES = ['software'];
+function isGenericProjectKind(projectKind) {
+    if (projectKind === null || projectKind === undefined) {
+        return true;
+    }
+    const trimmed = projectKind.trim();
+    return trimmed.length === 0 || trimmed === 'software';
+}
+const VARIANT_TO_CREATION = {
+    software_app: {
+        kind: 'software',
+        projectKind: 'software',
+        workflowVariant: 'software_app',
+    },
+    fiction_book: {
+        kind: 'book',
+        projectKind: 'fiction',
+        workflowVariant: 'fiction_book',
+    },
+    nonfiction_book: {
+        kind: 'book',
+        /** Live DB check allows `nonfiction`; `book` requires migration 20260601180000. */
+        projectKind: 'nonfiction',
+        workflowVariant: 'nonfiction_book',
+    },
+    research_report: {
+        kind: 'technical_report',
+        projectKind: 'research',
+        workflowVariant: 'research_report',
+    },
+    scientific_paper: {
+        kind: 'scientific_paper',
+        projectKind: 'research',
+        workflowVariant: 'scientific_paper',
+    },
+    policy_framework: {
+        kind: 'white_paper',
+        projectKind: 'research',
+        workflowVariant: 'policy_framework',
+    },
+    screenplay: {
+        kind: 'book',
+        projectKind: 'fiction',
+        workflowVariant: 'screenplay',
+    },
+    movie_package: {
+        kind: 'book',
+        projectKind: 'fiction',
+        workflowVariant: 'movie_package',
+    },
+    audiobook: {
+        kind: 'book',
+        projectKind: 'nonfiction',
+        workflowVariant: 'audiobook',
+    },
+    documentary: {
+        kind: 'book',
+        projectKind: 'documentary',
+        workflowVariant: 'documentary',
+    },
+    film_production: {
+        kind: 'software',
+        projectKind: 'film',
+        workflowVariant: 'film_production',
+    },
+    cross_channel_transformation: {
+        kind: 'software',
+        projectKind: 'software',
+        workflowVariant: 'cross_channel_transformation',
+    },
+};
+/** Selector from UI or API — WorkflowKind string or explicit WorkflowVariant. */
+/** Workflow kinds exposed on /projects/new (non-experimental only). */
+exports.PRODUCTION_CREATE_WORKFLOW_KINDS = [
+    'software',
+    'book',
+    'fiction',
+    'nonfiction',
+    'film',
+    'technical_report',
+];
+function normalizeFromSelector(selector) {
+    if ((0, resolve_workflow_variant_1.isValidWorkflowVariant)(selector)) {
+        return VARIANT_TO_CREATION[selector];
+    }
+    switch (selector) {
+        case 'software':
+            return VARIANT_TO_CREATION.software_app;
+        case 'book':
+            return VARIANT_TO_CREATION.nonfiction_book;
+        case 'fiction':
+            return VARIANT_TO_CREATION.fiction_book;
+        case 'nonfiction':
+            return VARIANT_TO_CREATION.nonfiction_book;
+        case 'film':
+            return VARIANT_TO_CREATION.film_production;
+        case 'technical_report':
+            return VARIANT_TO_CREATION.research_report;
+        case 'scientific_paper':
+            return VARIANT_TO_CREATION.scientific_paper;
+        case 'research_brief':
+            return VARIANT_TO_CREATION.research_report;
+        case 'white_paper':
+            return VARIANT_TO_CREATION.nonfiction_book;
+        case 'philosophical_manuscript':
+            return VARIANT_TO_CREATION.nonfiction_book;
+        default: {
+            const mapped = resolve_workflow_variant_1.LEGACY_KIND_TO_WORKFLOW_VARIANT[selector];
+            if (mapped !== undefined) {
+                return VARIANT_TO_CREATION[mapped];
+            }
+            return VARIANT_TO_CREATION.software_app;
+        }
+    }
+}
+/**
+ * Normalize partial or legacy create payloads into a canonical DB-safe tuple.
+ */
+function normalizeProjectCreationFields(input) {
+    const workflowVariantRaw = typeof input.workflowVariant === 'string' ? input.workflowVariant.trim() : '';
+    if (workflowVariantRaw.length > 0 && (0, resolve_workflow_variant_1.isValidWorkflowVariant)(workflowVariantRaw)) {
+        return VARIANT_TO_CREATION[workflowVariantRaw];
+    }
+    const projectKindRaw = typeof input.projectKind === 'string' ? input.projectKind.trim() : '';
+    if (projectKindRaw.length > 0 && !isGenericProjectKind(projectKindRaw)) {
+        if (projectKindRaw === 'film') {
+            return VARIANT_TO_CREATION.film_production;
+        }
+        if (projectKindRaw === 'book') {
+            return VARIANT_TO_CREATION.nonfiction_book;
+        }
+        const mapped = resolve_workflow_variant_1.LEGACY_KIND_TO_WORKFLOW_VARIANT[projectKindRaw];
+        if (mapped !== undefined) {
+            return VARIANT_TO_CREATION[mapped];
+        }
+    }
+    const kindRaw = typeof input.kind === 'string' ? input.kind.trim() : '';
+    if (kindRaw.length > 0) {
+        return normalizeFromSelector(kindRaw);
+    }
+    return VARIANT_TO_CREATION.software_app;
+}
+/** Convenience for /projects/new — defaults book → nonfiction_book until fiction/nonfiction picker ships. */
+function normalizeProjectCreationKind(selector, _subtype) {
+    return normalizeProjectCreationFields({ kind: selector });
+}

package/dist/workflow/resolve-workflow-variant.d.ts

@@ -0,0 +1,42 @@
+/**
+ * resolveWorkflowVariant — canonical resolver that converts a project record into a WorkflowVariant.
+ *
+ * Priority:
+ *   1. workflow_variant if present and valid
+ *   2. film project_kind / legacy kind → film_production
+ *   3. specific legacy kind (screenplay, movie_package, policy_framework, audiobook, …)
+ *      — the generic `book` alias defers to a more specific non-generic project_kind
+ *   4. project_kind when non-generic (not default software)
+ *   5. legacy `book` + generic project_kind → nonfiction_book
+ *   6. 'software_app' as the safe fallback
+ *
+ * This is the ONLY place that translates project_kind / kind → WorkflowVariant.
+ * Pages, routes, orchestrators, and completion logic must call this — never branch on project_kind directly.
+ */
+import { type WorkflowVariant } from './channel-registry';
+/** Minimal project shape required for resolution — avoids coupling to full DB type. */
+export type ProjectForVariantResolution = {
+    workflow_variant?: string | null;
+    project_kind?: string | null;
+    /** Legacy kind field used in older records. */
+    kind?: string | null;
+};
+/**
+ * Maps legacy project_kind (and WorkflowKind) strings to the canonical WorkflowVariant.
+ * The project_kind is the coarse category; the variant is the precise execution spine.
+ */
+export declare const LEGACY_KIND_TO_WORKFLOW_VARIANT: Record<string, WorkflowVariant>;
+/**
+ * Resolves the canonical WorkflowVariant for a project.
+ */
+export declare function resolveWorkflowVariant(project: ProjectForVariantResolution): WorkflowVariant;
+/** Type guard — validates that a string is a known WorkflowVariant. */
+export declare function isValidWorkflowVariant(value: string): value is WorkflowVariant;
+/**
+ * Convenience wrapper for the legacy project.kind field used across older route handlers.
+ * Accepts a bare kind string (not a full project record).
+ *
+ * Also accepts a canonical WorkflowVariant string (e.g. `fiction_book`) so callers can
+ * pass `resolveWorkflowVariant(project)` through getPipelineStages without degradation.
+ */
+export declare function resolveVariantFromKind(kind: string | undefined | null): WorkflowVariant;

package/dist/workflow/resolve-workflow-variant.js

@@ -0,0 +1,101 @@
+"use strict";
+/**
+ * resolveWorkflowVariant — canonical resolver that converts a project record into a WorkflowVariant.
+ *
+ * Priority:
+ *   1. workflow_variant if present and valid
+ *   2. film project_kind / legacy kind → film_production
+ *   3. specific legacy kind (screenplay, movie_package, policy_framework, audiobook, …)
+ *      — the generic `book` alias defers to a more specific non-generic project_kind
+ *   4. project_kind when non-generic (not default software)
+ *   5. legacy `book` + generic project_kind → nonfiction_book
+ *   6. 'software_app' as the safe fallback
+ *
+ * This is the ONLY place that translates project_kind / kind → WorkflowVariant.
+ * Pages, routes, orchestrators, and completion logic must call this — never branch on project_kind directly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_KIND_TO_WORKFLOW_VARIANT = void 0;
+exports.resolveWorkflowVariant = resolveWorkflowVariant;
+exports.isValidWorkflowVariant = isValidWorkflowVariant;
+exports.resolveVariantFromKind = resolveVariantFromKind;
+const channel_registry_1 = require("./channel-registry");
+const project_kind_normalizer_1 = require("./project-kind-normalizer");
+/**
+ * Maps legacy project_kind (and WorkflowKind) strings to the canonical WorkflowVariant.
+ * The project_kind is the coarse category; the variant is the precise execution spine.
+ */
+exports.LEGACY_KIND_TO_WORKFLOW_VARIANT = {
+    // ProjectKind values (8 in DB)
+    software: 'software_app',
+    fiction: 'fiction_book',
+    nonfiction: 'nonfiction_book',
+    research: 'research_report',
+    documentary: 'documentary',
+    film: 'film_production',
+    simulation: 'software_app', // closest mapping for now
+    educational: 'nonfiction_book', // nonfiction family
+    mixed: 'nonfiction_book', // fallback to writing family
+    book: 'nonfiction_book',
+    // WorkflowKind fine-grained values (writing sub-kinds)
+    technical_report: 'research_report',
+    scientific_paper: 'scientific_paper',
+    research_brief: 'research_report',
+    white_paper: 'nonfiction_book',
+    philosophical_manuscript: 'nonfiction_book',
+    policy_framework: 'policy_framework',
+    screenplay: 'screenplay',
+    movie_package: 'movie_package',
+    audiobook: 'audiobook',
+};
+/**
+ * Resolves the canonical WorkflowVariant for a project.
+ */
+function resolveWorkflowVariant(project) {
+    const explicit = project.workflow_variant;
+    if (explicit && isValidWorkflowVariant(explicit)) {
+        return explicit;
+    }
+    const projectKind = typeof project.project_kind === 'string' ? project.project_kind.trim() : '';
+    const legacyKind = typeof project.kind === 'string' ? project.kind.trim() : '';
+    if (projectKind === 'film' || legacyKind === 'film') {
+        return 'film_production';
+    }
+    const mappedLegacy = legacyKind.length > 0 ? exports.LEGACY_KIND_TO_WORKFLOW_VARIANT[legacyKind] : undefined;
+    // Deep legacy kinds (screenplay, movie_package, policy_framework, audiobook)
+    // win over a coarse project_kind. The generic `book` alias does not — a more
+    // specific non-generic project_kind (e.g. fiction) must still map to fiction_book.
+    const bookShouldDeferToSpecificProjectKind = legacyKind === 'book' && !(0, project_kind_normalizer_1.isGenericProjectKind)(projectKind);
+    if (mappedLegacy !== undefined && !bookShouldDeferToSpecificProjectKind) {
+        return mappedLegacy;
+    }
+    if (projectKind.length > 0 && !(0, project_kind_normalizer_1.isGenericProjectKind)(projectKind)) {
+        const mappedPk = exports.LEGACY_KIND_TO_WORKFLOW_VARIANT[projectKind];
+        if (mappedPk !== undefined) {
+            return mappedPk;
+        }
+    }
+    if (legacyKind === 'book' && (0, project_kind_normalizer_1.isGenericProjectKind)(projectKind)) {
+        return 'nonfiction_book';
+    }
+    return 'software_app';
+}
+/** Type guard — validates that a string is a known WorkflowVariant. */
+function isValidWorkflowVariant(value) {
+    return channel_registry_1.WORKFLOW_VARIANTS.includes(value);
+}
+/**
+ * Convenience wrapper for the legacy project.kind field used across older route handlers.
+ * Accepts a bare kind string (not a full project record).
+ *
+ * Also accepts a canonical WorkflowVariant string (e.g. `fiction_book`) so callers can
+ * pass `resolveWorkflowVariant(project)` through getPipelineStages without degradation.
+ */
+function resolveVariantFromKind(kind) {
+    if (!kind)
+        return 'software_app';
+    if (isValidWorkflowVariant(kind))
+        return kind;
+    const mapped = exports.LEGACY_KIND_TO_WORKFLOW_VARIANT[kind];
+    return mapped ?? 'software_app';
+}

package/dist/workflow/step-id-canonical.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Canonical workflow step ID + route path normalization (#1252).
+ * Single mapper — do not duplicate alias tables elsewhere.
+ *
+ * Dual-spine contract (software_app, WF-01):
+ * - Operator nav: ~18 WORKFLOW_STEPS in `SOFTWARE_OPERATOR_NAV_STEP_IDS` (sidebar / progress).
+ * - Quality channel: 12 WORKFLOW_CHANNEL_REGISTRY steps (orchestration / Doctor artifacts).
+ * - Nav aliases below map operator keys → registry stepIds; do not collapse nav to channel count.
+ */
+/** Nav / URL keys → registry `ChannelStepDefinition.stepId`. */
+export declare const REGISTRY_WORKFLOW_STEP_ID_BY_NAV_KEY: Readonly<Record<string, string>>;
+/** Operator route paths that alias the same step page. */
+export declare const WORKFLOW_STEP_ROUTE_PATH_ALIASES: Readonly<Record<string, string>>;
+/** Map UI / nav step keys to registry `stepId` when they differ. */
+export declare function resolveRegistryWorkflowStepId(navStepKey: string): string;
+/** Normalize any workflow step key (nav, stats query, registry) to registry stepId. */
+export declare function resolveCanonicalWorkflowStepId(input: string): string;
+/** Normalize operator page routes (e.g. /workflow/review → /review). */
+export declare function resolveWorkflowStepRoutePath(routePath: string): string;
+/**
+ * Normalize step-stats query param to a supported stats id.
+ * Maps nav aliases (deployments, knowledge-graph) to schema enum values.
+ */
+export declare function normalizeWorkflowStepStatsStepId(raw: string): string;
+/** All known step-id aliases (input → canonical registry stepId). */
+export declare const WORKFLOW_STEP_ID_ALIAS_PAIRS: ReadonlyArray<readonly [string, string]>;