@topogram/cli 0.3.63 → 0.3.65

package/src/workflows/import-app/workflow.js

@@ -0,0 +1,159 @@
+// @ts-check
+import { idHintify, titleCase } from "../../text-helpers.js";
+import { scanDocsWorkflow } from "../docs.js";
+import { collectApiImport } from "./api.js";
+import { collectDbImport } from "./db.js";
+import { dedupeCandidateRecords, inferCapabilityEntityId, makeCandidateRecord } from "./shared.js";
+
+/** @param {WorkflowRecord} capability @returns {any} */
+function workflowEntityIdForCapability(capability) {
+  return inferCapabilityEntityId(capability);
+}
+
+/** @param {WorkflowRecord} entity @param {any} enumCandidatesById @returns {any} */
+function findEntityStatusFields(entity, enumCandidatesById) {
+  return (entity?.fields || []).filter((/** @type {any} */ field) =>
+    ["status", "state"].includes(field.name) && enumCandidatesById.has(idHintify(field.field_type))
+  );
+}
+
+/** @param {WorkflowRecord} capability @param {any[]} knownStates @returns {any} */
+function targetStateForCapability(capability, knownStates) {
+  if (capability.target_state) {
+    const explicitState = idHintify(capability.target_state);
+    if (knownStates.length === 0 || knownStates.includes(explicitState)) {
+      return explicitState;
+    }
+  }
+  const id = capability.id_hint || "";
+  const method = String(capability.endpoint?.method || "").toUpperCase();
+  const candidates = [
+    ["sign_in", "authenticated"],
+    ["login", "authenticated"],
+    ["authenticate", "authenticated"],
+    ["register", "registered"],
+    ["approve", "approved"],
+    ["reject", "rejected"],
+    ["revision", "needs_revision"],
+    ["request_revision", "needs_revision"],
+    ["submit", "submitted"],
+    ["close", "closed"],
+    ["complete", "completed"],
+    ["archive", "archived"],
+    ["delete", "deleted"],
+    [method === "POST" && id.startsWith("cap_create_") ? "create" : "", knownStates[0] || "created"]
+  ].filter((/** @type {any} */ [needle]) => needle);
+  for (const [needle, state] of candidates) {
+    if (id.includes(needle) && state) {
+      const canonicalState = idHintify(state);
+      if (knownStates.length === 0 || knownStates.includes(canonicalState)) {
+        return canonicalState;
+      }
+    }
+  }
+  return null;
+}
+
+/** @param {WorkspacePaths} paths @returns {any} */
+export function collectWorkflowImport(paths) {
+  /** @type {any[]} */
+  const findings = [];
+  /** @type {WorkflowRecord} */
+  const candidates = {
+    workflows: [],
+    workflow_states: [],
+    workflow_transitions: []
+  };
+  const dbImport = collectDbImport(paths);
+  const apiImport = collectApiImport(paths);
+  const docScan = scanDocsWorkflow(paths.topogramRoot).summary;
+  const enumCandidatesById = new Map((dbImport.candidates.enums || []).map((/** @type {any} */ entry) => [entry.id_hint, entry]));
+  const entityCandidatesById = new Map((dbImport.candidates.entities || []).map((/** @type {any} */ entry) => [entry.id_hint, entry]));
+  const workflowDocs = (docScan.candidate_docs || []).filter((/** @type {any} */ doc) => doc.kind === "workflow");
+  const workflows = new Map();
+
+  for (const capability of apiImport.candidates.capabilities || []) {
+    const entityId = workflowEntityIdForCapability(capability);
+    const workflowId = `workflow_${entityId.replace(/^entity_/, "")}`;
+    const capabilityActors =
+      capability.auth_hint === "secured" ? ["user"] :
+      capability.auth_hint === "public" ? ["anonymous"] :
+      [];
+    if (!workflows.has(workflowId)) {
+      const entity = entityCandidatesById.get(entityId);
+      const statusFields = findEntityStatusFields(entity, enumCandidatesById);
+      const states = statusFields.flatMap((/** @type {any} */ field) => enumCandidatesById.get(idHintify(field.field_type))?.values || []).map(idHintify);
+      workflows.set(workflowId, {
+        workflow: makeCandidateRecord({
+          kind: "workflow",
+          idHint: workflowId,
+          label: `${titleCase(entityId.replace(/^entity_/, ""))} Workflow`,
+          confidence: "medium",
+          sourceKind: "generated_artifact",
+          provenance: capability.provenance || [],
+          track: "workflows",
+          entity_id: entityId,
+          actor_hints: capabilityActors,
+          related_capabilities: []
+        }),
+        states: states.map((/** @type {any} */ state) =>
+          makeCandidateRecord({
+            kind: "workflow_state",
+            idHint: `${workflowId}_${state}`,
+            label: titleCase(state),
+            confidence: "medium",
+            sourceKind: "schema",
+            provenance: entity?.provenance || capability.provenance || [],
+            track: "workflows",
+            workflow_id: workflowId,
+            entity_id: entityId,
+            state_id: state
+          })
+        ),
+        transitions: []
+      });
+    }
+    const workflow = workflows.get(workflowId);
+    workflow.workflow.related_capabilities.push(capability.id_hint);
+    workflow.workflow.actor_hints = [...new Set([...(workflow.workflow.actor_hints || []), ...capabilityActors])].sort();
+    const knownStates = workflow.states.map((/** @type {any} */ entry) => entry.state_id);
+    const targetState = targetStateForCapability(capability, knownStates);
+    if (targetState) {
+      workflow.transitions.push(
+        makeCandidateRecord({
+          kind: "workflow_transition",
+          idHint: `${workflowId}_${idHintify(capability.id_hint)}`,
+          label: titleCase(capability.id_hint.replace(/^cap_/, "")),
+          confidence: "low",
+          sourceKind: capability.source_kind || "generated_artifact",
+          provenance: capability.provenance || [],
+          track: "workflows",
+          workflow_id: workflowId,
+          entity_id: entityId,
+          capability_id: capability.id_hint,
+          actor_hints: capabilityActors,
+          to_state: targetState
+        })
+      );
+    }
+  }
+
+  for (const workflow of workflows.values()) {
+    workflow.workflow.related_capabilities = [...new Set(workflow.workflow.related_capabilities)].sort();
+    candidates.workflows.push(workflow.workflow);
+    candidates.workflow_states.push(...workflow.states);
+    candidates.workflow_transitions.push(...workflow.transitions);
+  }
+
+  findings.push({
+    kind: "workflow_inference",
+    workflow_count: candidates.workflows.length,
+    workflow_doc_signals: workflowDocs.map((/** @type {any} */ doc) => doc.id)
+  });
+
+  candidates.workflows = dedupeCandidateRecords(candidates.workflows, (/** @type {any} */ record) => record.id_hint);
+  candidates.workflow_states = dedupeCandidateRecords(candidates.workflow_states, (/** @type {any} */ record) => record.id_hint);
+  candidates.workflow_transitions = dedupeCandidateRecords(candidates.workflow_transitions, (/** @type {any} */ record) => record.id_hint);
+
+  return { findings, candidates };
+}

