thursday-agent 0.4.0 → 0.6.0

package/skills/interactive-page/scripts/archify/examples/product-analytics.dataflow.json

@@ -0,0 +1,76 @@
+{
+  "schema_version": 1,
+  "diagram_type": "dataflow",
+  "meta": {
+    "title": "Product Analytics Data Flow",
+    "output": "examples/dataflow-product-analytics.html",
+    "viewBox": [1080, 520],
+    "animation": "trace",
+    "quality_profile": "showcase",
+    "views": [
+      { "id": "collection-path", "label": "Collection path", "focus": ["web", "mobile", "edge", "stream"], "note": "Follow product events from clients into the ordered event stream." },
+      { "id": "consent-boundary", "label": "Consent and PII", "focus": ["edge", "consent", "pii"], "note": "Isolate the policy gate and restricted identity store." },
+      { "id": "analytics-consumers", "label": "Curated consumers", "focus": ["stream", "warehouse", "dashboard", "features", "model"], "note": "See curated facts, dashboards, and the derived feature path." }
+    ]
+  },
+  "stages": [
+    { "label": "Sources" },
+    { "label": "Ingest" },
+    { "label": "Process" },
+    { "label": "Store" },
+    { "label": "Consume" }
+  ],
+  "nodes": [
+    { "id": "web", "type": "frontend", "label": "Web App", "sublabel": "browser SDK", "stage": 0, "row": 0, "tag": "events" },
+    { "id": "mobile", "type": "frontend", "label": "Mobile", "sublabel": "iOS / Android", "stage": 0, "row": 2, "tag": "events" },
+    { "id": "edge", "type": "cloud", "label": "Edge API", "sublabel": "collector", "stage": 1, "row": 1, "tag": "TLS" },
+    { "id": "consent", "type": "security", "label": "Consent Gate", "sublabel": "policy filter", "stage": 2, "row": 0, "tag": "PII guard" },
+    { "id": "stream", "type": "messagebus", "label": "Event Stream", "sublabel": "Kafka topic", "stage": 2, "row": 2, "tag": "ordered" },
+    { "id": "pii", "type": "security", "label": "PII Vault", "sublabel": "encrypted", "stage": 3, "row": 0, "tag": "restricted" },
+    { "id": "warehouse", "type": "database", "label": "Warehouse", "sublabel": "analytics tables", "stage": 3, "row": 1, "tag": "curated" },
+    { "id": "features", "type": "database", "label": "Feature Store", "sublabel": "daily batch", "stage": 3, "row": 2, "tag": "derived" },
+    { "id": "dashboard", "type": "backend", "label": "Dashboards", "sublabel": "product metrics", "stage": 4, "row": 0, "tag": "SQL" },
+    { "id": "model", "type": "backend", "label": "ML Model", "sublabel": "ranking job", "stage": 4, "row": 2, "tag": "features" }
+  ],
+  "flows": [
+    { "id": "web-clickstream", "from": "web", "to": "edge", "label": "clickstream", "classification": "user events", "variant": "emphasis", "fromSide": "right", "toSide": "left", "via": [[205, 157], [205, 271]], "labelAt": [204, 190] },
+    { "id": "mobile-events", "from": "mobile", "to": "edge", "label": "app events", "classification": "device events", "variant": "default", "fromSide": "right", "toSide": "left", "via": [[222, 385], [222, 271]], "labelAt": [220, 342] },
+    { "id": "consent-enrichment", "from": "edge", "to": "consent", "label": "identity + consent", "classification": "PII touch", "variant": "security", "fromSide": "top", "toSide": "left", "via": [[315, 112], [450, 112], [450, 157]], "labelAt": [382, 100] },
+    { "id": "accepted-events", "from": "edge", "to": "stream", "label": "accepted events", "classification": "append-only", "variant": "emphasis", "fromSide": "right", "toSide": "left", "via": [[420, 271], [420, 385]], "labelAt": [438, 324] },
+    { "id": "identity-map", "from": "consent", "to": "pii", "label": "identity map", "classification": "encrypted PII", "variant": "security", "route": "straight", "labelAt": [638, 144] },
+    { "id": "normalized-facts", "from": "stream", "to": "warehouse", "label": "normalized facts", "classification": "non-PII", "variant": "emphasis", "fromSide": "right", "toSide": "left", "via": [[638, 385], [638, 271]], "labelAt": [638, 326] },
+    { "id": "daily-aggregates", "from": "warehouse", "to": "features", "label": "daily aggregates", "classification": "batch", "variant": "dashed", "fromSide": "bottom", "toSide": "top", "route": "straight", "labelAt": [745, 326] },
+    { "id": "metrics-query", "from": "warehouse", "to": "dashboard", "label": "metrics SQL", "classification": "read-only", "variant": "default", "fromSide": "right", "toSide": "bottom", "via": [[852, 271], [960, 271]], "labelAt": [876, 258] },
+    { "id": "feature-vectors", "from": "features", "to": "model", "label": "feature vectors", "classification": "derived", "variant": "dashed", "route": "straight", "labelAt": [852, 372] },
+    { "id": "restricted-join", "from": "pii", "to": "dashboard", "label": "restricted join", "classification": "approved only", "variant": "security", "route": "straight", "labelAt": [852, 144] }
+  ],
+  "cards": [
+    {
+      "dot": "emerald",
+      "title": "Primary Data Path",
+      "items": [
+        "Events move left to right through source, ingest, process, store, and consume stages",
+        "The hot path stays visually clear even with secondary batch flows",
+        "Labels name data assets instead of generic API verbs"
+      ]
+    },
+    {
+      "dot": "rose",
+      "title": "Sensitive Boundary",
+      "items": [
+        "Consent and PII paths are styled as security flows",
+        "PII lands in a restricted vault, separate from the analytics warehouse",
+        "Restricted joins are visible without implying default access"
+      ]
+    },
+    {
+      "dot": "orange",
+      "title": "Derived Consumers",
+      "items": [
+        "Dashboards read curated facts from the warehouse",
+        "Feature vectors are derived by batch from analytics tables",
+        "Consumption paths stay distinct from collection and consent handling"
+      ]
+    }
+  ]
+}

