deepline 0.3.88 → 0.3.90

package/dist/bundling-sources/shared_libs/plays/core.ts

@@ -13,6 +13,9 @@ import type {
   PlayAuthoringDefinedPlay,
   PlayAuthoringInputContract,
   PlayAuthoringReferenceLike,
+  AsyncPlayRunRef as PlayAuthoringAsyncPlayRunRef,
+  PlayAuthoringAsyncCallOptions,
+  PlayRunId as PlayAuthoringRunId,
   PlayAuthoringRuntimeContext,
   PlayAuthoringStepOptions,
   PlayAuthoringStepProgram,
@@ -125,7 +128,12 @@ export type DatasetBuilder<
   DeeplinePlayRuntimeContext
 >;
 
-export type PlayReferenceLike = PlayAuthoringReferenceLike;
+export type PlayReferenceLike<
+  TInput extends Record<string, unknown> = Record<string, unknown>,
+> = PlayAuthoringReferenceLike<TInput>;
+export type AsyncPlayRunRef = PlayAuthoringAsyncPlayRunRef;
+export type PlayAsyncCallOptions = PlayAuthoringAsyncCallOptions;
+export type PlayRunId = PlayAuthoringRunId;
 
 export type DeeplinePlayRuntimeContext = PlayAuthoringRuntimeContext;
 
@@ -444,10 +452,7 @@ export function definePlay<TInput, TOutput extends PlayReturnObject>(
 /** @internal Contextually type unannotated monitor-event handlers as unknown. */
 export function definePlay<TOutput extends PlayReturnObject>(
   name: string,
-  fn: (
-    context: DeeplinePlayRuntimeContext,
-    input: unknown,
-  ) => Promise<TOutput>,
+  fn: (context: DeeplinePlayRuntimeContext, input: unknown) => Promise<TOutput>,
   bindings: PlayBindings<never> & {
     readonly sqlListeners: readonly SqlListenerDeclaration[];
   },
@@ -455,7 +460,7 @@ export function definePlay<TOutput extends PlayReturnObject>(
 /* eslint-disable @typescript-eslint/no-explicit-any -- This constraint must infer a concrete contravariant handler input. */
 export function definePlay<
   THandler extends (
-  context: DeeplinePlayRuntimeContext,
+    context: DeeplinePlayRuntimeContext,
     input: any,
   ) => Promise<PlayReturnObject>,
 >(

package/dist/bundling-sources/shared_libs/plays/deployment-status.ts

@@ -1,6 +1,6 @@
 /**
  * The play deployment status machine, shared by the Convex control plane
- * (convex/playDeployments.ts), worker auth (src/lib/auth/play-deploy-auth.ts),
+ * (convex/playDeployments.ts), worker auth (apps/deepline-api/src/lib/auth/play-deploy-auth.ts),
  * and the deploy-worker API surface. One spelling of the union, the terminal
  * set, and the allowed transitions.
  */

package/dist/bundling-sources/shared_libs/plays/docflow-binding-owner.ts

@@ -61,10 +61,12 @@ export type DocflowOwnerSubstep = Extract<
   { type: 'dataset' | 'csv' }
 >;
 export type DocflowToolSubstep = Extract<PlayStaticSubstep, { type: 'tool' }>;
-export type DocflowPlayCallSubstep = Extract<
+export type DocflowChildPlaySubstep = Extract<
   PlayStaticSubstep,
-  { type: 'play_call' }
+  { type: 'play_call' | 'play_launch' }
 >;
+/** @deprecated Use `DocflowChildPlaySubstep`; retained for compatibility. */
+export type DocflowPlayCallSubstep = DocflowChildPlaySubstep;
 export type DocflowStepSuiteSubstep = Extract<
   PlayStaticSubstep,
   { type: 'step_suite' }
@@ -332,19 +334,19 @@ export function resolveDocflowBoundTool(
 }
 
 /**
- * The `ctx.runPlay` call a `type:"play"` docflow node names. Same join as every
- * other binding — symbol first, extent as the fallback — over the FLATTENED
- * substep tree, because a child call inside a `.withColumn(...)` body is nested
- * under its dataset. A `play_call`'s `field` is the column or variable the child
- * result lands in, which is exactly what the node's `out:` names.
+ * The `ctx.runPlay` or `ctx.runPlayAsync` call a `type:"play"` docflow node
+ * names. Same join as every other binding — symbol first, extent as the fallback
+ * — over the FLATTENED substep tree. Its `field` is the column, variable, or
+ * launch key the child run lands in, which is exactly what the node's `out:`
+ * names.
  */
-export function resolveDocflowBoundPlayCall(
+export function resolveDocflowBoundChildPlay(
   binding: PlayDocflowBinding,
   substeps: readonly PlayStaticSubstep[],
-): DocflowBindingJoin<DocflowPlayCallSubstep> {
+): DocflowBindingJoin<DocflowChildPlaySubstep> {
   const playCalls = flattenSubsteps(substeps).filter(
-    (substep): substep is DocflowPlayCallSubstep =>
-      substep.type === 'play_call',
+    (substep): substep is DocflowChildPlaySubstep =>
+      substep.type === 'play_call' || substep.type === 'play_launch',
   );
   return joinBySymbolThenExtent(
     binding,
@@ -353,6 +355,9 @@ export function resolveDocflowBoundPlayCall(
   );
 }
 
+/** @deprecated Use `resolveDocflowBoundChildPlay`; retained for compatibility. */
+export const resolveDocflowBoundPlayCall = resolveDocflowBoundChildPlay;
+
 // ── waterfalls: the step suite and its legs ─────────────────────────────────
 //
 // `steps().step('hunter_email', …).step('leadmagic_email', …).return(…)` compiles

package/dist/bundling-sources/shared_libs/plays/docflow.ts

@@ -78,7 +78,7 @@ export type PlayDocflowEdge = {
    *
    * ABSENT — never `null` — when unrecorded, and that is load-bearing rather
    * than stylistic. `docflow` is whole-object serialized into
-   * `playStaticPipelineContractHash` (`src/lib/plays/artifact-storage.ts`),
+   * `playStaticPipelineContractHash` (`apps/deepline-api/src/lib/plays/artifact-storage.ts`),
    * which is part of the immutable artifact storage key, and the canonicalizer
    * there drops `undefined` but HASHES `null`. Emitting `arm: null` on an
    * unannotated edge would change the contract hash of every diagrammed play

package/dist/bundling-sources/shared_libs/plays/email-status.ts

@@ -91,7 +91,7 @@ export type EmailStatusBuildInput = {
 
 // There is intentionally NO shared default status map. Each provider must
 // declare its own `statusMap` / `rules` for the raw status strings it emits
-// (see the provider registries under src/lib/integrations/**). A coarse global
+// (see the provider registries under packages/integrations/**). A coarse global
 // map silently coerced provider-specific strings ("deliverable", "accept_all",
 // etc.) into canonical verdicts and let validators depend on guesses instead of
 // documented behavior. With it gone, an unmapped raw status falls through to

package/dist/bundling-sources/shared_libs/plays/play-grep-search.ts

@@ -0,0 +1,39 @@
+// Convex limits its final prefix-search term to 32 UTF-8 bytes, so the public
+// query must stay below that boundary. The corpus was already backfilled in
+// Convex's lowercase representation, so do not rewrite terms here: changing
+// its token boundaries would make historical rows require another data
+// migration. Reject an unsupported query at the API boundary rather than
+// silently returning an incomplete result or adding a second reader.
+export const CONVEX_PLAY_GREP_SEARCH_TERM_MAX_BYTES = 31;
+export const CONVEX_PLAY_GREP_SEARCH_MAX_TERMS = 16;
+
+const CONVEX_PLAY_GREP_SEARCH_TERM_PATTERN = /[\p{L}\p{N}]+/gu;
+
+/** Return searchable raw terms for the public response filter. */
+export function extractPlayGrepSearchTerms(value: string): string[] {
+  return value.match(CONVEX_PLAY_GREP_SEARCH_TERM_PATTERN) ?? [];
+}
+
+/**
+ * Match the immutable representation of the completed grep-corpus backfill.
+ */
+export function normalizePlayGrepSearchQuery(value: string): string {
+  return value.toLowerCase();
+}
+
+/**
+ * Count the terms the API will send to Convex. Request validation keeps an
+ * accepted query within Convex's 16-term full-text-search limit.
+ */
+export function countNormalizedPlayGrepSearchTerms(value: string): number {
+  return extractPlayGrepSearchTerms(normalizePlayGrepSearchQuery(value)).length;
+}
+
+/** True when a query term exceeds Convex's usable full-text-search limit. */
+export function hasOverlongPlayGrepSearchTerm(value: string): boolean {
+  const encoder = new TextEncoder();
+  return extractPlayGrepSearchTerms(normalizePlayGrepSearchQuery(value)).some(
+    (term) =>
+      encoder.encode(term).byteLength > CONVEX_PLAY_GREP_SEARCH_TERM_MAX_BYTES,
+  );
+}

package/dist/bundling-sources/shared_libs/plays/resolve-static-pipeline.ts

@@ -136,7 +136,7 @@ async function resolvePipelineSubsteps(input: {
         return nested satisfies PlayStaticSubstep;
       }
 
-      if (annotated.type !== 'play_call') {
+      if (annotated.type !== 'play_call' && annotated.type !== 'play_launch') {
         return annotated;
       }
 

package/dist/bundling-sources/shared_libs/plays/share/copy.ts

@@ -0,0 +1,271 @@
+/**
+ * Package-owned helpers for share-page copy: the generation input shape, a deterministic
+ * (no-LLM) fallback builder, override merging, and validation of model output.
+ *
+ * Nothing here performs network I/O — see generate-card.ts for the LLM call.
+ */
+import type {
+  PlayShareCopyOverrides,
+  PlayShareGeneratedCopy,
+  PlayShareSchemaShape,
+  PlayShareStaticPipelineSummary,
+} from './types';
+
+/** A single safe, bounded sample of a successful run. */
+export type ShareRunSummarySample = {
+  rowCount: number | null;
+  outputLeadCount: number | null;
+  columns: string[];
+};
+
+/**
+ * Everything the copy generators are allowed to see about a revision. This is
+ * assembled server-side and contains no provider spend, secrets, or source.
+ */
+export type ShareCardGenerationInput = {
+  playName: string;
+  displayName?: string | null;
+  ownerDisplayName: string | null;
+  version: number;
+  graphHash: string | null;
+  sourceHash: string;
+  summary: PlayShareStaticPipelineSummary;
+  inputSchema: PlayShareSchemaShape;
+  outputSchema: PlayShareSchemaShape;
+  providerNames: string[];
+  existingDescription: string | null;
+  sampleRunSummaries: ShareRunSummarySample[];
+};
+
+const COPY_FIELDS: Array<keyof PlayShareGeneratedCopy> = [
+  'title',
+  'shortDescription',
+  'jtbd',
+  'whenToUse',
+  'inputs',
+  'outputs',
+  'agentPrompt',
+  'llmSummary',
+  'seoTitle',
+  'seoDescription',
+];
+
+function humanizePlayName(name: string): string {
+  const cleaned = name
+    .split('/')
+    .pop()!
+    .replace(/[._-]+/g, ' ')
+    .trim();
+  if (!cleaned) {
+    return 'Play';
+  }
+  return cleaned
+    .split(/\s+/)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+function firstSentence(text: string): string {
+  const trimmed = text.trim();
+  const match = trimmed.match(/^.*?[.!?](\s|$)/);
+  return (match ? match[0] : trimmed).trim();
+}
+
+function joinList(items: string[], fallback: string): string {
+  const cleaned = items.filter(Boolean);
+  if (cleaned.length === 0) {
+    return fallback;
+  }
+  if (cleaned.length === 1) {
+    return cleaned[0];
+  }
+  return `${cleaned.slice(0, -1).join(', ')} and ${cleaned[cleaned.length - 1]}`;
+}
+
+/**
+ * Build a conservative card from structured facts, no model required. Used as a
+ * deterministic fallback and as the seed for the LLM prompt. Uncertain parts are
+ * intentionally generic rather than invented.
+ */
+export function buildDeterministicShareCard(
+  input: ShareCardGenerationInput,
+): PlayShareGeneratedCopy {
+  const human = input.displayName?.trim() || humanizePlayName(input.playName);
+  const providers = input.providerNames.filter(Boolean);
+  const providerPhrase =
+    providers.length > 0
+      ? ` using ${joinList(providers, 'GTM providers')}`
+      : '';
+  const inputFields = input.inputSchema?.fields ?? [];
+  const outputFields = input.outputSchema?.fields ?? [];
+
+  const existing = input.existingDescription?.trim() || '';
+  const shortDescription = existing
+    ? firstSentence(existing)
+    : `${human} is a Deepline play that automates a ${input.summary.stepCount}-step GTM pipeline${providerPhrase}.`;
+
+  const jtbd = existing
+    ? existing
+    : `Run a repeatable, multi-step GTM workflow${providerPhrase} without wiring providers together by hand.`;
+
+  const whenToUse =
+    providers.length > 0
+      ? [
+          `You need data from ${joinList(providers, 'multiple providers')} in one pass.`,
+          'You want a repeatable pipeline instead of one-off lookups.',
+          'You want an agent or teammate to run the same workflow on demand.',
+        ]
+      : [
+          'You need a repeatable, multi-step GTM workflow.',
+          'You want an agent or teammate to run it on demand.',
+          'You want consistent output columns every run.',
+        ];
+
+  const inputs =
+    inputFields.length > 0
+      ? inputFields
+      : input.summary.hasMap
+        ? ['A list of rows to process (CSV or table).']
+        : ['Run parameters for the workflow.'];
+
+  const outputs =
+    outputFields.length > 0
+      ? outputFields
+      : ['An enriched output table with one row per processed record.'];
+
+  const agentPrompt = `Use the Deepline "${input.playName}" play to ${jtbd
+    .charAt(0)
+    .toLowerCase()}${jtbd.slice(1)}`;
+
+  const llmSummary = [
+    `${human} (Deepline play "${input.playName}", version ${input.version}).`,
+    shortDescription,
+    `Pipeline: ${input.summary.stepCount} steps, ${input.summary.providerCount} provider${input.summary.providerCount === 1 ? '' : 's'}${input.summary.hasMap ? ', processes input rows as a dataset' : ''}.`,
+    inputFields.length > 0 ? `Inputs: ${inputFields.join(', ')}.` : null,
+    outputFields.length > 0 ? `Outputs: ${outputFields.join(', ')}.` : null,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  const primaryInput = inputs[0]?.replace(/\.$/, '') ?? 'GTM inputs';
+  const primaryOutput = outputs[0]?.replace(/\.$/, '') ?? 'workflow output';
+  const providerCount = input.summary.providerCount;
+  const seoTitle = `${human}: Inputs, Outputs & CLI Setup`;
+  const seoDescription = [
+    `Run or fork this Deepline play from ${primaryInput} to ${primaryOutput}.`,
+    `See steps, ${providerCount} provider${providerCount === 1 ? '' : 's'}, setup, and CLI commands.`,
+  ].join(' ');
+
+  return {
+    title: human,
+    shortDescription,
+    jtbd,
+    whenToUse,
+    inputs,
+    outputs,
+    agentPrompt,
+    llmSummary,
+    seoTitle,
+    seoDescription,
+  };
+}
+
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function nonEmptyStringArray(value: unknown): value is string[] {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.every((item) => nonEmptyString(item))
+  );
+}
+
+/**
+ * Validate an arbitrary object as `PlayShareGeneratedCopy`. Returns the typed
+ * copy or throws (loud failure) so model output can never silently degrade.
+ */
+export function parseGeneratedCopy(value: unknown): PlayShareGeneratedCopy {
+  if (!value || typeof value !== 'object') {
+    throw new Error('Generated copy must be an object.');
+  }
+  const record = value as Record<string, unknown>;
+  const stringFields: Array<keyof PlayShareGeneratedCopy> = [
+    'title',
+    'shortDescription',
+    'jtbd',
+    'agentPrompt',
+    'llmSummary',
+    'seoTitle',
+    'seoDescription',
+  ];
+  for (const field of stringFields) {
+    if (!nonEmptyString(record[field])) {
+      throw new Error(
+        `Generated copy field "${field}" must be a non-empty string.`,
+      );
+    }
+  }
+  const arrayFields: Array<keyof PlayShareGeneratedCopy> = [
+    'whenToUse',
+    'inputs',
+    'outputs',
+  ];
+  for (const field of arrayFields) {
+    if (!nonEmptyStringArray(record[field])) {
+      throw new Error(
+        `Generated copy field "${field}" must be a non-empty array of strings.`,
+      );
+    }
+  }
+
+  return {
+    title: (record.title as string).trim(),
+    shortDescription: (record.shortDescription as string).trim(),
+    jtbd: (record.jtbd as string).trim(),
+    whenToUse: (record.whenToUse as string[]).map((item) => item.trim()),
+    inputs: (record.inputs as string[]).map((item) => item.trim()),
+    outputs: (record.outputs as string[]).map((item) => item.trim()),
+    agentPrompt: (record.agentPrompt as string).trim(),
+    llmSummary: (record.llmSummary as string).trim(),
+    seoTitle: (record.seoTitle as string).trim(),
+    seoDescription: (record.seoDescription as string).trim(),
+  };
+}
+
+function isMeaningfulOverride(value: unknown): boolean {
+  if (nonEmptyString(value)) {
+    return true;
+  }
+  if (Array.isArray(value)) {
+    return value.some((item) => nonEmptyString(item));
+  }
+  return false;
+}
+
+/**
+ * Merge owner overrides over generated copy at read time. Only non-empty
+ * overrides win; everything else falls through to the generated value.
+ */
+export function mergeShareCopy(
+  generated: PlayShareGeneratedCopy,
+  overrides: PlayShareCopyOverrides | null | undefined,
+): PlayShareGeneratedCopy {
+  if (!overrides) {
+    return generated;
+  }
+  const merged: PlayShareGeneratedCopy = { ...generated };
+  for (const field of COPY_FIELDS) {
+    const override = overrides[field];
+    if (isMeaningfulOverride(override)) {
+      // Field types are homogeneous per key; cast is safe after the check.
+      (merged[field] as unknown) = Array.isArray(override)
+        ? override
+            .filter((item) => nonEmptyString(item))
+            .map((item) => item.trim())
+        : (override as string).trim();
+    }
+  }
+  return merged;
+}

package/dist/bundling-sources/shared_libs/plays/share/metrics.ts

@@ -0,0 +1,140 @@
+/**
+ * Package-owned metric aggregation for the public read model.
+ *
+ * Hard rules (see docs/shareable-play-pages-plan.md + AGENTS.md):
+ * - Only Deepline credits are aggregated here. Provider spend (USD) is never
+ *   passed into this module.
+ * - Cost is exposed only when the owner opted in.
+ * - Latency is exposed only when the owner opted in AND the revision has no map.
+ * - Denominator-specific metrics return null when row/contact counts are
+ *   missing or ambiguous.
+ */
+import type { PlayCostBasis, PublishedPlayPageMetrics } from './types';
+
+/**
+ * One completed run, reduced to the only facts the public metrics need.
+ * `providerCostUsd` deliberately does not exist on this type.
+ */
+export type ShareRunMetricSample = {
+  /** Total Deepline credits for the run (sum of usageEvents.credits). */
+  credits: number;
+  /** Number of input rows processed, when reliably known. */
+  inputRowCount: number | null;
+  /** Number of output leads/contacts produced, when reliably known. */
+  outputLeadCount: number | null;
+  /** Wall-clock run latency in ms, when valid timing exists. */
+  latencyMs: number | null;
+};
+
+export type ComputePublicMetricsOptions = {
+  showAverageDeeplineCost: boolean;
+  showAverageLatency: boolean;
+  /** Latency is meaningless for mapped (fan-out) revisions. */
+  hasMap: boolean;
+  /** Which credit denominator the page may render; see `classifyCostBasis`. */
+  costBasis: PlayCostBasis;
+};
+
+function mean(values: number[]): number | null {
+  if (values.length === 0) {
+    return null;
+  }
+  const total = values.reduce((sum, value) => sum + value, 0);
+  return total / values.length;
+}
+
+function roundTo(value: number, decimals: number): number {
+  const factor = 10 ** decimals;
+  return Math.round(value * factor) / factor;
+}
+
+/**
+ * Aggregate a bounded sample of completed runs into public, credit-only metrics.
+ */
+export function computePublicMetrics(
+  samples: ShareRunMetricSample[],
+  options: ComputePublicMetricsOptions,
+): PublishedPlayPageMetrics {
+  const sampleRunCount = samples.length;
+
+  const empty: PublishedPlayPageMetrics = {
+    averageDeeplineCostCredits: null,
+    averageCostPerInputRowCredits: null,
+    averageCostPerOutputLeadCredits: null,
+    averageLatencyMs: null,
+    sampleRunCount,
+    costBasis: options.costBasis,
+  };
+
+  if (sampleRunCount === 0) {
+    return empty;
+  }
+
+  const metrics: PublishedPlayPageMetrics = { ...empty };
+
+  if (options.showAverageDeeplineCost) {
+    const creditValues = samples
+      .map((sample) => sample.credits)
+      .filter((value) => Number.isFinite(value) && value >= 0);
+    const avgCredits = mean(creditValues);
+    metrics.averageDeeplineCostCredits =
+      avgCredits === null ? null : roundTo(avgCredits, 2);
+
+    metrics.averageCostPerInputRowCredits = ratioOverDenominator(
+      samples,
+      (sample) => sample.inputRowCount,
+    );
+    metrics.averageCostPerOutputLeadCredits = ratioOverDenominator(
+      samples,
+      (sample) => sample.outputLeadCount,
+    );
+  }
+
+  if (options.showAverageLatency && !options.hasMap) {
+    const latencyValues = samples
+      .map((sample) => sample.latencyMs)
+      .filter(
+        (value): value is number =>
+          value !== null && Number.isFinite(value) && value >= 0,
+      );
+    const avgLatency = mean(latencyValues);
+    metrics.averageLatencyMs =
+      avgLatency === null ? null : Math.round(avgLatency);
+  }
+
+  return metrics;
+}
+
+/**
+ * total credits / total denominator, considering only runs where the
+ * denominator is a reliable positive number. Returns null if no such run.
+ */
+function ratioOverDenominator(
+  samples: ShareRunMetricSample[],
+  pick: (sample: ShareRunMetricSample) => number | null,
+): number | null {
+  let creditSum = 0;
+  let denominatorSum = 0;
+  let usableRuns = 0;
+
+  for (const sample of samples) {
+    const denominator = pick(sample);
+    if (
+      denominator === null ||
+      !Number.isFinite(denominator) ||
+      denominator <= 0 ||
+      !Number.isFinite(sample.credits) ||
+      sample.credits < 0
+    ) {
+      continue;
+    }
+    creditSum += sample.credits;
+    denominatorSum += denominator;
+    usableRuns += 1;
+  }
+
+  if (usableRuns === 0 || denominatorSum <= 0) {
+    return null;
+  }
+  return roundTo(creditSum / denominatorSum, 4);
+}

package/dist/bundling-sources/shared_libs/plays/share/public-read-model.ts

@@ -0,0 +1,86 @@
+/**
+ * Package-owned assembler for the bounded `PublishedPlayPagePackage`.
+ *
+ * This is the ONLY object the public page and public API expose. It is built
+ * from already-gathered, already-sanitized inputs — this function performs no
+ * I/O and makes no access decisions.
+ */
+import {
+  buildInputSchemaShape,
+  buildOutputSchemaShape,
+  buildPublicSubsteps,
+  buildStaticPipelineSummary,
+} from './static-pipeline-summary';
+// This Module is bundled by Convex through its workspace dependency graph.
+import { buildShareCanonicalPath } from '../slug';
+import type {
+  PlayShareGeneratedCopy,
+  PlayShareSeoIndexing,
+  PublishedPlayPageMetrics,
+  PublishedPlayPagePackage,
+} from './types';
+
+export type BuildPublishedPlayPagePackageInput = {
+  shareSlug: string;
+  /** Org URL handle; the public page is namespaced `/p/:orgSlug/:playName`. */
+  orgSlug: string;
+  /** Page-level SEO posture; applied only to the published version. */
+  pageSeoIndexing: PlayShareSeoIndexing;
+  publishedVersion: number;
+  publishedAt: number;
+  definitionName: string;
+  ownerDisplayName: string | null;
+  revision: {
+    id: string;
+    version: number;
+    graphHash: string | null;
+    staticPipeline: unknown;
+  };
+  copy: PlayShareGeneratedCopy;
+  metrics: PublishedPlayPageMetrics;
+};
+
+export function buildPublishedPlayPagePackage(
+  input: BuildPublishedPlayPagePackageInput,
+): PublishedPlayPagePackage {
+  const isPublishedVersion = input.revision.version === input.publishedVersion;
+
+  // Non-published (historical) versions default to noindex regardless of the
+  // page setting, so old copies never compete with the canonical version.
+  const seoIndexing: PlayShareSeoIndexing = isPublishedVersion
+    ? input.pageSeoIndexing
+    : 'noindex';
+
+  return {
+    page: {
+      shareSlug: input.shareSlug,
+      orgSlug: input.orgSlug,
+      visibility: 'unlisted',
+      seoIndexing,
+      canonicalPath: buildShareCanonicalPath(
+        input.orgSlug,
+        input.definitionName,
+        input.publishedVersion,
+      ),
+      isPublishedVersion,
+      publishedAt: input.publishedAt,
+    },
+    definition: {
+      name: input.definitionName,
+      ownerDisplayName: input.ownerDisplayName,
+    },
+    revision: {
+      id: input.revision.id,
+      version: input.revision.version,
+      graphHash: input.revision.graphHash,
+      staticPipelineSummary: buildStaticPipelineSummary(
+        input.revision.staticPipeline,
+      ),
+      substeps: buildPublicSubsteps(input.revision.staticPipeline),
+      inputSchema: buildInputSchemaShape(input.revision.staticPipeline),
+      outputSchema: buildOutputSchemaShape(input.revision.staticPipeline),
+    },
+    copy: input.copy,
+    publicMetrics: input.metrics,
+  };
+}