package/src/workflows/reconcile/adoption-plan/build.js

@@ -0,0 +1,208 @@
+// @ts-check
+
+import { adoptionItemKey } from "../../../adoption/plan.js";
+import { confidenceRank } from "../../docs.js";
+import {
+  adoptionStatusForStep,
+  blockingDependenciesForProjectionImpacts,
+  blockingDependenciesForUiImpacts,
+  blockingDependenciesForWorkflowImpacts,
+  projectionImpactsForAdoptionItem
+} from "./dependencies.js";
+import {
+  canonicalDisplayPathForItem,
+  canonicalRelativePathForItem,
+  candidateSourcePathForItem
+} from "./paths.js";
+import {
+  reasonForAdoptionItem,
+  recommendationForAdoptionItem
+} from "./reasons.js";
+
+/** @param {CandidateBundle[]} bundles @returns {any} */
+export function buildAdoptionPlan(bundles) {
+  /** @type {any[]} */
+  const items = [];
+  for (const bundle of bundles) {
+    for (const step of bundle.adoptionPlan || []) {
+      const itemKind =
+        step.action === "merge_bundle_into_existing_entity" ? "bundle" :
+        step.action === "apply_projection_permission_patch" ? "projection_permission_patch" :
+        step.action === "apply_projection_auth_patch" ? "projection_auth_patch" :
+        step.action === "apply_projection_ownership_patch" ? "projection_ownership_patch" :
+        step.action.includes("doc") ? "doc" :
+        step.action.includes("decision") ? "decision" :
+        step.action.includes("verification") ? "verification" :
+        step.action.includes("widget") ? "widget" :
+        step.action.includes("ui_") ? "ui" :
+        step.action.includes("actor") ? "actor" :
+        step.action.includes("role") ? "role" :
+        step.action.includes("enum") ? "enum" :
+        step.action.includes("shape") ? "shape" :
+        step.action.includes("capability") ? "capability" :
+        step.action.includes("entity") ? "entity" :
+        "bundle";
+      if (itemKind === "bundle") {
+        continue;
+      }
+      const projectionImpacts = projectionImpactsForAdoptionItem(bundle, step);
+      const directProjectionBlockingDependencies =
+        (step.action === "apply_projection_permission_patch" || step.action === "apply_projection_auth_patch" || step.action === "apply_projection_ownership_patch") && step.target
+          ? blockingDependenciesForProjectionImpacts([
+              {
+                projection_id: step.target,
+                kind: step.projection_kind || "api",
+                projection_type: null,
+                reason: `Projection ${step.target} auth rules need explicit review before promotion.`
+              }
+            ])
+          : [];
+      const uiImpacts = step.action.includes("ui_") ? bundle.uiImpacts || [] : [];
+      const workflowImpacts = step.action.includes("workflow") ? bundle.workflowImpacts || [] : [];
+      const blockingDependencies = [
+        ...blockingDependenciesForProjectionImpacts(projectionImpacts),
+        ...directProjectionBlockingDependencies,
+        ...blockingDependenciesForUiImpacts(uiImpacts),
+        ...blockingDependenciesForWorkflowImpacts(workflowImpacts)
+      ];
+      items.push({
+        bundle: bundle.slug,
+        item: step.item,
+        kind: itemKind,
+        track:
+          step.action.includes("workflow") ? "workflows" :
+          step.action.includes("verification") ? "verification" :
+          step.action.includes("ui_") ? "ui" :
+          step.action === "apply_projection_permission_patch" ? "projection" :
+          step.action === "apply_projection_auth_patch" ? "projection" :
+          step.action === "apply_projection_ownership_patch" ? "projection" :
+          step.action.includes("doc") ? "docs" :
+          itemKind,
+        suggested_action: step.action,
+        target: step.target || null,
+        confidence: step.confidence || null,
+        inference_summary: step.inference_summary || null,
+        related_docs: step.related_docs || [],
+        related_capabilities: step.related_capabilities || [],
+        permission: step.permission || null,
+        claim: step.claim || null,
+        claim_value: Object.prototype.hasOwnProperty.call(step, "claim_value") ? step.claim_value : null,
+        ownership: step.ownership || null,
+        ownership_field: step.ownership_field || null,
+        projection_surface: step.projection_surface || null,
+        status: adoptionStatusForStep(step, projectionImpacts, uiImpacts, workflowImpacts),
+        source_path: step.source_path || candidateSourcePathForItem(bundle, itemKind, step.item),
+        canonical_path:
+          step.action === "skip_duplicate_shape"
+            ? (step.target ? canonicalDisplayPathForItem("shape", step.target) : null)
+            : (step.canonical_rel_path ? `topogram/${step.canonical_rel_path}` : canonicalDisplayPathForItem(itemKind, step.item)),
+        canonical_rel_path: step.canonical_rel_path || canonicalRelativePathForItem(itemKind, step.item),
+        reason: reasonForAdoptionItem(step),
+        recommendation: recommendationForAdoptionItem(step),
+        projection_impacts: projectionImpacts,
+        ui_impacts: uiImpacts,
+        workflow_impacts: workflowImpacts,
+        blocking_dependencies: blockingDependencies
+      });
+    }
+    for (const patch of bundle.projectionPatches || []) {
+      items.push({
+        bundle: bundle.slug,
+        item: `projection_patch:${patch.projection_id}`,
+        kind: "projection_patch",
+        track: "projection",
+        suggested_action: "review_projection_patch",
+        target: patch.projection_id,
+        status: "needs_projection_review",
+        source_path: `candidates/reconcile/model/bundles/${bundle.slug}/${patch.patch_rel_path}`,
+        canonical_path: null,
+        canonical_rel_path: null,
+        reason: patch.reason || `Projection ${patch.projection_id} needs additive review.`,
+        projection_impacts: [
+          {
+            projection_id: patch.projection_id,
+            kind: patch.kind,
+            projection_type: patch.projection_type,
+            missing_capabilities: patch.missing_realizes || []
+          }
+        ],
+        ui_impacts: (patch.missing_screens || []).length > 0 ? [
+          {
+            projection_id: patch.projection_id,
+            kind: patch.kind,
+            projection_type: patch.projection_type,
+            missing_screens: patch.missing_screens || []
+          }
+        ] : [],
+        workflow_impacts: [],
+        blocking_dependencies: blockingDependenciesForProjectionImpacts([
+          {
+            projection_id: patch.projection_id,
+            kind: patch.kind,
+            projection_type: patch.projection_type,
+            reason: patch.reason || `Projection ${patch.projection_id} needs additive review.`
+          }
+        ])
+      });
+    }
+    for (const patch of bundle.docLinkSuggestions || []) {
+      items.push({
+        bundle: bundle.slug,
+        item: `doc_link_patch:${patch.doc_id}`,
+        kind: "doc_link_patch",
+        track: "docs",
+        suggested_action: "apply_doc_link_patch",
+        target: patch.doc_id,
+        status: "pending",
+        source_path: `candidates/reconcile/model/bundles/${bundle.slug}/${patch.patch_rel_path}`,
+        canonical_path: patch.canonical_rel_path ? `topogram/${patch.canonical_rel_path}` : null,
+        canonical_rel_path: patch.canonical_rel_path || null,
+        reason: `Apply suggested related actor/role links to \`${patch.doc_id}\`.`,
+        recommendation: recommendationForAdoptionItem({ action: "apply_doc_link_patch", target: patch.doc_id }),
+        related_docs: [patch.doc_id],
+        related_actors: patch.add_related_actors || [],
+        related_roles: patch.add_related_roles || [],
+        related_capabilities: patch.add_related_capabilities || [],
+        related_rules: patch.add_related_rules || [],
+        related_workflows: patch.add_related_workflows || [],
+        projection_impacts: [],
+        ui_impacts: [],
+        workflow_impacts: [],
+        blocking_dependencies: []
+      });
+    }
+    for (const patch of bundle.docMetadataPatches || []) {
+      items.push({
+        bundle: bundle.slug,
+        item: `doc_metadata_patch:${patch.doc_id}`,
+        kind: "doc_metadata_patch",
+        track: "docs",
+        suggested_action: "apply_doc_metadata_patch",
+        target: patch.doc_id,
+        status: "pending",
+        confidence: patch.imported_confidence || "low",
+        source_path: `candidates/reconcile/model/bundles/${bundle.slug}/${patch.patch_rel_path}`,
+        canonical_path: patch.canonical_rel_path ? `topogram/${patch.canonical_rel_path}` : null,
+        canonical_rel_path: patch.canonical_rel_path || null,
+        reason: `Apply suggested safe metadata updates to \`${patch.doc_id}\`.`,
+        recommendation: recommendationForAdoptionItem({ action: "apply_doc_metadata_patch", target: patch.doc_id }),
+        related_docs: [patch.doc_id],
+        summary: patch.summary || null,
+        success_outcome: patch.success_outcome || null,
+        actors: patch.actors || [],
+        projection_impacts: [],
+        ui_impacts: [],
+        workflow_impacts: [],
+        blocking_dependencies: []
+      });
+    }
+  }
+  return items.sort((/** @type {any} */ a, /** @type {any} */ b) =>
+    a.bundle.localeCompare(b.bundle) ||
+    confidenceRank(b.confidence || "low") - confidenceRank(a.confidence || "low") ||
+    a.kind.localeCompare(b.kind) ||
+    a.item.localeCompare(b.item)
+  );
+}
+
+export const ADOPT_SELECTORS = new Set(["from-plan", "actors", "roles", "enums", "shapes", "entities", "capabilities", "widgets", "docs", "journeys", "workflows", "verification", "ui"]);