package/skills/interactive-page/scripts/archify/examples/production-deployment.architecture.json

@@ -0,0 +1,71 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "Production Deployment Ownership",
+    "output": "examples/production-deployment.html",
+    "visual_preset": "blueprint",
+    "animation": "trace",
+    "quality_profile": "showcase",
+    "engineering_profile": "deployment-ownership",
+    "views": [
+      {
+        "id": "request-boundary",
+        "label": "Request crosses the edge",
+        "focus": ["clients", "edge", "gateway", "api_a", "api_b"],
+        "note": "Follow public traffic into the private application network."
+      },
+      {
+        "id": "state-ownership",
+        "label": "State and ownership",
+        "focus": ["api_a", "api_b", "redis", "postgres", "replica"],
+        "note": "Separate stateless platform workloads from data-team-owned state."
+      },
+      {
+        "id": "async-operations",
+        "label": "Async and operations",
+        "focus": ["api_b", "events", "worker", "audit", "observability"],
+        "note": "See the asynchronous work and the evidence it emits."
+      }
+    ]
+  },
+  "components": [
+    { "id": "clients", "type": "external", "label": "Customers", "sublabel": "web + mobile", "pos": [38, 300], "size": [122, 60] },
+    { "id": "edge", "type": "cloud", "label": "Global Edge", "sublabel": "CDN + WAF", "pos": [230, 300], "size": [126, 60], "tag": "edge team" },
+    { "id": "gateway", "type": "security", "label": "API Gateway", "sublabel": "public :443", "pos": [430, 300], "size": [128, 60], "tag": "platform" },
+    { "id": "api_a", "type": "backend", "label": "API Pods / AZ-a", "sublabel": "private subnet", "pos": [630, 195], "size": [136, 62], "tag": "app team" },
+    { "id": "api_b", "type": "backend", "label": "API Pods / AZ-b", "sublabel": "private subnet", "pos": [630, 405], "size": [136, 62], "tag": "app team" },
+    { "id": "redis", "type": "database", "label": "Redis", "sublabel": "multi-AZ cache", "pos": [840, 195], "size": [126, 62], "tag": "platform" },
+    { "id": "postgres", "type": "database", "label": "PostgreSQL", "sublabel": "primary / encrypted", "pos": [840, 405], "size": [126, 62], "tag": "data team" },
+    { "id": "events", "type": "messagebus", "label": "Event Bus", "sublabel": "orders.v1", "pos": [1040, 300], "size": [126, 60], "tag": "platform" },
+    { "id": "worker", "type": "backend", "label": "Workers", "sublabel": "private workload", "pos": [1190, 300], "size": [126, 60], "tag": "app team" },
+    { "id": "replica", "type": "database", "label": "DR Replica", "sublabel": "eu-west-1", "pos": [1040, 578], "size": [126, 62], "tag": "data team" },
+    { "id": "audit", "type": "cloud", "label": "Audit Archive", "sublabel": "immutable objects", "pos": [1190, 450], "size": [126, 62], "tag": "security" },
+    { "id": "observability", "type": "external", "label": "Observability", "sublabel": "metrics + traces", "pos": [1190, 85], "size": [126, 62], "tag": "SRE" }
+  ],
+  "boundaries": [
+    { "kind": "region", "label": "AWS us-east-1 / production", "wraps": ["edge", "gateway", "api_a", "api_b", "redis", "postgres", "events", "worker", "audit"], "pad": 20 },
+    { "kind": "security-group", "label": "private application network", "wraps": ["api_a", "api_b", "redis", "postgres", "events", "worker"], "pad": 14 },
+    { "kind": "region", "label": "AWS eu-west-1 / disaster recovery", "wraps": ["replica"] },
+    { "kind": "security-group", "label": "DR private subnet", "wraps": ["replica"], "pad": 14 }
+  ],
+  "connections": [
+    { "from": "clients", "to": "edge", "label": "HTTPS", "variant": "emphasis" },
+    { "from": "edge", "to": "gateway", "label": "mTLS", "variant": "security" },
+    { "from": "gateway", "to": "api_a", "label": "VPC route", "variant": "emphasis", "route": "orthogonal-h", "labelAt": [594, 275] },
+    { "from": "gateway", "to": "api_b", "label": "VPC route", "variant": "emphasis", "route": "orthogonal-h", "labelAt": [594, 385] },
+    { "from": "api_a", "to": "redis", "label": "cache", "route": "straight" },
+    { "from": "api_b", "to": "postgres", "label": "SQL", "route": "straight" },
+    { "from": "api_a", "to": "events", "label": "publish", "variant": "dashed", "fromSide": "top", "toSide": "top", "via": [[698, 170], [1103, 170]] },
+    { "from": "api_b", "to": "events", "variant": "dashed", "fromSide": "top", "toSide": "bottom", "via": [[698, 380], [1103, 380]] },
+    { "from": "events", "to": "worker", "variant": "emphasis" },
+    { "from": "postgres", "to": "replica", "label": "cross-region WAL", "variant": "security", "route": "orthogonal-v", "labelAt": [1003, 529] },
+    { "from": "worker", "to": "audit", "label": "evidence", "variant": "dashed", "fromSide": "bottom", "toSide": "top", "labelDy": 58 },
+    { "from": "worker", "to": "observability", "label": "OTLP", "variant": "dashed", "route": "orthogonal-v" }
+  ],
+  "cards": [
+    { "dot": "cyan", "title": "Runtime Ownership", "items": ["Platform owns the edge, gateway, cache, and event bus", "Application teams own API pods and workers", "Data owns primary and disaster-recovery state"] },
+    { "dot": "rose", "title": "Named Crossings", "items": ["Public HTTPS terminates at the managed edge", "mTLS crosses into the application network", "Cross-region WAL is explicit and encrypted"] },
+    { "dot": "emerald", "title": "Operational Evidence", "items": ["Workers emit traces to SRE-owned observability", "Audit evidence lands in immutable storage", "Unknown placement should remain marked, never invented"] }
+  ]
+}

