@owlmeans/viable-common 0.0.44 → 0.0.46

package/src/areas/tenancy/types.ts

@@ -0,0 +1,23 @@
+import type { Blueprint } from '../../blueprint/types.js'
+import type { ProjectArea } from '../consts.js'
+import type { ProjectTenancy } from '../types.js'
+
+/** Which of a product's audiences act inside a tenant organization. */
+export interface TenancyHelper {
+  /**
+   * The tenancy of a resolved blueprint.
+   *
+   * Total, like `landingGatePreferenceOf`: an absent layer, an absent key and a value this deploy
+   * cannot read all answer {@link NO_TENANCY}. Only a literal `true` turns a flag on, because a flag
+   * read as on by mistake splits a product's people into organizations nobody asked for, while one
+   * read as off leaves the application exactly as it was before tenancy existed.
+   */
+  tenancyOf: (blueprint?: Pick<Blueprint, 'experience'> | null) => ProjectTenancy
+  /**
+   * Whether an AREA's people act inside a tenant organization.
+   *
+   * Guest has no organization to act in, and admin is the project owner, who stands above every
+   * tenant rather than inside one — so both are never tenanted, whatever the flags say.
+   */
+  tenantedArea: (area: ProjectArea, tenancy: ProjectTenancy) => boolean
+}

package/src/areas/tenancy.ts

@@ -1,33 +1,34 @@
 import type { Blueprint } from '../blueprint/types.js'
 import { ProjectArea, NO_TENANCY } from './consts.js'
 import type { ProjectTenancy } from './types.js'
+import type { TenancyHelper } from './tenancy/types.js'
 