package/src/workflows/reconcile/adoption-plan/dependencies.js

@@ -0,0 +1,75 @@
+// @ts-check
+
+/** @param {WorkflowRecord} step @param {any[]} projectionImpacts @param {any[]} uiImpacts @param {any[]} workflowImpacts @returns {any} */
+export function adoptionStatusForStep(step, projectionImpacts = [], uiImpacts = [], workflowImpacts = []) {
+  if (step.action === "skip_duplicate_shape") {
+    return "skipped";
+  }
+  if (step.action === "apply_projection_permission_patch") {
+    return "needs_projection_review";
+  }
+  if (step.action === "apply_projection_auth_patch") {
+    return "needs_projection_review";
+  }
+  if (step.action === "apply_projection_ownership_patch") {
+    return "needs_projection_review";
+  }
+  if (step.action.includes("capability") && projectionImpacts.length > 0) {
+    return "needs_projection_review";
+  }
+  if (step.action.includes("ui_") && uiImpacts.length > 0) {
+    return "needs_ui_review";
+  }
+  if (step.action.includes("workflow") && workflowImpacts.length > 0) {
+    return "needs_workflow_review";
+  }
+  return "pending";
+}
+
+/** @param {CandidateBundle} bundle @param {WorkflowRecord} step @returns {any} */
+export function projectionImpactsForAdoptionItem(bundle, step) {
+  if (!step.action.includes("capability")) {
+    return [];
+  }
+  return (bundle.projectionImpacts || [])
+    .filter((/** @type {any} */ impact) => (impact.missing_capabilities || []).includes(step.item))
+    .map((/** @type {any} */ impact) => ({
+      projection_id: impact.projection_id,
+      kind: impact.kind,
+      projection_type: impact.projection_type,
+      reason: impact.reason
+    }));
+}
+
+/** @param {any[]} projectionImpacts @returns {any} */
+export function blockingDependenciesForProjectionImpacts(projectionImpacts) {
+  return projectionImpacts.map((/** @type {any} */ impact) => ({
+    type: "projection_review",
+    id: `projection_review:${impact.projection_id}`,
+    projection_id: impact.projection_id,
+    kind: impact.kind,
+    projection_type: impact.projection_type,
+    reason: impact.reason
+  }));
+}
+
+/** @param {any[]} uiImpacts @returns {any} */
+export function blockingDependenciesForUiImpacts(uiImpacts) {
+  return uiImpacts.map((/** @type {any} */ impact) => ({
+    type: "ui_review",
+    id: `ui_review:${impact.projection_id}`,
+    projection_id: impact.projection_id,
+    kind: impact.kind,
+    projection_type: impact.projection_type,
+    reason: impact.reason
+  }));
+}
+
+/** @param {any[]} workflowImpacts @returns {any} */
+export function blockingDependenciesForWorkflowImpacts(workflowImpacts) {
+  return workflowImpacts.map((/** @type {any} */ impact) => ({
+    type: "workflow_review",
+    id: impact.review_group_id,
+    reason: impact.reason
+  }));
+}