package/skills/interactive-page/scripts/archify/examples/release-delivery.workflow.json

@@ -0,0 +1,62 @@
+{
+  "schema_version": 1,
+  "diagram_type": "workflow",
+  "meta": {
+    "title": "Release Delivery Workflow",
+    "output": "examples/release-delivery.html",
+    "animation": "trace",
+    "quality_profile": "showcase",
+    "views": [
+      { "id": "commit-to-checks", "label": "Commit to green build", "focus": ["commit", "pull_request", "build", "checks"], "note": "Follow the change through reproducible build and blocking quality gates." },
+      { "id": "approval-to-production", "label": "Approve and promote", "focus": ["checks", "approval", "deploy", "verify_prod", "announce"], "note": "See who authorizes production and how success is verified." },
+      { "id": "rollback-path", "label": "Failure and rollback", "focus": ["checks", "failed", "verify_prod", "rollback", "deploy"], "note": "Isolate the two places where delivery stops or reverses safely." }
+    ]
+  },
+  "lanes": [
+    { "id": "dev", "label": "Developer" },
+    { "id": "ci", "label": "Continuous Integration" },
+    { "id": "approval", "label": "Release Governance" },
+    { "id": "environment", "label": "Production Environment" },
+    { "id": "communication", "label": "Release Communication" },
+    { "id": "exceptions", "label": "Failure + Rollback", "variant": "exception" }
+  ],
+  "phases": [
+    { "id": "change", "label": "Change", "fromCol": 0, "toCol": 1 },
+    { "id": "verify", "label": "Build + verify", "fromCol": 2, "toCol": 3, "variant": "emphasis" },
+    { "id": "promote", "label": "Promote + observe", "fromCol": 4, "toCol": 5, "variant": "dashed" }
+  ],
+  "groups": [
+    { "id": "blocking_checks", "label": "Blocking checks", "lane": "ci", "fromCol": 2, "toCol": 3, "variant": "emphasis" },
+    { "id": "rollback_work", "label": "Recovery path", "lane": "exceptions", "fromCol": 3, "toCol": 5, "variant": "security" }
+  ],
+  "mainPath": ["commit", "pull_request", "build", "checks", "approval", "deploy", "verify_prod", "announce"],
+  "nodes": [
+    { "id": "commit", "lane": "dev", "col": 0, "type": "frontend", "label": "Commit", "sublabel": "signed change" },
+    { "id": "pull_request", "lane": "dev", "col": 1, "type": "frontend", "label": "Pull Request", "sublabel": "reviewed diff" },
+    { "id": "build", "lane": "ci", "col": 2, "type": "backend", "label": "Build", "sublabel": "locked inputs", "tag": "reproducible" },
+    { "id": "checks", "lane": "ci", "col": 3, "type": "security", "label": "Quality Gates", "sublabel": "test + scan", "tag": "blocking" },
+    { "id": "approval", "lane": "approval", "col": 4, "type": "security", "label": "Approve", "sublabel": "release owner", "tag": "human gate" },
+    { "id": "deploy", "lane": "environment", "col": 4, "type": "cloud", "label": "Deploy", "sublabel": "canary 10%", "tag": "production" },
+    { "id": "verify_prod", "lane": "environment", "col": 5, "type": "backend", "label": "Verify", "sublabel": "smoke + SLO" },
+    { "id": "announce", "lane": "communication", "col": 5, "type": "external", "label": "Announce", "sublabel": "status + notes" },
+    { "id": "failed", "lane": "exceptions", "col": 2, "type": "security", "label": "Stop Release", "sublabel": "gate failed" },
+    { "id": "rollback", "lane": "exceptions", "col": 4, "width": 64, "type": "messagebus", "label": "Rollback", "sublabel": "last good image", "tag": "owner: on-call" }
+  ],
+  "edges": [
+    { "from": "commit", "to": "pull_request" },
+    { "from": "pull_request", "to": "build", "label": "merge", "variant": "emphasis", "route": "drop", "fromSide": "bottom", "toSide": "top" },
+    { "from": "build", "to": "checks" },
+    { "from": "checks", "to": "approval", "variant": "emphasis", "route": "drop", "fromSide": "bottom", "toSide": "top" },
+    { "from": "approval", "to": "deploy", "variant": "security", "route": "drop", "fromSide": "bottom", "toSide": "top" },
+    { "from": "deploy", "to": "verify_prod" },
+    { "from": "verify_prod", "to": "announce", "label": "healthy", "variant": "emphasis", "route": "drop", "fromSide": "bottom", "toSide": "top" },
+    { "from": "checks", "to": "failed", "label": "red", "variant": "security", "role": "error", "route": "drop", "fromSide": "bottom", "toSide": "top" },
+    { "from": "verify_prod", "to": "rollback", "variant": "security", "role": "error", "route": "outside-right", "fromSide": "right", "toSide": "right" },
+    { "from": "rollback", "to": "deploy", "label": "restore", "variant": "dashed", "role": "return", "route": "return-left", "fromSide": "left", "toSide": "left" }
+  ],
+  "cards": [
+    { "dot": "emerald", "title": "One Happy Path", "items": ["Every change is reviewed before a reproducible build", "Blocking checks must be green before human approval", "Production is complete only after smoke and SLO verification"] },
+    { "dot": "rose", "title": "Stop Conditions", "items": ["Test or security failure stops promotion", "Production health can reverse a release", "Rollback ownership is visible before an incident"] },
+    { "dot": "cyan", "title": "Release Evidence", "items": ["Approval, immutable image, and check results are retained", "The release announcement follows verification", "The main path remains readable without hiding failure"] }
+  ]
+}

