@owlmeans/viable-common 0.0.43 → 0.0.44

package/src/branding.ts

@@ -1,22 +1,5 @@
 import type { SlotMetadata } from './types.js'
 
-/**
- * The build-time environment keys a generated application reads its branding from.
- *
- * Named here, once, because two processes emit them — the publisher for the preview and the agent
- * for a production publish — and a key spelled differently in one of them produces an application
- * that silently falls back to its defaults with nothing anywhere reporting it.
- */
-export const BRANDING_ENV_KEYS = [
-  'BRANDING_COPYRIGHT',
-  'BRANDING_ORGANIZATION',
-  'BRANDING_TERMS_URL',
-  'BRANDING_PRIVACY_URL',
-  'BRANDING_CREDIT',
-  'BRANDING_PRODUCT',
-  'BRANDING_GOOGLE_TAG',
-] as const
-
 /**
  * Slot metadata as build-time environment.
  *

package/src/connect/consts.ts

@@ -169,28 +169,6 @@ export const MODEL_TIER_ROLES: Record<string, ModelTier> = {
   'picker': ModelTier.Cheap,
 }
 
-export const tierOfRole = (role: string): ModelTier =>
-  MODEL_TIER_ROLES[role] ?? ModelTier.Standard
-
-/**
- * Pick the best tier a parent actually offers, never below what was asked for by more than the
- * offer allows.
- *
- * A parent that offers only one model answers every task with it; a parent that offers two gets
- * the nearer of the two. Silence is not an option — a task the connector cannot place is a run
- * that stops.
- */
-export const clampTier = (wanted: ModelTier, offered: ModelTier[]): ModelTier => {
-  if (offered.length < 1 || offered.includes(wanted)) return wanted
-  const ladder = [ModelTier.Strong, ModelTier.Standard, ModelTier.Cheap]
-  const from = ladder.indexOf(wanted)
-  // Prefer a stronger model over a weaker one: the task was sized for `wanted`.
-  for (let i = from; i >= 0; --i) if (offered.includes(ladder[i])) return ladder[i]
-  for (let i = from + 1; i < ladder.length; ++i) if (offered.includes(ladder[i])) return ladder[i]
-
-  return wanted
-}
-
 /** What the model task asks the parent's subagent to produce. */
 export enum ModelTaskMode {
   /** Prose or code. */

package/src/connect/entrypoints.ts

@@ -3,47 +3,16 @@ import { route, RouteMethod } from '@owlmeans/route'
 import { connect } from './consts.js'
 import {
   ConnectAttachBodySchema, ConnectConfirmBodySchema, ConnectConvertCreateBodySchema,
-  ConnectConvertProceedBodySchema, ConnectCreateBodySchema, ConnectInquiryParamsSchema, ConnectKitApplyBodySchema,
+  ConnectConvertProceedBodySchema, ConnectConvertStartBodySchema, ConnectCreateBodySchema,
+  ConnectInquiryParamsSchema, ConnectKitApplyBodySchema,
   ConnectModifyBodySchema, ConnectOpParamsSchema, ConnectOpResultSchema,
   ConnectPipelineParamsSchema, ConnectPipelineResumeBodySchema, ConnectProjectBrandingSaveSchema,
   ConnectProjectIdSchema, ConnectSessionOpenSchema, ConnectSessionParamsSchema, ConnectPullQuerySchema,
   ConnectStoryParamsSchema, InquiryAnswerSchema,
 } from './schemas.js'
-import type {
-  ConnectAttachBody, ConnectConfirmBody, ConnectConvertCreateBody, ConnectConvertProceedBody,
-  ConnectCreateBody, ConnectInquiryAnswerBody, ConnectKitApplyBody, ConnectKitApplyResult, ConnectKitDescribe,
-  ConnectModifyBody,
-  ConnectPipelineParams, ConnectPipelineResumeBody, ConnectProjectBranding,
-  ConnectProjectBrandingSave, ConnectSessionOpen,
-  ConnectPipelineState, ConnectProjectStatus, ConnectPullQuery, ConnectSessionParams,
-  ConnectStoryStatus, ConversionStatusView, ConvertCheck,
-} from './types.js'
+import type { ConnectAttachBody, ConnectConfirmBody, ConnectConvertCreateBody, ConnectConvertProceedBody, ConnectConvertStartBody, ConnectCreateBody, ConnectInquiryAnswerBody, ConnectKitApplyBody, ConnectKitApplyResult, ConnectKitDescribe, ConnectModifyBody, ConnectPipelineParams, ConnectPipelineResumeBody, ConnectProjectBranding, ConnectProjectBrandingSave, ConnectSessionOpen, ConnectPipelineState, ConnectProjectStatus, ConnectPullQuery, ConnectSessionParams, ConnectStoryStatus, ConversionStatusView, ConvertCheck, ConnectEntrypointOptions } from './types.js'
 import type { ConnectOpResult } from './ops.js'
 
-/**
- * What the platform injects when it mounts the connector routes.
- *
- * The names of the guard and the gates belong to the deployment, not to the contract: a connector
- * API on another platform would guard the same paths with its own vocabulary. Everything else —
- * paths, methods, schemas, parents — is fixed here so a client cannot address them differently.
- */
-export interface ConnectEntrypointOptions {
-  /** The guard alias every connector route carries. */
-  guard: string
-  /** The gate alias and parameters that decide project ownership. */
-  gate?: { alias: string, params: string[] }
-  /**
-   * The gate that decides whether the caller may use the local-LLM mode.
-   *
-   * Applied to the one route that turns it on — opening a delegated session. Everything else is
-   * free: `cloud` is the default, and a project's own override is the platform's browser surface,
-   * not the connector's.
-   */
-  localLlm?: { alias: string, params: string[] }
-  /** Path prefix; defaults to `/connect`. */
-  path?: string
-}
-
 /**
  * Declare the connector's HTTP surface — exactly the routes a connector calls: the session (long
  * poll, no socket), the operation relay, projects, story status, generated files, conversion,
@@ -216,7 +185,10 @@ export const connectProtocols = (opts: ConnectEntrypointOptions) => {
     ),
     start: protocol(
       route(connect.convert.start, '/convert/:id/start', { parent: base, method: RouteMethod.POST }),
-      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed<ConversionStatusView>()),
+      contract.request({
+        params: typed<{ id: string }>(ConnectProjectIdSchema),
+        body: typed<ConnectConvertStartBody>(ConnectConvertStartBodySchema),
+      }, typed<ConversionStatusView>()),
     ),
     proceed: protocol(
       route(connect.convert.proceed, '/convert/:id/proceed', { parent: base, method: RouteMethod.POST }),

package/src/connect/errors.ts

@@ -1,4 +1,5 @@
 import { ResilientError } from '@owlmeans/error'
+import type { ConnectConfirmation, ConnectConfirmationAction } from './types.js'
 
 export class ConnectError extends ResilientError {
   public static override typeName = `ViableConnect${ResilientError.typeName}`
@@ -191,6 +192,79 @@ export class ConnectConsentRequired extends ConnectError {
   }
 }
 
+/** A packed number read back: anything unreadable is `0`, never `NaN`. */
+const packedNumber = (value: string | undefined): number => {
+  const parsed = Number(value ?? 0)
+
+  return Number.isFinite(parsed) ? parsed : 0
+}
+
+/**
+ * A conversion verb would spend the plan's conversion or credits, and the caller has not said that a
+ * person agreed (`confirm: true`): a start that would use the organization's `conversions` unit, or a
+ * stage whose estimate reaches past what is left of the conversion limit into credit limits or
+ * topped-up credits. Nothing was started. The caller tells the person what it costs and repeats the
+ * call with `confirm: true` once they agree — unlike {@link ConnectConsentRequired}, this is agreed
+ * to in the conversation, not in the browser.
+ *
+ * Packed like the other two refusals a connector phrases for a person, because only `type` and
+ * `message` survive a marshal:
+ * `confirmation-required:<action>:<cap>:<spent>:<estimate>:<fromAllowance>:<fromCreditLimits>:<moneyUsd>`.
+ */
+export class ConnectConfirmationRequired extends ConnectError {
+  public static override typeName = `ConfirmationRequired${ConnectError.typeName}`
+  /** A precondition only a person can meet, not a fault: answered 428. */
+  public static httpStatus = 428
+
+  public action: ConnectConfirmationAction = 'convert-start'
+  public cap = 0
+  public spent = 0
+  public estimate = 0
+  public fromAllowance = 0
+  public fromCreditLimits = 0
+  public moneyUsd = 0
+
+  /** Build the packed message a caller passes to the constructor. */
+  static encode(fields: ConnectConfirmation): string {
+    return [
+      fields.action, fields.cap, fields.spent, fields.estimate, fields.fromAllowance, fields.fromCreditLimits,
+      fields.moneyUsd,
+    ].map(value => typeof value === 'number' && !Number.isFinite(value) ? 0 : value).join(':')
+  }
+
+  /** Read the packed fields back — what follows the marker, the inverse of {@link encode}. */
+  static decode(packed: string): ConnectConfirmation {
+    const [action, cap, spent, estimate, fromAllowance, fromCreditLimits, moneyUsd] = packed.split(':')
+
+    return {
+      action: (action ?? '') as ConnectConfirmationAction,
+      cap: packedNumber(cap),
+      spent: packedNumber(spent),
+      estimate: packedNumber(estimate),
+      fromAllowance: packedNumber(fromAllowance),
+      fromCreditLimits: packedNumber(fromCreditLimits),
+      moneyUsd: packedNumber(moneyUsd),
+    }
+  }
+
+  constructor(message: string = 'error') {
+    super(`confirmation-required:${message}`)
+    this.type = ConnectConfirmationRequired.typeName
+    this.applyFields()
+  }
+
+  private applyFields(): void {
+    const marker = 'confirmation-required:'
+    const at = this.message.lastIndexOf(marker)
+    if (at < 0) return
+    Object.assign(this, ConnectConfirmationRequired.decode(this.message.slice(at + marker.length)))
+  }
+
+  override finalizeUnmarshal(): void {
+    this.applyFields()
+  }
+}
+
 ResilientError.registerErrorClass(ConnectError)
 ResilientError.registerErrorClass(ConnectSessionNotFound)
 ResilientError.registerErrorClass(ConnectSessionGone)
@@ -200,3 +274,4 @@ ResilientError.registerErrorClass(LocalSlotUnsupported)
 ResilientError.registerErrorClass(ConnectOpUnknown)
 ResilientError.registerErrorClass(ConnectOutOfCredits)
 ResilientError.registerErrorClass(ConnectConsentRequired)
+ResilientError.registerErrorClass(ConnectConfirmationRequired)

package/src/connect/index.ts

@@ -1,4 +1,5 @@
 export * from './consts.js'
+export * from './utils.js'
 export * from './schemas.js'
 export * from './errors.js'
 export * from './entrypoints.js'

package/src/connect/references.ts

@@ -1,80 +1,7 @@
 import { entrypointRef } from '@owlmeans/entrypoint'
-import type { RegisteredEntrypoint, RequestShape } from '@owlmeans/entrypoint'
-import type { EntrypointReference } from '@owlmeans/context'
 import { connect } from './consts.js'
 import type { ConnectOp, ConnectOpResult } from './ops.js'
-import type {
-  ConnectAttachBody, ConnectConfirmBody, ConnectCreateBody, ConnectConvertCreateBody,
-  ConnectConvertProceedBody, ConnectInquiryAnswerBody, ConnectKitApplyBody, ConnectKitApplyResult,
-  ConnectKitDescribe, ConnectModifyBody, ConnectOpSubmission,
-  ConnectPipelineParams, ConnectPipelineResumeBody, ConnectPipelineState, ConnectProjectBranding,
-  ConnectProjectBrandingSave, ConnectProjectStatus, ConnectProjectSummary, ConnectPullQuery,
-  ConnectSessionOpen, ConnectSessionParams, ConnectSessionView, ConnectStoryStatus,
-  ConversionStatusView, ConvertCheck,
-} from './types.js'
-
-type ConnectReference<Request extends RequestShape, Response> =
-  EntrypointReference<RegisteredEntrypoint<Request, Response>>
-
-export interface ConnectReferences {
-  session: {
-    open: ConnectReference<{ body: ConnectSessionOpen }, ConnectSessionView>
-    openDelegated: ConnectReference<{ body: ConnectSessionOpen }, ConnectSessionView>
-    close: ConnectReference<{ params: ConnectSessionParams }, ConnectSessionView>
-  }
-  op: {
-    pull: ConnectReference<{ params: ConnectSessionParams, query: ConnectPullQuery }, ConnectOp[]>
-    submit: ConnectReference<{
-      params: { sessionId: string, opId: string }, body: ConnectOpResult
-    }, ConnectOpSubmission>
-  }
-  project: {
-    create: ConnectReference<{ body: ConnectCreateBody }, ConnectProjectStatus>
-    confirm: ConnectReference<{ params: { id: string }, body: ConnectConfirmBody }, ConnectProjectStatus>
-    list: ConnectReference<{}, ConnectProjectSummary[]>
-    status: ConnectReference<{ params: { id: string } }, ConnectProjectStatus>
-    attach: ConnectReference<{ body: ConnectAttachBody }, ConnectProjectStatus>
-    reinit: ConnectReference<{ params: { id: string } }, ConnectProjectStatus>
-    modify: ConnectReference<{ params: { id: string }, body: ConnectModifyBody }, ConnectProjectStatus>
-    kit: {
-      describe: ConnectReference<{ params: { id: string } }, ConnectKitDescribe>
-      apply: ConnectReference<{ params: { id: string }, body: ConnectKitApplyBody }, ConnectKitApplyResult>
-    }
-    branding: {
-      get: ConnectReference<{ params: { id: string } }, ConnectProjectBranding>
-      save: ConnectReference<{
-        params: { id: string }, body: ConnectProjectBrandingSave
-      }, ConnectProjectBranding>
-    }
-  }
-  story: {
-    status: ConnectReference<{ params: { id: string, storyId: string } }, ConnectStoryStatus>
-  }
-  files: {
-    list: ConnectReference<{ params: { id: string } }, string[]>
-  }
-  convert: {
-    create: ConnectReference<{ body: ConnectConvertCreateBody }, ConversionStatusView>
-    check: ConnectReference<{ params: { id: string } }, ConvertCheck>
-    start: ConnectReference<{ params: { id: string } }, ConversionStatusView>
-    proceed: ConnectReference<{
-      params: { id: string }, body: ConnectConvertProceedBody
-    }, ConversionStatusView>
-    status: ConnectReference<{ params: { id: string } }, ConversionStatusView>
-    purge: ConnectReference<{ params: { id: string } }, ConversionStatusView>
-  }
-  inquiry: {
-    answer: ConnectReference<{
-      params: { id: string, inquiryId: string }, body: ConnectInquiryAnswerBody
-    }, unknown>
-  }
-  pipeline: {
-    state: ConnectReference<{ params: ConnectPipelineParams }, ConnectPipelineState>
-    resume: ConnectReference<{
-      params: ConnectPipelineParams, body: ConnectPipelineResumeBody
-    }, ConnectPipelineState>
-  }
-}
+import type { ConnectAttachBody, ConnectConfirmBody, ConnectCreateBody, ConnectConvertCreateBody, ConnectConvertProceedBody, ConnectConvertStartBody, ConnectInquiryAnswerBody, ConnectKitApplyBody, ConnectKitApplyResult, ConnectKitDescribe, ConnectModifyBody, ConnectOpSubmission, ConnectPipelineParams, ConnectPipelineResumeBody, ConnectPipelineState, ConnectProjectBranding, ConnectProjectBrandingSave, ConnectProjectStatus, ConnectProjectSummary, ConnectPullQuery, ConnectSessionOpen, ConnectSessionParams, ConnectSessionView, ConnectStoryStatus, ConversionStatusView, ConvertCheck, ConnectReferences } from './types.js'
 
 /**
  * Typed references for adapter packages that address the connector dynamically.  Applications
@@ -122,7 +49,9 @@ export const connectRef: ConnectReferences = {
   convert: {
     create: entrypointRef<{ body: ConnectConvertCreateBody }, ConversionStatusView>(connect.convert.create),
     check: entrypointRef<{ params: { id: string } }, ConvertCheck>(connect.convert.check),
-    start: entrypointRef<{ params: { id: string } }, ConversionStatusView>(connect.convert.start),
+    start: entrypointRef<{
+      params: { id: string }, body: ConnectConvertStartBody
+    }, ConversionStatusView>(connect.convert.start),
     proceed: entrypointRef<{
       params: { id: string }, body: ConnectConvertProceedBody
     }, ConversionStatusView>(connect.convert.proceed),

package/src/connect/schemas.ts

@@ -9,6 +9,7 @@ import {
 import type { ConnectOpResult, InquiryAnswerPayload } from './ops.js'
 import type {
   ConnectAttachBody, ConnectConfirmBody, ConnectConvertCreateBody, ConnectConvertProceedBody,
+  ConnectConvertStartBody,
   ConnectCreateBody, ConnectLlmBody, ConnectModifyBody, ConnectPipelineParams,
   ConnectPipelineResumeBody, ConnectProjectBrandingSave, ConnectProjectLlmBody, ConnectSession,
   ConnectSessionOpen, ConnectPullQuery, ConnectSessionParams, ConnectKitApplyBody, ConnectKitApplyResult,
@@ -377,11 +378,21 @@ export const ConnectConvertCreateBodySchema = {
   additionalProperties: false,
 } as unknown as JSONSchemaType<ConnectConvertCreateBody>
 
+export const ConnectConvertStartBodySchema = {
+  type: 'object',
+  properties: {
+    confirm: { type: 'boolean', nullable: true },
+  },
+  required: [],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<ConnectConvertStartBody>
+
 export const ConnectConvertProceedBodySchema = {
   type: 'object',
   properties: {
     decision: { type: 'string', enum: Object.values(ConversionDecision) },
     note: { type: 'string', maxLength: 4096, nullable: true },
+    confirm: { type: 'boolean', nullable: true },
   },
   required: ['decision'],
   additionalProperties: false,

package/src/connect/types.local.ts

@@ -0,0 +1,5 @@
+import type { RegisteredEntrypoint, RequestShape } from '@owlmeans/entrypoint'
+import type { EntrypointReference } from '@owlmeans/context'
+
+export type ConnectReference<Request extends RequestShape, Response> =
+  EntrypointReference<RegisteredEntrypoint<Request, Response>>

package/src/connect/types.ts

@@ -7,7 +7,8 @@ import type {
   ConnectExecutor, ConnectHarness, ConnectLlm, ConnectSessionStatus, ConnectTarget,
   ConnectTransport, ConnectWaitReason, ModelTier
 } from './consts.js'
-import type { InquiryAnswerPayload, InquiryPayload } from './ops.js'
+import type { InquiryAnswerPayload, InquiryPayload, ConnectOp, ConnectOpResult } from './ops.js'
+import type { ConnectReference } from './types.local.js'
 
 /**
  * What a parent agent can do, as it reports itself.
@@ -316,11 +317,28 @@ export interface ConnectConvertCreateBody {
   origin?: { kind: OriginKind, repoUrl?: string, branch?: string }
 }
 
+/**
+ * Start the conversion of a project already filed.
+ *
+ * `confirm` says a PERSON agreed to what the start uses: without it, a start that would spend the
+ * organization's `conversions` unit is refused with `ConnectConfirmationRequired` and nothing runs.
+ * A delegated conversion spends nothing and is never asked.
+ */
+export interface ConnectConvertStartBody {
+  confirm?: boolean
+}
+
 /** Decide what happens at a stage boundary. */
 export interface ConnectConvertProceedBody {
   decision: ConversionDecision
   /** Free text the user added to the decision; recorded, never parsed. */
   note?: string
+  /**
+   * A person agreed to what the stage costs. Without it, a stage that would spend credit limits or
+   * topped-up credits (its estimate past what is left of the conversion limit) is refused with
+   * `ConnectConfirmationRequired` — its estimate split packed — and nothing runs.
+   */
+  confirm?: boolean
 }
 
 /** Answer one question a parked run is waiting on. */
@@ -464,3 +482,108 @@ export interface ConnectKitApplyResult {
   skipped: string[]
   warnings: string[]
 }
+
+/**
+ * What the platform injects when it mounts the connector routes.
+ *
+ * The names of the guard and the gates belong to the deployment, not to the contract: a connector
+ * API on another platform would guard the same paths with its own vocabulary. Everything else —
+ * paths, methods, schemas, parents — is fixed here so a client cannot address them differently.
+ */
+export interface ConnectEntrypointOptions {
+  /** The guard alias every connector route carries. */
+  guard: string
+  /** The gate alias and parameters that decide project ownership. */
+  gate?: { alias: string, params: string[] }
+  /**
+   * The gate that decides whether the caller may use the local-LLM mode.
+   *
+   * Applied to the one route that turns it on — opening a delegated session. Everything else is
+   * free: `cloud` is the default, and a project's own override is the platform's browser surface,
+   * not the connector's.
+   */
+  localLlm?: { alias: string, params: string[] }
+  /** Path prefix; defaults to `/connect`. */
+  path?: string
+}
+
+/** The conversion verb a {@link ConnectConfirmationRequired} stopped. */
+export type ConnectConfirmationAction = 'convert-start' | 'convert-proceed'
+
+/**
+ * What a person is asked to agree to before a conversion verb spends anything — credits, except
+ * `moneyUsd`. `cap` is the plan's conversion limit this conversion runs under (`0` when no plan unit
+ * covers it) and `spent` what the conversion has used of it so far; `estimate` is the stage's
+ * estimate (`0` while nothing has priced it), of which `fromAllowance` comes from the conversion
+ * limit, `fromCreditLimits` from the organization's open credit limits, and the rest from topped-up
+ * credits — `moneyUsd`, the only money figure.
+ */
+export interface ConnectConfirmation {
+  action: ConnectConfirmationAction
+  cap: number
+  spent: number
+  estimate: number
+  fromAllowance: number
+  fromCreditLimits: number
+  moneyUsd: number
+}
+
+export interface ConnectReferences {
+  session: {
+    open: ConnectReference<{ body: ConnectSessionOpen }, ConnectSessionView>
+    openDelegated: ConnectReference<{ body: ConnectSessionOpen }, ConnectSessionView>
+    close: ConnectReference<{ params: ConnectSessionParams }, ConnectSessionView>
+  }
+  op: {
+    pull: ConnectReference<{ params: ConnectSessionParams, query: ConnectPullQuery }, ConnectOp[]>
+    submit: ConnectReference<{
+      params: { sessionId: string, opId: string }, body: ConnectOpResult
+    }, ConnectOpSubmission>
+  }
+  project: {
+    create: ConnectReference<{ body: ConnectCreateBody }, ConnectProjectStatus>
+    confirm: ConnectReference<{ params: { id: string }, body: ConnectConfirmBody }, ConnectProjectStatus>
+    list: ConnectReference<{}, ConnectProjectSummary[]>
+    status: ConnectReference<{ params: { id: string } }, ConnectProjectStatus>
+    attach: ConnectReference<{ body: ConnectAttachBody }, ConnectProjectStatus>
+    reinit: ConnectReference<{ params: { id: string } }, ConnectProjectStatus>
+    modify: ConnectReference<{ params: { id: string }, body: ConnectModifyBody }, ConnectProjectStatus>
+    kit: {
+      describe: ConnectReference<{ params: { id: string } }, ConnectKitDescribe>
+      apply: ConnectReference<{ params: { id: string }, body: ConnectKitApplyBody }, ConnectKitApplyResult>
+    }
+    branding: {
+      get: ConnectReference<{ params: { id: string } }, ConnectProjectBranding>
+      save: ConnectReference<{
+        params: { id: string }, body: ConnectProjectBrandingSave
+      }, ConnectProjectBranding>
+    }
+  }
+  story: {
+    status: ConnectReference<{ params: { id: string, storyId: string } }, ConnectStoryStatus>
+  }
+  files: {
+    list: ConnectReference<{ params: { id: string } }, string[]>
+  }
+  convert: {
+    create: ConnectReference<{ body: ConnectConvertCreateBody }, ConversionStatusView>
+    check: ConnectReference<{ params: { id: string } }, ConvertCheck>
+    start: ConnectReference<{ params: { id: string }, body: ConnectConvertStartBody }, ConversionStatusView>
+    proceed: ConnectReference<{
+      params: { id: string }, body: ConnectConvertProceedBody
+    }, ConversionStatusView>
+    status: ConnectReference<{ params: { id: string } }, ConversionStatusView>
+    purge: ConnectReference<{ params: { id: string } }, ConversionStatusView>
+  }
+  inquiry: {
+    answer: ConnectReference<{
+      params: { id: string, inquiryId: string }, body: ConnectInquiryAnswerBody
+    }, unknown>
+  }
+  pipeline: {
+    state: ConnectReference<{ params: ConnectPipelineParams }, ConnectPipelineState>
+    resume: ConnectReference<{
+      params: ConnectPipelineParams, body: ConnectPipelineResumeBody
+    }, ConnectPipelineState>
+  }
+}

package/src/connect/utils.ts

@@ -0,0 +1,23 @@
+import { MODEL_TIER_ROLES, ModelTier } from './consts.js'
+
+export const tierOfRole = (role: string): ModelTier =>
+  MODEL_TIER_ROLES[role] ?? ModelTier.Standard
+
+/**
+ * Pick the best tier a parent actually offers, never below what was asked for by more than the
+ * offer allows.
+ *
+ * A parent that offers only one model answers every task with it; a parent that offers two gets
+ * the nearer of the two. Silence is not an option — a task the connector cannot place is a run
+ * that stops.
+ */
+export const clampTier = (wanted: ModelTier, offered: ModelTier[]): ModelTier => {
+  if (offered.length < 1 || offered.includes(wanted)) return wanted
+  const ladder = [ModelTier.Strong, ModelTier.Standard, ModelTier.Cheap]
+  const from = ladder.indexOf(wanted)
+  // Prefer a stronger model over a weaker one: the task was sized for `wanted`.
+  for (let i = from; i >= 0; --i) if (offered.includes(ladder[i])) return ladder[i]
+  for (let i = from + 1; i < ladder.length; ++i) if (offered.includes(ladder[i])) return ladder[i]
+
+  return wanted
+}

package/src/consts.ts

@@ -35,3 +35,20 @@ export const metadataSecrets = [
   'dbAppPassword',
   'valkeyPassword',
 ] satisfies (keyof SlotSecretMetadata)[]
+
+/**
+ * The build-time environment keys a generated application reads its branding from.
+ *
+ * Named here, once, because two processes emit them — the publisher for the preview and the agent
+ * for a production publish — and a key spelled differently in one of them produces an application
+ * that silently falls back to its defaults with nothing anywhere reporting it.
+ */
+export const BRANDING_ENV_KEYS = [
+  'BRANDING_COPYRIGHT',
+  'BRANDING_ORGANIZATION',
+  'BRANDING_TERMS_URL',
+  'BRANDING_PRIVACY_URL',
+  'BRANDING_CREDIT',
+  'BRANDING_PRODUCT',
+  'BRANDING_GOOGLE_TAG',
+] as const

package/src/convert/consts.local.ts

@@ -0,0 +1,120 @@
+import { FileClass } from './consts.js'
+
+/**
+ * Extension → class, for the extensions that decide a file on their own.
+ *
+ * Deliberately not exhaustive: a path rule below overrides it wherever the location says more than
+ * the tail does (a `.ts` under `tests/` is a test, a `.json` under `seed/` is data).
+ */
+export const EXT_CLASS: Record<string, FileClass> = {
+  ts: FileClass.Source, tsx: FileClass.Source, js: FileClass.Source, jsx: FileClass.Source,
+  mjs: FileClass.Source, cjs: FileClass.Source, mts: FileClass.Source, cts: FileClass.Source,
+  vue: FileClass.Source, svelte: FileClass.Source, java: FileClass.Source, kt: FileClass.Source,
+  kts: FileClass.Source, go: FileClass.Source, py: FileClass.Source, rb: FileClass.Source,
+  php: FileClass.Source, cs: FileClass.Source, ex: FileClass.Source, exs: FileClass.Source,
+  rs: FileClass.Source, sql: FileClass.Source, sh: FileClass.Source,
+
+  css: FileClass.Style, scss: FileClass.Style, sass: FileClass.Style, less: FileClass.Style,
+  styl: FileClass.Style,
+
+  md: FileClass.Doc, mdx: FileClass.Doc, rst: FileClass.Doc, adoc: FileClass.Doc,
+  txt: FileClass.Doc,
+
+  json: FileClass.Config, yaml: FileClass.Config, yml: FileClass.Config, toml: FileClass.Config,
+  ini: FileClass.Config, env: FileClass.Config, properties: FileClass.Config,
+  xml: FileClass.Config, conf: FileClass.Config,
+
+  html: FileClass.Template, htm: FileClass.Template, hbs: FileClass.Template,
+  ejs: FileClass.Template, pug: FileClass.Template, twig: FileClass.Template,
+  erb: FileClass.Template, jinja: FileClass.Template, j2: FileClass.Template,
+
+  csv: FileClass.Data, tsv: FileClass.Data, ndjson: FileClass.Data, jsonl: FileClass.Data,
+  parquet: FileClass.Data, dump: FileClass.Data,
+
+  png: FileClass.Binary, jpg: FileClass.Binary, jpeg: FileClass.Binary, gif: FileClass.Binary,
+  webp: FileClass.Binary, ico: FileClass.Binary, pdf: FileClass.Binary, zip: FileClass.Binary,
+  gz: FileClass.Binary, tar: FileClass.Binary, woff: FileClass.Binary, woff2: FileClass.Binary,
+  ttf: FileClass.Binary, otf: FileClass.Binary, mp4: FileClass.Binary, mp3: FileClass.Binary,
+  wasm: FileClass.Binary, jar: FileClass.Binary, so: FileClass.Binary, dll: FileClass.Binary,
+}
+
+/** Exact basenames that are a package manifest whatever their extension says. */
+export const MANIFEST_NAMES = [
+  'package.json', 'deno.json', 'pom.xml', 'build.gradle', 'build.gradle.kts',
+  'settings.gradle', 'settings.gradle.kts', 'go.mod', 'cargo.toml', 'pyproject.toml',
+  'requirements.txt', 'pipfile', 'composer.json', 'gemfile', 'mix.exs',
+]
+
+/** Exact basenames that are a lockfile — never read, never counted as source. */
+export const LOCK_NAMES = [
+  'bun.lock', 'bun.lockb', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml', 'go.sum',
+  'cargo.lock', 'composer.lock', 'gemfile.lock', 'poetry.lock', 'pipfile.lock', 'mix.lock',
+]
+
+/**
+ * Path segments whose contents are produced by a build and say nothing about the application.
+ *
+ * `bin` is deliberately absent though `obj` is here: it is .NET/Java output in two of the nine
+ * ecosystems the converter reads and a real entrypoint directory in the rest (`bin/cli.ts`,
+ * `bin/console`, `bin/rails`), and this function is handed one path with no tree around it to
+ * tell the two apart. Dropping those entrypoints out of every source listing is the worse error.
+ */
+export const GENERATED_SEGMENTS = [
+  'node_modules', 'dist', 'build', 'out', 'target', 'vendor', '.next', '.nuxt', '.svelte-kit',
+  '.turbo', '.gradle', '__pycache__', 'coverage', '.venv', 'obj',
+]
+
+/** Path segments that make a file a test wherever its extension would have said otherwise. */
+export const TEST_SEGMENTS = ['test', 'tests', '__tests__', 'spec', 'specs', 'e2e']
+
+/**
+ * The classes a seed or dump LOCATION is allowed to override.
+ *
+ * A seed directory says what a file holds, not what language it is written in — so it reclassifies
+ * a payload and never a program. `seed/users.json` is data; `src/seedUsers.ts` is the code that
+ * loads it, and `src/exportReport.ts` is a screen, and pushing either into the data budget takes
+ * real source out of the census's reach.
+ */
+export const DATA_OVERRIDABLE: FileClass[] = [
+  FileClass.Data, FileClass.Config, FileClass.Binary, FileClass.Unknown,
+]
+
+/**
+ * The extensions that are as often a dump as they are a program.
+ *
+ * A `.sql` under `migrations/` is schema somebody wrote and a coder has to reproduce; the same
+ * tail under `dumps/` is an export nothing should read into a prompt. The location is the only
+ * thing that separates them, so it outranks the tail for these and for no other language.
+ */
+export const DATA_AMBIGUOUS_EXT = ['sql']
+
+/**
+ * Extensions whose tail already answers the binary question, either way.
+ *
+ * Deliberately two lists and not one with a default: an extension the census has never seen must
+ * be READ rather than guessed at, because a repository nobody here wrote carries tails nobody
+ * here chose. Nothing in either list is a guess about content — a `.ts` holding a NUL byte is a
+ * corrupt file, and a `.png` that is not binary is not a `.png`.
+ */
+export const TEXT_EXTENSIONS: readonly string[] = [
+  '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts', '.json', '.jsonc',
+  '.md', '.mdx', '.txt', '.css', '.scss', '.sass', '.less', '.html', '.htm', '.xml', '.svg',
+  '.yml', '.yaml', '.toml', '.ini', '.env', '.sh', '.bash', '.zsh', '.sql', '.graphql', '.gql',
+  '.py', '.rb', '.go', '.rs', '.java', '.kt', '.php', '.cs', '.c', '.h', '.cpp', '.hpp', '.swift',
+  '.vue', '.svelte', '.astro', '.lock', '.csv',
+]
+
+export const BINARY_EXTENSIONS: readonly string[] = [
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.bmp', '.ico', '.icns', '.tiff',
+  '.mp3', '.mp4', '.wav', '.ogg', '.webm', '.mov', '.avi',
+  '.woff', '.woff2', '.ttf', '.otf', '.eot',
+  '.pdf', '.zip', '.gz', '.tgz', '.bz2', '.xz', '.7z', '.rar', '.tar',
+  '.wasm', '.node', '.so', '.dylib', '.dll', '.exe', '.bin', '.class', '.jar',
+  '.db', '.sqlite', '.sqlite3',
+]
+
+/** Path segments and name fragments that mark bulk data — an export, not the app's own data. */
+export const BULK_HINTS = ['dump', 'dumps', 'export', 'exports', 'backup', 'backups', 'snapshot', 'archive']
+
+/** Path segments that mark seed data — what the application needs in order to make sense. */
+export const SEED_HINTS = ['seed', 'seeds', 'fixture', 'fixtures', 'sample', 'samples', 'demo-data']