package/src/workflows/reconcile/adoption-plan/outputs.js

@@ -0,0 +1,143 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { adoptionItemKey } from "../../../adoption/plan.js";
+import {
+  applyDocLinkPatchToMarkdown as applyDocLinkPatchToMarkdownReconcile,
+  applyDocMetadataPatchToMarkdown as applyDocMetadataPatchToMarkdownReconcile
+} from "../../../reconcile/docs.js";
+import { readJsonIfExists, readTextIfExists } from "../../shared.js";
+import { canonicalRelativePathForItem } from "./paths.js";
+import { applyProjectionAuthPatchToTopogram } from "./projection-patches.js";
+
+/** @param {WorkspacePaths} paths @returns {any} */
+export function readAdoptionPlan(paths) {
+  return readJsonIfExists(path.join(paths.topogramRoot, "candidates", "reconcile", "adoption-plan.json"));
+}
+
+/** @param {WorkspacePaths} paths @param {any[]} candidateFiles @param {any[]} planItems @param {any[]} selectedItems @param {WorkflowOptions} options @returns {any} */
+export function buildCanonicalAdoptionOutputs(paths, candidateFiles, planItems, selectedItems, options = {}) {
+  const refreshAdopted = Boolean(options.refreshAdopted);
+  /** @type {WorkflowFiles} */
+  /** @type {WorkflowFiles} */
+  const files = {};
+  /** @type {any[]} */
+  const refreshedFiles = [];
+  const selectedSet = new Set(selectedItems);
+  const itemMap = new Map(planItems.map((/** @type {any} */ item) => [adoptionItemKey(item), item]));
+  const capabilityBundleSet = new Set(
+    [...selectedSet]
+      .map((/** @type {any} */ key) => itemMap.get(key))
+      .filter((/** @type {any} */ item) => item?.kind === "capability")
+      .map((/** @type {any} */ item) => item.bundle)
+  );
+  for (const item of planItems) {
+    if (item.kind === "shape" && item.status !== "skipped" && capabilityBundleSet.has(item.bundle)) {
+      selectedSet.add(adoptionItemKey(item));
+    }
+  }
+  for (const item of planItems) {
+    if (!selectedSet.has(adoptionItemKey(item))) {
+      continue;
+    }
+    if (item.suggested_action === "skip_duplicate_shape") {
+      continue;
+    }
+    const relativeCanonicalPath = item.canonical_rel_path || canonicalRelativePathForItem(item.kind, item.item);
+    if (!relativeCanonicalPath) {
+      continue;
+    }
+    const canonicalPath = path.join(paths.topogramRoot, relativeCanonicalPath);
+    if (item.suggested_action === "apply_doc_link_patch") {
+      const baseContents = files[relativeCanonicalPath] || (fs.existsSync(canonicalPath) ? fs.readFileSync(canonicalPath, "utf8") : null);
+      if (!baseContents) {
+        continue;
+      }
+      const updatedContents = applyDocLinkPatchToMarkdownReconcile(baseContents, item);
+      if (!updatedContents || updatedContents === baseContents) {
+        continue;
+      }
+      files[relativeCanonicalPath] = updatedContents;
+      refreshedFiles.push(relativeCanonicalPath.replaceAll(path.sep, "/"));
+      continue;
+    }
+    if (item.suggested_action === "apply_doc_metadata_patch") {
+      const baseContents = files[relativeCanonicalPath] || (fs.existsSync(canonicalPath) ? fs.readFileSync(canonicalPath, "utf8") : null);
+      if (!baseContents) {
+        continue;
+      }
+      const updatedContents = applyDocMetadataPatchToMarkdownReconcile(baseContents, item);
+      if (!updatedContents || updatedContents === baseContents) {
+        continue;
+      }
+      files[relativeCanonicalPath] = updatedContents;
+      refreshedFiles.push(relativeCanonicalPath.replaceAll(path.sep, "/"));
+      continue;
+    }
+    if (item.suggested_action === "apply_projection_permission_patch" || item.suggested_action === "apply_projection_auth_patch" || item.suggested_action === "apply_projection_ownership_patch") {
+      const baseContents = files[relativeCanonicalPath] || (fs.existsSync(canonicalPath) ? fs.readFileSync(canonicalPath, "utf8") : null);
+      if (!baseContents) {
+        continue;
+      }
+      const updatedContents = applyProjectionAuthPatchToTopogram(baseContents, item);
+      if (!updatedContents || updatedContents === baseContents) {
+        continue;
+      }
+      files[relativeCanonicalPath] = updatedContents;
+      refreshedFiles.push(relativeCanonicalPath.replaceAll(path.sep, "/"));
+      continue;
+    }
+    if (fs.existsSync(canonicalPath)) {
+      if (!refreshAdopted) {
+        continue;
+      }
+      const existingContents = fs.readFileSync(canonicalPath, "utf8");
+      const machineManagedImported =
+        existingContents.startsWith("# imported ") ||
+        /\bsource_of_truth:\s*imported\b/.test(existingContents);
+      if (!machineManagedImported) {
+        continue;
+      }
+    }
+    const candidateContents =
+      candidateFiles[item.source_path] ||
+      (item.source_path ? readTextIfExists(path.join(paths.topogramRoot, item.source_path)) : null);
+    if (!candidateContents) {
+      continue;
+    }
+    files[relativeCanonicalPath] = candidateContents;
+    if (fs.existsSync(canonicalPath)) {
+      refreshedFiles.push(relativeCanonicalPath.replaceAll(path.sep, "/"));
+    }
+  }
+  return { files, refreshedFiles: [...new Set(refreshedFiles)].sort() };
+}
+
+/** @param {any[]} planItems @param {any[]} selectedItems @param {any[]} writtenCanonicalFiles @param {string} selector @returns {any} */
+export function buildPromotedCanonicalItems(planItems, selectedItems, writtenCanonicalFiles, selector) {
+  const itemMap = new Map((planItems || []).map((/** @type {any} */ item) => [adoptionItemKey(item), item]));
+  const writtenSet = new Set((writtenCanonicalFiles || []).map((/** @type {any} */ item) => String(item).replaceAll(path.sep, "/")));
+  return [...new Set(selectedItems || [])]
+    .map((/** @type {any} */ key) => itemMap.get(key))
+    .filter(Boolean)
+    .filter((/** @type {any} */ item) => item.canonical_rel_path && writtenSet.has(String(item.canonical_rel_path).replaceAll(path.sep, "/")))
+    .map((/** @type {any} */ item) => ({
+      selector: selector || null,
+      bundle: item.bundle,
+      item: item.item,
+      kind: item.kind,
+      track: item.track || null,
+      source_path: item.source_path || null,
+      canonical_rel_path: String(item.canonical_rel_path).replaceAll(path.sep, "/"),
+      canonical_path: item.canonical_path || `topogram/${String(item.canonical_rel_path).replaceAll(path.sep, "/")}`,
+      suggested_action: item.suggested_action || null
+    }))
+    .sort((/** @type {any} */ a, /** @type {any} */ b) =>
+      (a.bundle || "").localeCompare(b.bundle || "") ||
+      (a.track || "").localeCompare(b.track || "") ||
+      (a.kind || "").localeCompare(b.kind || "") ||
+      (a.item || "").localeCompare(b.item || "")
+    );
+}