package/skills/interactive-page/scripts/archify/examples/web-app.architecture.json

@@ -0,0 +1,46 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "Sample Web App",
+    "output": "web-app-rendered.html",
+    "quality_profile": "showcase",
+    "views": [
+      { "id": "request-path", "label": "Primary request path", "focus": ["users", "cdn", "lb", "api", "db"], "note": "Follow the primary customer request from the edge to durable state." },
+      { "id": "identity-and-cache", "label": "Identity and cache", "focus": ["auth", "api", "cache"], "note": "Isolate authentication and the read-through cache beside the request path." },
+      { "id": "async-work", "label": "Static and async work", "focus": ["cdn", "s3", "api", "queue", "worker"], "note": "See the two secondary paths without adding noise to the main request." }
+    ]
+  },
+  "components": [
+    { "id": "users", "type": "external", "label": "Users", "sublabel": "Browser / Mobile", "pos": [40, 300], "size": [120, 60] },
+    { "id": "auth", "type": "security", "label": "Auth Provider", "sublabel": "OAuth 2.0", "pos": [40, 110], "size": [120, 64], "tag": "JWT + PKCE" },
+    { "id": "cdn", "type": "cloud", "label": "CloudFront", "sublabel": "CDN", "pos": [250, 300], "size": [130, 60] },
+    { "id": "lb", "type": "cloud", "label": "Load Balancer", "sublabel": "HTTPS :443", "pos": [460, 300], "size": [130, 60] },
+    { "id": "api", "type": "backend", "label": "API Server", "sublabel": "FastAPI :8000", "pos": [670, 300], "size": [130, 60] },
+    { "id": "cache", "type": "database", "label": "Redis", "sublabel": "cache :6379", "pos": [670, 150], "size": [130, 60] },
+    { "id": "db", "type": "database", "label": "PostgreSQL", "sublabel": "primary :5432", "pos": [880, 300], "size": [130, 60] },
+    { "id": "s3", "type": "cloud", "label": "S3", "sublabel": "static assets", "pos": [250, 440], "size": [130, 60], "tag": "OAI protected" },
+    { "id": "queue", "type": "messagebus", "label": "SQS", "sublabel": "job queue", "pos": [670, 440], "size": [130, 60] },
+    { "id": "worker", "type": "backend", "label": "Worker", "sublabel": "async jobs", "pos": [880, 440], "size": [130, 60] }
+  ],
+  "boundaries": [
+    { "kind": "region", "label": "AWS Region: us-west-2", "wraps": ["cdn", "lb", "api", "cache", "db", "s3", "queue", "worker"] },
+    { "kind": "security-group", "label": "sg-api :443/:8000", "wraps": ["lb", "api"] }
+  ],
+  "connections": [
+    { "id": "users-to-cdn", "from": "users", "to": "cdn", "label": "HTTPS", "variant": "emphasis" },
+    { "id": "jwt-verification", "from": "auth", "to": "api", "label": "verify JWT", "variant": "security", "fromSide": "right", "toSide": "top", "via": [[620, 142], [620, 246], [735, 246]] },
+    { "id": "cdn-to-lb", "from": "cdn", "to": "lb" },
+    { "id": "static-assets", "from": "cdn", "to": "s3", "label": "static", "variant": "dashed", "fromSide": "bottom", "toSide": "top", "labelDy": 58 },
+    { "id": "lb-to-api", "from": "lb", "to": "api" },
+    { "id": "cache-read-through", "from": "api", "to": "cache", "label": "read-through", "fromSide": "top", "toSide": "bottom", "labelDy": -68 },
+    { "id": "api-sql", "from": "api", "to": "db", "label": "SQL" },
+    { "id": "enqueue-job", "from": "api", "to": "queue", "label": "enqueue", "variant": "dashed", "fromSide": "bottom", "toSide": "top", "labelDy": 58 },
+    { "id": "queue-to-worker", "from": "queue", "to": "worker" }
+  ],
+  "cards": [
+    { "dot": "cyan", "title": "Edge", "items": ["CloudFront CDN fronts all traffic", "S3 serves static assets via OAI"] },
+    { "dot": "emerald", "title": "Application", "items": ["FastAPI behind an HTTPS load balancer", "Redis read-through cache", "Async work drained from SQS by a worker"] },
+    { "dot": "rose", "title": "Security", "items": ["OAuth 2.0 with JWT + PKCE", "API + LB isolated in a security group"] }
+  ]
+}