-/**
- * The tenancy of a resolved blueprint.
- *
- * Total, like `landingGatePreferenceOf`: an absent layer, an absent key and a value this deploy
- * cannot read all answer {@link NO_TENANCY}. Only a literal `true` turns a flag on, because a flag
- * read as on by mistake splits a product's people into organizations nobody asked for, while one
- * read as off leaves the application exactly as it was before tenancy existed.
- */
-export const tenancyOf = (blueprint?: Pick<Blueprint, 'experience'> | null): ProjectTenancy => {
-  const tenancy = blueprint?.experience?.tenancy
-  const operators = tenancy?.operators === true
-  const users = tenancy?.users === true
+export const createTenancyHelper = (): TenancyHelper => {
+  const tenancyOf = (blueprint?: Pick<Blueprint, 'experience'> | null): ProjectTenancy => {
+    const tenancy = blueprint?.experience?.tenancy
+    const operators = tenancy?.operators === true
+    const users = tenancy?.users === true
 
-  return operators || users ? Object.freeze({ operators, users }) : NO_TENANCY
-}
+    return operators || users ? Object.freeze({ operators, users }) : NO_TENANCY
+  }
 
-/**
- * Whether an AREA's people act inside a tenant organization.
- *
- * Guest has no organization to act in, and admin is the project owner, who stands above every
- * tenant rather than inside one — so both are never tenanted, whatever the flags say.
- */
-export const tenantedArea = (area: ProjectArea, tenancy: ProjectTenancy): boolean => {
-  switch (area) {
-    case ProjectArea.User: return tenancy.users === true
-    case ProjectArea.Operator: return tenancy.operators === true
-    default: return false
+  const tenantedArea = (area: ProjectArea, tenancy: ProjectTenancy): boolean => {
+    switch (area) {
+      case ProjectArea.User: return tenancy.users === true
+      case ProjectArea.Operator: return tenancy.operators === true
+      default: return false
+    }
   }
+
+  return { tenancyOf, tenantedArea }
 }
+
+export const tenancyHelper = createTenancyHelper()
+
+/** @deprecated compat:factory-refactor — use `tenancyHelper.tenancyOf(…)` */
+export const tenancyOf = (blueprint?: Pick<Blueprint, 'experience'> | null): ProjectTenancy =>
+  tenancyHelper.tenancyOf(blueprint)
+
+/** @deprecated compat:factory-refactor — use `tenancyHelper.tenantedArea(…)` */
+export const tenantedArea = (area: ProjectArea, tenancy: ProjectTenancy): boolean =>
+  tenancyHelper.tenantedArea(area, tenancy)

package/src/ba/connecting/types.ts

@@ -0,0 +1,45 @@
+import type { StoryDraft } from '../../areas/types.js'
+import type { ConnectingStoryDraft, MergedStoryDraft } from '../types.js'
+
+/** The connecting stories of a flow: how many it may carry, and where each one lands. */
+export interface ConnectingStoryHelper {
+  /**
+   * How many connecting stories one flow may carry.
+   *
+   * An N-step chain has N-1 joints, and a connecting story exists to bridge one of them — so the
+   * flow sizes its own supporting cast, and a three-step product can never end up with eight list
+   * screens. It is a CEILING, not a target: the prompt is told to write as few as its rules actually
+   * derived, and most flows land well below this.
+   *
+   * The real reason for a hard number: every story here becomes a full develop run the project's
+   * owner pays for.
+   */
+  connectingStoryCap: (flowCount: number) => number
+  /**
+   * Interleave the connecting stories into the flow they were derived from.
+   *
+   * `after` is an ANCHOR, not a position: it names the flow story whose result the connecting story
+   * displays, so the connecting story lands immediately behind it — which is also immediately in
+   * front of the step it leads into. The result is ONE ordered list, and it is the order records are
+   * created in.
+   *
+   * This is the only place the anchor is interpreted. Both halves of the feature — the prompt that
+   * produces it and the pipeline that persists the result — read it through here, or the two drift
+   * and nothing fails loudly enough to notice. The CLAMPED anchor is carried out on each connective
+   * entry as `after`, which is what the story card's `follows` relationship is written from.
+   *
+   * Four properties are deliberate:
+   *
+   * - **The flow subsequence is never disturbed.** Strip the connecting stories back out and you have
+   *   `flow`, in `flow` order: story N still implements numbered step N. Everything that finds the
+   *   primary story depends on that.
+   * - **Nothing precedes the first flow story.** An anchor below 1 is clamped up rather than opening a
+   *   position in front of the flow — nothing can be listed before the step that produced it, and
+   *   story 1 stays the enabling action.
+   * - **A placement is advice; the story is work already paid for.** An anchor past the end means
+   *   "at the end", and one that is not a number at all means the front of the flow. Neither is a
+   *   reason to lose a story.
+   * - **Ties keep the model's order**, which is the only ranking anything has.
+   */
+  mergeConnectingStories: (flow: StoryDraft[], connecting: ConnectingStoryDraft[]) => MergedStoryDraft[]
+}

package/src/ba/connecting.ts

@@ -0,0 +1,64 @@
+import type { StoryDraft } from "../areas/types.js"
+import type { ConnectingStoryDraft, MergedStoryDraft } from "./types.js"
+import { StoryKind } from "./consts.js"
+import type { ConnectingStoryHelper } from './connecting/types.js'
+
+export const createConnectingStoryHelper = (): ConnectingStoryHelper => {
+  const connectingStoryCap = (flowCount: number): number => Math.max(flowCount - 1, 0)
+
+  /** Collapse case and whitespace, so "the same story twice" is recognised as such. */
+  const canonical = (story: string): string => story.trim().replace(/\s+/g, ' ').toLowerCase()
+
+  const mergeConnectingStories = (
+    flow: StoryDraft[], connecting: ConnectingStoryDraft[]
+  ): MergedStoryDraft[] => {
+    if (flow.length < 1) {
+      return []
+    }
+
+    const seen = new Set(flow.map(({ story }) => canonical(story)))
+    const placed: Array<{ draft: ConnectingStoryDraft, at: number }> = []
+
+    for (const draft of connecting) {
+      const text = canonical(draft.story)
+      // A connecting story that repeats a flow story is not a second story: it is one develop run
+      // spent twice AND — since the home-screen detector matches its answer back by exact text — a
+      // second record that answer could resolve to.
+      if (text === '' || seen.has(text)) {
+        continue
+      }
+      seen.add(text)
+
+      const after = Number(draft.after)
+      placed.push({
+        draft,
+        at: Number.isFinite(after) ? Math.min(Math.max(Math.trunc(after), 1), flow.length) : 1,
+      })
+    }
+
+    // Over the cap, the LATEST-anchored go: a story late in the flow gates the fewest steps behind
+    // it, while the queue that hands step 1 to step 2 is what makes everything after it reachable.
+    // The sort is stable, so two stories on the same step keep the order they were derived in.
+    const surviving = placed
+      .map((entry, order) => ({ ...entry, order }))
+      .sort((a, b) => a.at - b.at || a.order - b.order)
+      .slice(0, connectingStoryCap(flow.length))
+
+    // Bucket N holds what comes immediately after flow story N (1-based, as the prompt numbers them).
+    const buckets: ConnectingStoryDraft[][] = flow.map(() => [])
+    for (const { draft, at } of surviving) {
+      buckets[at - 1]!.push(draft)
+    }
+
+    return flow.flatMap(({ story, area }, index) => [
+      { story, area, kind: StoryKind.Flow },
+      ...buckets[index]!.map(draft => (
+        { story: draft.story.trim(), area: draft.area, kind: StoryKind.Connective, after: index + 1 }
+      )),
+    ])
+  }
+
+  return { connectingStoryCap, mergeConnectingStories }
+}
+
+export const connectingStoryHelper = createConnectingStoryHelper()

package/src/ba/helpers.ts

@@ -1,94 +1,10 @@
-import type { StoryDraft } from "../areas/types.js"
-import type { ConnectingStoryDraft, MergedStoryDraft } from "./types.js"
-import { StoryKind } from "./consts.js"
+import type { StoryDraft } from '../areas/types.js'
+import { connectingStoryHelper } from './connecting.js'
+import type { ConnectingStoryDraft, MergedStoryDraft } from './types.js'
 
-/**
- * How many connecting stories one flow may carry.
- *
- * An N-step chain has N-1 joints, and a connecting story exists to bridge one of them — so the
- * flow sizes its own supporting cast, and a three-step product can never end up with eight list
- * screens. It is a CEILING, not a target: the prompt is told to write as few as its rules actually
- * derived, and most flows land well below this.
- *
- * The real reason for a hard number: every story here becomes a full develop run the project's
- * owner pays for.
- */
-export const connectingStoryCap = (flowCount: number): number => Math.max(flowCount - 1, 0)
+/** @deprecated compat:factory-refactor — use `connectingStoryHelper.connectingStoryCap(…)` */
+export const connectingStoryCap = (flowCount: number): number => connectingStoryHelper.connectingStoryCap(flowCount)
 
-/** Collapse case and whitespace, so "the same story twice" is recognised as such. */
-const canonical = (story: string): string => story.trim().replace(/\s+/g, ' ').toLowerCase()
-
-/**
- * Interleave the connecting stories into the flow they were derived from.
- *
- * `after` is an ANCHOR, not a position: it names the flow story whose result the connecting story
- * displays, so the connecting story lands immediately behind it — which is also immediately in
- * front of the step it leads into. The result is ONE ordered list, and it is the order records are
- * created in.
- *
- * This is the only place the anchor is interpreted. Both halves of the feature — the prompt that
- * produces it and the pipeline that persists the result — read it through here, or the two drift
- * and nothing fails loudly enough to notice. The CLAMPED anchor is carried out on each connective
- * entry as `after`, which is what the story card's `follows` relationship is written from.
- *
- * Four properties are deliberate:
- *
- * - **The flow subsequence is never disturbed.** Strip the connecting stories back out and you have
- *   `flow`, in `flow` order: story N still implements numbered step N. Everything that finds the
- *   primary story depends on that.
- * - **Nothing precedes the first flow story.** An anchor below 1 is clamped up rather than opening a
- *   position in front of the flow — nothing can be listed before the step that produced it, and
- *   story 1 stays the enabling action.
- * - **A placement is advice; the story is work already paid for.** An anchor past the end means
- *   "at the end", and one that is not a number at all means the front of the flow. Neither is a
- *   reason to lose a story.
- * - **Ties keep the model's order**, which is the only ranking anything has.
- */
-export const mergeConnectingStories = (
-  flow: StoryDraft[], connecting: ConnectingStoryDraft[]
-): MergedStoryDraft[] => {
-  if (flow.length < 1) {
-    return []
-  }
-
-  const seen = new Set(flow.map(({ story }) => canonical(story)))
-  const placed: Array<{ draft: ConnectingStoryDraft, at: number }> = []
-
-  for (const draft of connecting) {
-    const text = canonical(draft.story)
-    // A connecting story that repeats a flow story is not a second story: it is one develop run
-    // spent twice AND — since the home-screen detector matches its answer back by exact text — a
-    // second record that answer could resolve to.
-    if (text === '' || seen.has(text)) {
-      continue
-    }
-    seen.add(text)
-
-    const after = Number(draft.after)
-    placed.push({
-      draft,
-      at: Number.isFinite(after) ? Math.min(Math.max(Math.trunc(after), 1), flow.length) : 1,
-    })
-  }
-
-  // Over the cap, the LATEST-anchored go: a story late in the flow gates the fewest steps behind
-  // it, while the queue that hands step 1 to step 2 is what makes everything after it reachable.
-  // The sort is stable, so two stories on the same step keep the order they were derived in.
-  const surviving = placed
-    .map((entry, order) => ({ ...entry, order }))
-    .sort((a, b) => a.at - b.at || a.order - b.order)
-    .slice(0, connectingStoryCap(flow.length))
-
-  // Bucket N holds what comes immediately after flow story N (1-based, as the prompt numbers them).
-  const buckets: ConnectingStoryDraft[][] = flow.map(() => [])
-  for (const { draft, at } of surviving) {
-    buckets[at - 1]!.push(draft)
-  }
-
-  return flow.flatMap(({ story, area }, index) => [
-    { story, area, kind: StoryKind.Flow },
-    ...buckets[index]!.map(draft => (
-      { story: draft.story.trim(), area: draft.area, kind: StoryKind.Connective, after: index + 1 }
-    )),
-  ])
-}
+/** @deprecated compat:factory-refactor — use `connectingStoryHelper.mergeConnectingStories(…)` */
+export const mergeConnectingStories = (flow: StoryDraft[], connecting: ConnectingStoryDraft[]): MergedStoryDraft[] =>
+  connectingStoryHelper.mergeConnectingStories(flow, connecting)

package/src/ba/index.ts

@@ -1,4 +1,6 @@
 
+export * from './connecting.js'
 export * from './helpers.js'
 export * from './consts.js'
 export type * from './types.js'
+export type * from './connecting/types.js'

package/src/blueprint/types.ts

@@ -1,7 +1,6 @@
 import type { ProjectTenancy } from '../areas/types.js'
 import type { SubProject } from '../slot/consts.js'
-import type { ViableSkill } from '../skills/consts.js'
-import type { ViablePersona } from '../skills/roles.js'
+import type { ViablePersona, ViableSkill } from '../skills/consts.js'
 import type { TopologyDescriptor } from '../topology/types.js'
 import { BlueprintPatchKind, LandingGatePreference } from './consts.js'
 
@@ -189,6 +188,7 @@ export interface BlueprintCapabilities {
   marketingConsent: boolean
 }
 
+// Kept as a type: a mapped type over the blueprint's keys.
 /** A partial override of a blueprint, deep-merged over the resolved value. */
 export type BlueprintPatch = {
   [K in keyof Blueprint]?: Blueprint[K] extends string ? Blueprint[K] : Partial<Blueprint[K]>

package/src/connect/branding/types.ts

@@ -0,0 +1,29 @@
+
+
+/**
+ * A project's branding as a connector reads it — what the generated application says about who
+ * made it, and the Google tag it loads.
+ *
+ * Every field is a string, `''` when unset, in the platform's own branding vocabulary. The
+ * platform credit is absent on purpose: hiding it is a paid capability behind its own gated route,
+ * and neither reading nor saving this record may reach it.
+ */
+export interface ConnectProjectBranding {
+  /** The copyright line in the application's footer. Never empty once saved. */
+  copyright: string
+  /** The organization's display name. Never empty once saved. */
+  organizationName: string
+  /** `''`, an `https://` URL, or a same-origin path such as `/terms` (the generated page). */
+  termsUrl: string
+  /** `''`, an `https://` URL, or a same-origin path such as `/privacy` (the generated page). */
+  privacyUrl: string
+  /** `''`, or a Google tag id: `GTM-…`, `G-…`, `GT-…`, `AW-…`, `DC-…`. */
+  googleTag: string
+}
+
+/**
+ * A PATCH of a project's branding: every field optional, and an absent field keeps its current
+ * value. The platform merges it over what is stored, validates the result as a whole with the
+ * rules the web form uses, and answers the merged record.
+ */
+export interface ConnectProjectBrandingSave extends Partial<ConnectProjectBranding> {}

package/src/connect/consts.ts

@@ -412,3 +412,6 @@ export const connect = Object.freeze({
     resume: 'viable:manager-api:connect:pipeline:resume',
   }),
 })
+
+/** Tier → the model the parent will run it on. Free-form; display only. */
+export const ModelTierValues = Object.values(ModelTier)

package/src/connect/conversion/types.ts

@@ -0,0 +1,96 @@
+import type {
+  ArchitectureCase, ConversionDecision, ConversionStage, ConversionStatus, ConvertibilityReason,
+  ConvertibilityVerdict, OriginKind, OriginShape, OriginState
+} from '../../convert/consts.js'
+import type { ConversionEstimate, StoryEstimateBand } from '../../convert/estimate/types.js'
+import type { ConversionStackRef } from '../../convert/record/types.js'
+import type { ConnectTarget, ConnectWaitReason } from '../consts.js'
+import type { InquiryPayload } from '../ops/types.js'
+
+/** Start a conversion of an existing project's code. */
+export interface ConnectConvertCreateBody {
+  name?: string
+  about?: string
+  /** Where the converted target's tree will live. */
+  target?: ConnectTarget
+  /**
+   * Where the code comes from.
+   *
+   * Absent for a LOCAL target the connector is already attached to: the tree is the directory the
+   * session opened on, and there is nothing to fetch.
+   */
+  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
+}
+
+/**
+ * Whether this origin can be converted, and what it will cost.
+ *
+ * Answered BEFORE anything is provisioned or charged, from the census alone — which is why it
+ * carries the counts it was decided from rather than a bare verdict.
+ */
+export interface ConvertCheck {
+  projectId: string
+  verdict: ConvertibilityVerdict
+  reasons: ConvertibilityReason[]
+  stack?: ConversionStackRef
+  architecture?: ArchitectureCase
+  shape: OriginShape
+  monorepo: boolean
+  /** Workspace members and directories nothing declares. Named, because each one is a decision. */
+  unlinked: string[]
+  files: number
+  bytes: number
+  /** Bulk data files found — sampled and described, never carried. */
+  bulk: number
+  estimate?: ConversionEstimate
+}
+
+/** Everything a caller needs to draw the conversion's current state in one call. */
+export interface ConversionStatusView {
+  projectId: string
+  stage: ConversionStage
+  status: ConversionStatus
+  /** The last decision the user made. */
+  decision?: ConversionDecision
+  verdict?: ConvertibilityVerdict
+  stack?: ConversionStackRef
+  /** What the conversion is rebuilding the project ONTO. Always the Viable stack today. */
+  targetStack?: ConversionStackRef
+  architecture?: ArchitectureCase
+  /** One per stage that has been estimated, newest last. */
+  estimates: ConversionEstimate[]
+  storyEstimate?: StoryEstimateBand
+  originState: OriginState
+  /** How many questions the conversion answered for itself. Each one is readable in the docs. */
+  assumptions: number
+  runId?: string
+  /** Set exactly when `status` is `Waiting`: the question the run stopped on. */
+  pendingInquiry?: InquiryPayload
+  waitingFor?: ConnectWaitReason
+  lastError?: string
+  updatedAt: string
+}

package/src/connect/entrypoints/types.ts

@@ -0,0 +1,25 @@
+
+
+/**
+ * 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
+}

package/src/connect/entrypoints.ts

@@ -10,8 +10,19 @@ import {
   ConnectProjectIdSchema, ConnectSessionOpenSchema, ConnectSessionParamsSchema, ConnectPullQuerySchema,
   ConnectStoryParamsSchema, InquiryAnswerSchema,
 } from './schemas.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'
+import type { ConnectProjectBranding, ConnectProjectBrandingSave } from './branding/types.js'
+import type {
+  ConnectConvertCreateBody, ConnectConvertProceedBody, ConnectConvertStartBody, ConversionStatusView, ConvertCheck
+} from './conversion/types.js'
+import type { ConnectEntrypointOptions } from './entrypoints/types.js'
+import type { ConnectKitApplyBody, ConnectKitApplyResult, ConnectKitDescribe } from './kit/types.js'
+import type { ConnectInquiryAnswerBody, ConnectOpResult } from './ops/types.js'
+import type { ConnectPipelineParams, ConnectPipelineResumeBody, ConnectPipelineState } from './pipeline/types.js'
+import type {
+  ConnectAttachBody, ConnectConfirmBody, ConnectCreateBody, ConnectModifyBody, ConnectProjectStatus,
+  ConnectStoryStatus
+} from './project/types.js'
+import type { ConnectPullQuery, ConnectSessionOpen, ConnectSessionParams } from './session/types.js'
 
 /**
  * Declare the connector's HTTP surface — exactly the routes a connector calls: the session (long

package/src/connect/errors/types.ts

@@ -0,0 +1,22 @@
+
+
+/** 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
+}

package/src/connect/errors.ts

@@ -1,5 +1,5 @@
 import { ResilientError } from '@owlmeans/error'
-import type { ConnectConfirmation, ConnectConfirmationAction } from './types.js'
+import type { ConnectConfirmation, ConnectConfirmationAction } from './errors/types.js'
 
 export class ConnectError extends ResilientError {
   public static override typeName = `ViableConnect${ResilientError.typeName}`

package/src/connect/index.ts

@@ -1,8 +1,18 @@
 export * from './consts.js'
-export * from './utils.js'
+export * from './model-tier.js'
 export * from './schemas.js'
 export * from './errors.js'
 export * from './entrypoints.js'
 export * from './references.js'
-export type * from './types.js'
-export type * from './ops.js'
+export type * from './session/types.js'
+export type * from './ops/types.js'
+export type * from './project/types.js'
+export type * from './settings/types.js'
+export type * from './branding/types.js'
+export type * from './pipeline/types.js'
+export type * from './conversion/types.js'
+export type * from './kit/types.js'
+export type * from './entrypoints/types.js'
+export type * from './errors/types.js'
+export type * from './references/types.js'
+export type * from './model-tier/types.js'

package/src/connect/kit/types.ts

@@ -0,0 +1,56 @@
+
+
+/** One status of a planning kit's flow. `intrinsic` is the planning intrinsic it maps to. */
+export interface PlanningKitStatusView {
+  key: string
+  label: string
+  intrinsic: string
+}
+
+/** One status flow a planning kit declares. */
+export interface PlanningKitFlowView {
+  key: string
+  label: string
+  statuses: PlanningKitStatusView[]
+}
+
+/** One card type a planning kit declares; `flow` is the key of its main flow. */
+export interface PlanningKitTypeView {
+  key: string
+  label: string
+  flow: string
+}
+
+/**
+ * A planning kit as a connector sees it: a ready set of card types and status flows for one kind
+ * of work-management product, written into the target's common package on `apply`.
+ */
+export interface PlanningKitView {
+  id: string
+  /** The work kind the kit serves — a bare string, so a newer kind never fails an older reader. */
+  kind: string
+  title: string
+  purpose: string
+  /** The project-level container type the kit's cards live in. */
+  container: { key: string, label: string }
+  types: PlanningKitTypeView[]
+  flows: PlanningKitFlowView[]
+}
+
+/** What `project.kit.describe` answers. */
+export interface ConnectKitDescribe {
+  kits: PlanningKitView[]
+}
+
+/** Apply one kit; `types` keeps only these card-type keys of it (every type when omitted). */
+export interface ConnectKitApplyBody {
+  kit: string
+  types?: string[]
+}
+
+/** What `project.kit.apply` answers: the type keys written, those left out, and warnings. */
+export interface ConnectKitApplyResult {
+  applied: string[]
+  skipped: string[]
+  warnings: string[]
+}

package/src/connect/model-tier/types.ts

@@ -0,0 +1,16 @@
+import type { ModelTier } from '../consts.js'
+
+/** Which model tier a platform role runs on, and how a tier is placed on what a parent offers. */
+export interface ModelTierHelper {
+  /** The tier a platform role asks for; a role the table does not name is `Standard`. */
+  tierOfRole: (role: string) => ModelTier
+  /**
+   * 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.
+   */
+  clampTier: (wanted: ModelTier, offered: ModelTier[]) => ModelTier
+}

package/src/connect/model-tier.ts

@@ -0,0 +1,22 @@
+import { MODEL_TIER_ROLES, ModelTier } from './consts.js'
+import type { ModelTierHelper } from './model-tier/types.js'
+
+export const createModelTierHelper = (): ModelTierHelper => {
+  const tierOfRole = (role: string): ModelTier =>
+    MODEL_TIER_ROLES[role] ?? ModelTier.Standard
+
+  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
+  }
+
+  return { tierOfRole, clampTier }
+}
+
+export const modelTierHelper = createModelTierHelper()