package/src/workflows/reconcile/adoption-plan/paths.js

@@ -0,0 +1,58 @@
+// @ts-check
+
+import { dashedTopogramId } from "../ids.js";
+
+/** @param {string} kind @param {string} item @returns {any} */
+export function canonicalRelativePathForItem(kind, item) {
+  switch (kind) {
+    case "actor":
+      return `actors/${dashedTopogramId(item)}.tg`;
+    case "role":
+      return `roles/${dashedTopogramId(item)}.tg`;
+    case "enum":
+      return `enums/enum-${dashedTopogramId(String(item || "").replace(/^enum_/, ""))}.tg`;
+    case "entity":
+      return `entities/${dashedTopogramId(item)}.tg`;
+    case "shape":
+      return `shapes/${dashedTopogramId(item)}.tg`;
+    case "capability":
+      return `capabilities/${dashedTopogramId(item)}.tg`;
+    case "widget":
+      return `widgets/${dashedTopogramId(item)}.tg`;
+    case "verification":
+      return `verifications/${dashedTopogramId(item)}.tg`;
+    default:
+      return null;
+  }
+}
+
+/** @param {string} kind @param {string} item @returns {any} */
+export function canonicalDisplayPathForItem(kind, item) {
+  const relativePath = canonicalRelativePathForItem(kind, item);
+  return relativePath ? `topogram/${relativePath}` : null;
+}
+
+/** @param {CandidateBundle} bundle @param {string} kind @param {WorkflowRecord} item @returns {any} */
+export function candidateSourcePathForItem(bundle, kind, item) {
+  const base = `candidates/reconcile/model/bundles/${bundle.slug}`;
+  switch (kind) {
+    case "actor":
+      return `${base}/actors/${item}.tg`;
+    case "role":
+      return `${base}/roles/${item}.tg`;
+    case "enum":
+      return `${base}/enums/${item}.tg`;
+    case "entity":
+      return `${base}/entities/${item}.tg`;
+    case "shape":
+      return `${base}/shapes/${item}.tg`;
+    case "capability":
+      return `${base}/capabilities/${item}.tg`;
+    case "widget":
+      return `${base}/widgets/${item}.tg`;
+    case "verification":
+      return `${base}/verifications/${item}.tg`;
+    default:
+      return `${base}/README.md`;
+  }
+}