package/skills/interactive-page/scripts/archify/migrations/workflow-v2.mjs

@@ -0,0 +1,279 @@
+import { compileWorkflow } from '../renderers/workflow/workflow-compiler.mjs';
+import {
+  createMappedWorkflowCandidate,
+  intrinsicWorkflow,
+  planningWorkflow,
+} from '../renderers/workflow/workflow-migration-geometry.mjs';
+import { validateSchema } from '../renderers/shared/validator.mjs';
+
+export { createHorizontalRankMapper } from '../renderers/workflow/workflow-migration-geometry.mjs';
+
+const TARGET_SCHEMA_VERSION = 2;
+
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function diagnostic({ code, message, subject = {}, evidence = {}, supportedFixes = [] }) {
+  return {
+    code,
+    severity: 'error',
+    message,
+    subject,
+    evidence,
+    supportedFixes,
+  };
+}
+
+function schemaDiagnostics(workflow) {
+  try {
+    validateSchema('workflow', workflow);
+    return [];
+  } catch (error) {
+    if (Array.isArray(error?.archifyDiagnostics)) {
+      return error.archifyDiagnostics.map((entry) => ({ ...entry }));
+    }
+    throw error;
+  }
+}
+
+function legacyLayoutProbe(workflow, qualityProfile) {
+  // The probe discovers fixed-v1 rank centers, not authored canvas capacity.
+  // Omitting viewBox lets a capacity-only legacy failure reach the v2 compiler,
+  // which can measure and monotonically expand the real migrated document.
+  const probe = {
+    schema_version: 1,
+    diagram_type: 'workflow',
+    meta: {
+      title: workflow.meta.title,
+      ...(workflow.meta.locale ? { locale: workflow.meta.locale } : {}),
+      legend: { mode: 'hidden' },
+    },
+    lanes: clone(workflow.lanes),
+    nodes: [{
+      id: 'migration_probe',
+      lane: workflow.lanes[0].id,
+      col: 0,
+      type: 'backend',
+      label: 'Probe',
+    }],
+    edges: [],
+  };
+  return compileWorkflow({ workflow: probe, qualityProfile });
+}
+
+function legacyRequirementProbe(workflow, qualityProfile) {
+  // Measure the complete fixed-v1 document without treating an authored
+  // viewBox as its intrinsic requirement. The authored viewBox remains a
+  // migration capacity and is preserved separately on the migrated document.
+  const probe = clone(workflow);
+  delete probe.meta.viewBox;
+  return compileWorkflow({ workflow: probe, qualityProfile });
+}
+
+function requiredViewBoxFrom(result) {
+  if (Array.isArray(result?.receipt?.requiredViewBox)) {
+    return [...result.receipt.requiredViewBox];
+  }
+  const required = result?.diagnostics
+    ?.map((entry) => entry?.evidence?.requiredViewBox)
+    .find((candidate) => Array.isArray(candidate) && candidate.length === 2);
+  return required ? [...required] : null;
+}
+
+function expandableViewBox(result) {
+  if (result.ok || !result.diagnostics?.length) return null;
+  if (!result.diagnostics.every((entry) => entry.code === 'workflow/viewbox-capacity')) return null;
+  return requiredViewBoxFrom(result);
+}
+
+function result({
+  ok,
+  document,
+  fromSchemaVersion = 1,
+  preExistingDiagnostics = [],
+  migrationDiagnostics = [],
+  newSchemaDiagnostics = [],
+  changedCoordinates = [],
+  oldRequiredViewBox = null,
+  newRequiredViewBox = null,
+}) {
+  return {
+    ok,
+    ...(document ? { document } : {}),
+    fromSchemaVersion,
+    toSchemaVersion: TARGET_SCHEMA_VERSION,
+    preExistingDiagnostics,
+    migrationDiagnostics,
+    newSchemaDiagnostics,
+    changedCoordinates,
+    oldRequiredViewBox,
+    newRequiredViewBox,
+  };
+}
+
+export function migrateWorkflowDocument(inputWorkflow) {
+  if (!inputWorkflow || typeof inputWorkflow !== 'object' || Array.isArray(inputWorkflow)) {
+    return result({
+      ok: false,
+      migrationDiagnostics: [diagnostic({
+        code: 'migration/source-document',
+        message: 'Workflow migration requires one parsed JSON object.',
+        supportedFixes: ['provide one workflow schema v1 JSON document'],
+      })],
+    });
+  }
+  // Migration has no quality override: the authored policy (or effective
+  // standard default) must validate the document after it leaves this process.
+  const qualityProfile = inputWorkflow.meta?.quality_profile || 'standard';
+
+  const workflow = clone(inputWorkflow);
+  const preExistingDiagnostics = schemaDiagnostics(workflow);
+  if (preExistingDiagnostics.length) {
+    return result({
+      ok: false,
+      fromSchemaVersion: workflow.schema_version,
+      preExistingDiagnostics,
+    });
+  }
+  if (workflow.schema_version === TARGET_SCHEMA_VERSION) {
+    const compiled = compileWorkflow({ workflow: clone(workflow), qualityProfile });
+    const requiredViewBox = requiredViewBoxFrom(compiled);
+    if (!compiled.ok) {
+      return result({
+        ok: false,
+        fromSchemaVersion: TARGET_SCHEMA_VERSION,
+        preExistingDiagnostics: compiled.diagnostics,
+        oldRequiredViewBox: requiredViewBox,
+        newRequiredViewBox: requiredViewBox,
+      });
+    }
+    return result({
+      ok: true,
+      document: workflow,
+      fromSchemaVersion: TARGET_SCHEMA_VERSION,
+      oldRequiredViewBox: requiredViewBox,
+      newRequiredViewBox: requiredViewBox,
+    });
+  }
+  if (workflow.schema_version !== 1) {
+    return result({
+      ok: false,
+      fromSchemaVersion: workflow.schema_version,
+      migrationDiagnostics: [diagnostic({
+        code: 'migration/source-schema-version',
+        message: 'Workflow migration to schema v2 requires a schema v1 or v2 source.',
+        subject: { path: '/schema_version' },
+        evidence: { actual: workflow.schema_version, expected: [1, 2] },
+        supportedFixes: ['use an unchanged schema v1 workflow or an already migrated schema v2 workflow as the source'],
+      })],
+    });
+  }
+
+  const legacy = compileWorkflow({ workflow: clone(workflow), qualityProfile });
+  const legacyProbe = legacyLayoutProbe(workflow, qualityProfile);
+  if (!legacyProbe.ok) {
+    return result({
+      ok: false,
+      preExistingDiagnostics: legacy.ok ? [] : legacy.diagnostics,
+      migrationDiagnostics: legacyProbe.diagnostics,
+    });
+  }
+  const legacyRequirement = legacyRequirementProbe(workflow, qualityProfile);
+  const oldRequiredViewBox = requiredViewBoxFrom(legacyRequirement)
+    || requiredViewBoxFrom(legacyProbe)
+    || requiredViewBoxFrom(legacy);
+  const preExistingLayoutDiagnostics = legacy.ok ? [] : legacy.diagnostics;
+
+  let planned = compileWorkflow({ workflow: intrinsicWorkflow(workflow), qualityProfile });
+  if (!planned.ok) {
+    // Old absolute pins can be invalid at the new rank centers before their X
+    // coordinates are mapped. Obtain the same rank plan from an automatic-route
+    // projection, then validate every authored pin again after mapping.
+    planned = compileWorkflow({ workflow: planningWorkflow(workflow), qualityProfile });
+  }
+  if (!planned.ok) {
+    return result({
+      ok: false,
+      preExistingDiagnostics: preExistingLayoutDiagnostics,
+      newSchemaDiagnostics: planned.diagnostics,
+      oldRequiredViewBox,
+      newRequiredViewBox: requiredViewBoxFrom(planned),
+    });
+  }
+
+  let mappedCandidate;
+  try {
+    mappedCandidate = createMappedWorkflowCandidate(
+      workflow,
+      legacyProbe.receipt.columns,
+      planned.receipt.columns,
+    );
+  } catch (error) {
+    return result({
+      ok: false,
+      preExistingDiagnostics: preExistingLayoutDiagnostics,
+      migrationDiagnostics: [diagnostic({
+        code: 'migration/rank-mapping',
+        message: 'Could not construct a stable horizontal rank mapping.',
+        evidence: { reason: error.message },
+        supportedFixes: ['report the workflow and compiler receipts to the Archify maintainers'],
+      })],
+      oldRequiredViewBox,
+      newRequiredViewBox: requiredViewBoxFrom(planned),
+    });
+  }
+
+  const { document: migrated, changedCoordinates } = mappedCandidate;
+
+  let compiled = compileWorkflow({ workflow: migrated, qualityProfile });
+  const requiredExpansion = migrated.meta.viewBox ? expandableViewBox(compiled) : null;
+  if (requiredExpansion) {
+    const current = migrated.meta.viewBox;
+    const expanded = [
+      Math.max(current[0], requiredExpansion[0]),
+      Math.max(current[1], requiredExpansion[1]),
+    ];
+    if (expanded[0] > current[0] || expanded[1] > current[1]) {
+      migrated.meta.viewBox = expanded;
+      compiled = compileWorkflow({ workflow: migrated, qualityProfile });
+    }
+  }
+
+  const newRequiredViewBox = requiredViewBoxFrom(compiled) || requiredViewBoxFrom(planned);
+  if (!compiled.ok) {
+    return result({
+      ok: false,
+      preExistingDiagnostics: preExistingLayoutDiagnostics,
+      newSchemaDiagnostics: compiled.diagnostics,
+      changedCoordinates,
+      oldRequiredViewBox,
+      newRequiredViewBox,
+    });
+  }
+
+  const migratedSchemaDiagnostics = schemaDiagnostics(migrated);
+  if (migratedSchemaDiagnostics.length) {
+    return result({
+      ok: false,
+      preExistingDiagnostics: preExistingLayoutDiagnostics,
+      newSchemaDiagnostics: migratedSchemaDiagnostics,
+      changedCoordinates,
+      oldRequiredViewBox,
+      newRequiredViewBox,
+    });
+  }
+
+  return result({
+    ok: true,
+    document: migrated,
+    preExistingDiagnostics: preExistingLayoutDiagnostics,
+    changedCoordinates,
+    oldRequiredViewBox,
+    newRequiredViewBox,
+  });
+}
+
+export function serializeMigratedWorkflow(workflow) {
+  return `${JSON.stringify(workflow, null, 2)}\n`;
+}