@owlmeans/viable-common 0.0.42 → 0.0.44

package/src/planning/schemas.ts

@@ -1,13 +1,15 @@
 import type { JSONSchemaType } from 'ajv'
-import { CODE_MAX } from '@owlmeans/planning'
-import { ProjectArea } from '../areas/consts.js'
-import { TENANCY_QUOTE_MAX } from '../areas/tenancy.js'
+import { CODE_MAX, IntrinsicPolicy, IntrinsicStatus, SpecificationFormat, WorkcardKind, AnyTypeSchema, ProjectTypeSchema, RelationshipType, SpecificationSlot, StatusFlowSchema, WorkcardTypeSchema } from '@owlmeans/planning'
+import { ProjectArea, TENANCY_QUOTE_MAX } from '../areas/consts.js'
 import { CASE_QUOTE_MAX, WorkKind } from '../blueprint/consts.js'
 import { StoryKind } from '../ba/consts.js'
 import { ConnectLlm, ConnectTarget } from '../connect/consts.js'
 import { ProjectOriginSchema } from '../convert/schemas.js'
-import { StoryActor } from '../design/runtime.js'
+import { StoryActor, STORY_DESIGN_VERSION } from '../design/consts.js'
 import type { ViableProjectFields, ViableStoryFields } from './types.js'
+import { StoryDesignSchema } from '../design/schemas.js'
+import { ScaffoldPlanSchema } from '../scaffold/schemas.js'
+import { VIABLE_BUG_CODE, VIABLE_BUG_TYPE, VIABLE_DESIGN_REVISIONS_KEPT, VIABLE_IMPROVEMENT_CODE, VIABLE_IMPROVEMENT_TYPE, VIABLE_PROJECT_CODE, VIABLE_PROJECT_FLOW, VIABLE_PROJECT_TYPE, VIABLE_REQUIREMENT_CODE, VIABLE_REQUIREMENT_TYPE, VIABLE_SPEC_FLOW, VIABLE_SPEC_TYPE, VIABLE_STORY_CODE, VIABLE_STORY_FLOW, VIABLE_STORY_TYPE, ViableProjectStatus, ViableProjectTransition, ViableRelationship, ViableSpecCategory, ViableSpecStatus, ViableStoryStatus, ViableStoryTransition, ViableTone } from './consts.js'
 
 /**
  * The `fields` schema of a `viable:project` card.
@@ -109,3 +111,188 @@ export const ViableSpecFieldsSchema = {
   required: [],
   additionalProperties: false,
 } as unknown as JSONSchemaType<Record<string, never>>
+
+/**
+ * The story flow.
+ *
+ * `failed` maps to PLANNED: a failed story is work still to do, so "done" is the closed count and
+ * a retry is simply `start` again. `reset` from anywhere is the manual recovery — the one move a
+ * completed story still accepts.
+ */
+export const VIABLE_STORY_FLOW_SCHEMA: StatusFlowSchema = {
+  id: VIABLE_STORY_FLOW,
+  version: 1,
+  statuses: [
+    { key: ViableStoryStatus.Planned, intrinsic: IntrinsicStatus.Planned, initial: true, tone: ViableTone.Blue },
+    { key: ViableStoryStatus.InProgress, intrinsic: IntrinsicStatus.InProgress, tone: ViableTone.Yellow },
+    { key: ViableStoryStatus.Completed, intrinsic: IntrinsicStatus.Closed, tone: ViableTone.Green },
+    { key: ViableStoryStatus.Failed, intrinsic: IntrinsicStatus.Planned, tone: ViableTone.Red },
+  ],
+  transitions: [
+    {
+      name: ViableStoryTransition.Start,
+      from: [ViableStoryStatus.Planned, ViableStoryStatus.Failed],
+      to: ViableStoryStatus.InProgress,
+      explicit: true,
+    },
+    {
+      name: ViableStoryTransition.Complete,
+      from: [ViableStoryStatus.InProgress],
+      to: ViableStoryStatus.Completed,
+      explicit: true,
+    },
+    {
+      name: ViableStoryTransition.Fail,
+      from: [ViableStoryStatus.InProgress],
+      to: ViableStoryStatus.Failed,
+    },
+    { name: ViableStoryTransition.Reset, from: '*', to: ViableStoryStatus.Planned, explicit: true },
+  ],
+}
+
+/**
+ * The project flow.
+ *
+ * A create lands at `draft`; confirming the brief is `confirm`; the end of an initialization is
+ * `activate`. A reinitialization and a failed initialization are SLOT facts, not transitions, and
+ * destroying a project is a `delete` plus the platform's cascade — never `archive`.
+ */
+export const VIABLE_PROJECT_FLOW_SCHEMA: StatusFlowSchema = {
+  id: VIABLE_PROJECT_FLOW,
+  version: 1,
+  statuses: [
+    { key: ViableProjectStatus.Draft, intrinsic: IntrinsicStatus.Planned, initial: true, tone: ViableTone.Blue },
+    { key: ViableProjectStatus.Confirmed, intrinsic: IntrinsicStatus.InProgress, tone: ViableTone.Yellow },
+    { key: ViableProjectStatus.Active, intrinsic: IntrinsicStatus.InProgress, tone: ViableTone.Green },
+    { key: ViableProjectStatus.Archived, intrinsic: IntrinsicStatus.Closed, tone: ViableTone.Neutral },
+  ],
+  transitions: [
+    {
+      name: ViableProjectTransition.Confirm,
+      from: [ViableProjectStatus.Draft],
+      to: ViableProjectStatus.Confirmed,
+      explicit: true,
+    },
+    {
+      name: ViableProjectTransition.Activate,
+      from: [ViableProjectStatus.Confirmed],
+      to: ViableProjectStatus.Active,
+    },
+    { name: ViableProjectTransition.Archive, from: '*', to: ViableProjectStatus.Archived, explicit: true },
+    {
+      name: ViableProjectTransition.Reopen,
+      from: [ViableProjectStatus.Archived],
+      to: ViableProjectStatus.Active,
+      explicit: true,
+    },
+  ],
+}
+
+/** A document is written or revised; it has no lifecycle to move through. */
+export const VIABLE_SPEC_FLOW_SCHEMA: StatusFlowSchema = {
+  id: VIABLE_SPEC_FLOW,
+  version: 1,
+  statuses: [
+    { key: ViableSpecStatus.Current, intrinsic: IntrinsicStatus.Closed, initial: true, tone: ViableTone.Neutral },
+  ],
+  transitions: [],
+}
+
+export const slot = (
+  category: ViableSpecCategory, format: SpecificationFormat, extra: Partial<SpecificationSlot> = {},
+): SpecificationSlot => ({ category, format, type: VIABLE_SPEC_TYPE, ...extra })
+
+/** The brief a person confirms, and the plan the scaffold draws from it. */
+export const VIABLE_PROJECT_SLOTS: SpecificationSlot[] = [
+  slot(ViableSpecCategory.Specification, SpecificationFormat.Markdown, { required: true }),
+  slot(ViableSpecCategory.Vision, SpecificationFormat.Markdown),
+  slot(ViableSpecCategory.DesignSystem, SpecificationFormat.Markdown),
+  slot(ViableSpecCategory.Scaffold, SpecificationFormat.Json, {
+    revisioned: true, keepRevisions: VIABLE_DESIGN_REVISIONS_KEPT, schema: ScaffoldPlanSchema,
+  }),
+]
+
+/** A story's design — the payload the implementation stage consumes. */
+export const VIABLE_STORY_SLOTS: SpecificationSlot[] = [
+  slot(ViableSpecCategory.Design, SpecificationFormat.Json, {
+    revisioned: true,
+    keepRevisions: VIABLE_DESIGN_REVISIONS_KEPT,
+    schema: StoryDesignSchema,
+    version: STORY_DESIGN_VERSION,
+  }),
+]
+
+export const storyLink = (name: ViableRelationship): RelationshipType =>
+  ({ name, from: [VIABLE_STORY_TYPE], to: [VIABLE_STORY_TYPE], single: true })
+
+export const VIABLE_STORY_RELATIONSHIPS: RelationshipType[] = [
+  storyLink(ViableRelationship.Follows),
+  storyLink(ViableRelationship.SharesWidget),
+  storyLink(ViableRelationship.SharesScreen),
+]
+
+export const VIABLE_PROJECT_TYPE_SCHEMA: ProjectTypeSchema = {
+  type: VIABLE_PROJECT_TYPE,
+  kind: WorkcardKind.Project,
+  version: 1,
+  fields: ViableProjectFieldsSchema,
+  flows: [VIABLE_PROJECT_FLOW],
+  intrinsic: IntrinsicPolicy.Primary,
+  specifications: VIABLE_PROJECT_SLOTS,
+  code: VIABLE_PROJECT_CODE,
+  cardTypes: [VIABLE_STORY_TYPE],
+}
+
+export const VIABLE_STORY_TYPE_SCHEMA: WorkcardTypeSchema = {
+  type: VIABLE_STORY_TYPE,
+  kind: WorkcardKind.Card,
+  version: 1,
+  fields: ViableStoryFieldsSchema,
+  flows: [VIABLE_STORY_FLOW],
+  intrinsic: IntrinsicPolicy.Primary,
+  specifications: VIABLE_STORY_SLOTS,
+  relationships: VIABLE_STORY_RELATIONSHIPS,
+  code: VIABLE_STORY_CODE,
+}
+
+export const VIABLE_SPEC_TYPE_SCHEMA: WorkcardTypeSchema = {
+  type: VIABLE_SPEC_TYPE,
+  kind: WorkcardKind.Specification,
+  version: 1,
+  fields: ViableSpecFieldsSchema,
+  flows: [VIABLE_SPEC_FLOW],
+  specifications: [],
+}
+
+export const reserved = (type: string, code: WorkcardTypeSchema['code']): WorkcardTypeSchema => ({
+  type,
+  kind: WorkcardKind.Card,
+  version: 1,
+  fields: ViableOpenFieldsSchema,
+  flows: [VIABLE_STORY_FLOW],
+  intrinsic: IntrinsicPolicy.Primary,
+  specifications: [],
+  code,
+})
+
+/** Registered so their prefixes and flow are decided once; not creatable under a project yet. */
+export const VIABLE_RESERVED_TYPE_SCHEMAS: WorkcardTypeSchema[] = [
+  reserved(VIABLE_BUG_TYPE, VIABLE_BUG_CODE),
+  reserved(VIABLE_IMPROVEMENT_TYPE, VIABLE_IMPROVEMENT_CODE),
+  reserved(VIABLE_REQUIREMENT_TYPE, VIABLE_REQUIREMENT_CODE),
+]
+
+/** Every Viable type — what a planning plugin registers. */
+export const VIABLE_TYPE_SCHEMAS: AnyTypeSchema[] = [
+  VIABLE_PROJECT_TYPE_SCHEMA,
+  VIABLE_STORY_TYPE_SCHEMA,
+  VIABLE_SPEC_TYPE_SCHEMA,
+  ...VIABLE_RESERVED_TYPE_SCHEMAS,
+]
+
+/** Every Viable flow — registered beside the types. */
+export const VIABLE_FLOW_SCHEMAS: StatusFlowSchema[] = [
+  VIABLE_PROJECT_FLOW_SCHEMA,
+  VIABLE_STORY_FLOW_SCHEMA,
+  VIABLE_SPEC_FLOW_SCHEMA,
+]

package/src/planning/types.ts

@@ -1,11 +1,11 @@
 import type { Card, Project, Specification } from '@owlmeans/planning'
 import type { ProjectArea } from '../areas/consts.js'
 import type { WorkKind } from '../blueprint/consts.js'
-import type { ViableTenancyDecision } from '../areas/tenancy.js'
+import type { ViableTenancyDecision } from '../areas/types.js'
 import type { StoryKind } from '../ba/consts.js'
 import type { ConnectLlm, ConnectTarget } from '../connect/consts.js'
 import type { ProjectOrigin } from '../convert/types.js'
-import type { StoryActor } from '../design/runtime.js'
+import type { StoryActor } from '../design/consts.js'
 import type { StoryWriteInput } from '../metadata/types.js'
 
 /**

package/src/preview/consts.ts

@@ -6,4 +6,6 @@ export enum PreviewEventType {
   CaughtError = 'OWLMEANS_PREVIEW_CONSOLE_ERROR',
   PromiseRejection = 'OWLMEANS_PREVIEW_PROMISE_REJECTION',
   FetchError = 'OWLMEANS_PREVIEW_FETCH_ERROR',
+  /** An analytics event a target's web logged through `@owlmeans/log` (browser → manager frame). */
+  Analytics = 'OWLMEANS_PREVIEW_ANALYTICS',
 }

package/src/preview/types.ts

@@ -46,6 +46,19 @@ export interface OwlMeansFetchErrorPayload {
   incidentId?: string
 }
 
+/**
+ * Payload of an analytics event of a target's web — `AnalyticsEvent` of `@owlmeans/log`, as the
+ * target's `viablePreviewPlugin` posts it. Untrusted: it comes from generated code.
+ */
+export interface OwlMeansAnalyticsPayload {
+  event: string
+  scope: string
+  time: number
+  level: 'debug' | 'info' | 'warn' | 'error'
+  message: string
+  data?: unknown
+}
+
 /**
  * Specific message types for each event kind
  */
@@ -65,6 +78,10 @@ export interface OwlMeansCaughtErrorMessage extends OwlMeansPreviewMessage<OwlMe
   type: PreviewEventType.CaughtError
 }
 
+export interface OwlMeansAnalyticsMessage extends OwlMeansPreviewMessage<OwlMeansAnalyticsPayload> {
+  type: PreviewEventType.Analytics
+}
+
 /**
  * Union type for all possible OwlMeans preview messages
  */
@@ -73,9 +90,11 @@ export type OwlMeansPreviewMessages =
   | OwlMeansPromiseRejectionMessage 
   | OwlMeansFetchErrorMessage
   | OwlMeansCaughtErrorMessage
+  | OwlMeansAnalyticsMessage
 
 export type OwlMenasPreviewPayloads = 
   | OwlMeansErrorPayload
   | OwlMeansPromiseRejectionPayload
   | OwlMeansFetchErrorPayload
   | OwlMeansCaughtErrorPayload
+  | OwlMeansAnalyticsPayload

package/src/scaffold/helpers.ts

@@ -1,4 +1,4 @@
-import type { ScaffoldPlan, ScaffoldStoryPlan } from './types.js'
+import type { ScaffoldPlan, ScaffoldStoryPlan, ShareKind } from './types.js'
 
 /**
  * ONE reading of who owns a drawn artifact, so no consumer has to interpret the plan itself.
@@ -12,9 +12,6 @@ import type { ScaffoldPlan, ScaffoldStoryPlan } from './types.js'
  * so the stampers and the scaffold loop can read a plan that is already sane.
  */
 
-/** Which field the arrow is being followed along. */
-export type ShareKind = 'widget' | 'screen'
-
 const pointerOf = (story: ScaffoldStoryPlan, kind: ShareKind): string | undefined =>
   kind === 'widget' ? story.sharesWidgetWith : story.sharesScreenWith
 

package/src/scaffold/types.ts

@@ -266,3 +266,6 @@ export interface ScaffoldPlan {
    */
   motifs: string
 }
+
+/** Which field the arrow is being followed along. */
+export type ShareKind = 'widget' | 'screen'

package/src/slot/consts.ts

@@ -19,6 +19,8 @@
  * commands are executed by the connector on that machine, and nothing about it is provisioned,
  * routed, reconciled or published.
  */
+import { TargetLayout } from '../integrity/index.js'
+
 export enum WorkloadKind {
   Ephemeral = 'ephemeral',
   Production = 'production',
@@ -368,46 +370,15 @@ export const FILE_COMMAND_TIMEOUTS: Partial<Record<SlotFileCommand, number>> = {
   [SlotFileCommand.ReadHead]: 70_000,
 }
 
-/** The per-command caller bound for one command, or nothing where its type's default is right. */
-const perCommandTimeout = (type: SlotCommandType, command: string): number | undefined => {
-  switch (type) {
-    case SlotCommandType.Shell: return SHELL_COMMAND_TIMEOUTS[command]
-    case SlotCommandType.Git: return GIT_COMMAND_TIMEOUTS[command as SlotGitCommand]
-    case SlotCommandType.Database: return COMMAND_TIMEOUTS[SlotCommandType.Database]
-    default: return FILE_COMMAND_TIMEOUTS[command as SlotFileCommand]
-  }
-}
-
-/**
- * Resolve the caller-side bound for one command.
- *
- * One function rather than three lookups at each call site: an asker that forgets the per-command
- * table inherits twenty minutes for a fifteen-second command, which is the failure this table was
- * added to stop.
- */
-export const commandTimeout = (
-  type: SlotCommandType, command: string, override?: number
-): number => override
-  ?? perCommandTimeout(type, command)
-  ?? COMMAND_TIMEOUTS[type]
-  ?? DEFAULT_COMMAND_TIMEOUT
-
 /**
- * Resolve the executor-side deadline for one command.
+ * The one marker per layout, chosen because it exists in that layout and in no other.
  *
- * Per-command first, per-type second. It was per-type only, which is how a clone inherited the
- * bound of a `git status` — the same shape as the shell table above, and added for the same
- * reason.
+ * `sources/api` cannot appear in a v1 tree and `packages/backend` cannot appear in a v2 one, so a
+ * single `stat` settles it. Deliberately not `sources/` alone: v1 packages each have their own
+ * `src`, and a directory name that differs by one letter is not something to hang a runtime path
+ * resolution on. Ordered — the first marker found wins.
  */
-export const commandDeadline = (type: SlotCommandType, command: string): number => {
-  switch (type) {
-    case SlotCommandType.Shell:
-      return COMMAND_DEADLINES[command] ?? DEFAULT_COMMAND_DEADLINE
-    case SlotCommandType.Git:
-      return GIT_COMMAND_DEADLINES[command as SlotGitCommand] ?? DEFAULT_GIT_COMMAND_DEADLINE
-    case SlotCommandType.Database:
-      return 30_000
-    default:
-      return FILE_COMMAND_DEADLINES[command as SlotFileCommand] ?? DEFAULT_FILE_COMMAND_DEADLINE
-  }
-}
+export const LAYOUT_MARKERS: Array<[TargetLayout, string]> = [
+  [TargetLayout.V2, 'sources/api'],
+  [TargetLayout.V1, 'packages/backend'],
+]

package/src/slot/helpers.ts

@@ -1,10 +1,5 @@
 import { WorkloadKind } from './consts.js'
-
-/** The minimum a caller must know about a slot to address it. */
-export interface AddressableSlot {
-  kind?: WorkloadKind
-  host?: string
-}
+import type { AddressableSlot } from './types.js'
 
 /**
  * The origin a slot's application answers at.

package/src/slot/index.ts

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

package/src/slot/layout.ts

@@ -1,55 +1,7 @@
 import { TargetLayout } from '../integrity/index.js'
 import { packageForRole, resolveTopology, topologyOf } from '../topology/index.js'
 import { SubProject } from './consts.js'
-
-/**
- * Where each role lives, for one layout. Directory names are target-root-relative.
- *
- * The pure half of layout resolution. Whoever holds the tree — the publisher over a pod volume,
- * the connector over a directory on a developer's machine — adds the two filesystem probes that
- * pick the layout and turn these names into absolute paths. The TABLES are shared so the two
- * cannot disagree about what a role means.
- */
-export interface TargetPaths {
-  layout: TargetLayout
-  /** The directory holding the workspace packages — `packages` or `sources`. */
-  dir: string
-  /** The package whose `dist/index.js` runs as the target's HTTP server. */
-  api: string
-  /** The package whose `dist/` is served to a browser. */
-  web: string
-  /** The shared library the other two compile against. */
-  common: string
-  /**
-   * The package whose `dist/index.js` runs as the target's queue worker, when the target has one.
-   *
-   * Absent for v1, which had no such package and never will — a target's tree is the one it was
-   * initialized with. Present for v2 as a NAME, not as a promise: every caller checks the disk
-   * before acting on it.
-   */
-  worker?: string
-  /**
-   * Every package a full build runs, in dependency order.
-   *
-   * Longer than the three roles for v2, whose `backend` is a library that both `api` and `worker`
-   * import. A caller skips whatever is not on disk — a target need not have a worker.
-   */
-  build: string[]
-  /**
-   * The packages built with `tsc -b` and consumed through their `build/` output, in dependency
-   * order — never bundled, so their output has to be on disk at RUN time, not only at build time.
-   *
-   * The bundled packages keep every dependency external, so `bun dist/index.js` resolves
-   * `project-backend` from `node_modules` at startup, follows its `main` to `build/index.js` — and
-   * if nothing built it, Bun answers `Cannot find package 'project-backend'` and the target exits 1
-   * with a message that names a dependency rather than a missing build.
-   *
-   * v1 got away without this list: it had ONE library and the template shipped its `build/`
-   * prebuilt. v2 deleted those artifacts and added a second library, so every path that builds a
-   * target has to build these first or it can never start.
-   */
-  libraries: string[]
-}
+import type { TargetPaths } from './types.js'
 
 /**
  * Where every role lives, per layout — DERIVED from that layout's topology.
@@ -114,19 +66,6 @@ export const ROLE_DIRS: Record<TargetLayout, Record<SubProject, string>> = {
   [TargetLayout.V2]: roleDirsOfTopology(TargetLayout.V2),
 }
 
-/**
- * The one marker per layout, chosen because it exists in that layout and in no other.
- *
- * `sources/api` cannot appear in a v1 tree and `packages/backend` cannot appear in a v2 one, so a
- * single `stat` settles it. Deliberately not `sources/` alone: v1 packages each have their own
- * `src`, and a directory name that differs by one letter is not something to hang a runtime path
- * resolution on. Ordered — the first marker found wins.
- */
-export const LAYOUT_MARKERS: Array<[TargetLayout, string]> = [
-  [TargetLayout.V2, 'sources/api'],
-  [TargetLayout.V1, 'packages/backend'],
-]
-
 /**
  * Resolve a wire-level role to the directory it names in a given layout.
  *

package/src/slot/types.ts

@@ -1,4 +1,5 @@
-import type { SlotCommandType, SlotDatabaseCommand, SlotFileCommand, SlotGitCommand, SlotShellCommand, SubProject } from './consts.js'
+import { type SlotCommandType, type SlotDatabaseCommand, type SlotFileCommand, type SlotGitCommand, type SlotShellCommand, type SubProject, WorkloadKind } from './consts.js'
+import { TargetLayout } from '../integrity/index.js'
 
 export type SlotCommand = SlotFileCommand | SlotShellCommand | SlotGitCommand | SlotDatabaseCommand
 
@@ -191,3 +192,58 @@ export interface SlotShellArgs {
   args?: string
   skipBuild?: boolean
 }
+
+/** The minimum a caller must know about a slot to address it. */
+export interface AddressableSlot {
+  kind?: WorkloadKind
+  host?: string
+}
+
+/**
+ * Where each role lives, for one layout. Directory names are target-root-relative.
+ *
+ * The pure half of layout resolution. Whoever holds the tree — the publisher over a pod volume,
+ * the connector over a directory on a developer's machine — adds the two filesystem probes that
+ * pick the layout and turn these names into absolute paths. The TABLES are shared so the two
+ * cannot disagree about what a role means.
+ */
+export interface TargetPaths {
+  layout: TargetLayout
+  /** The directory holding the workspace packages — `packages` or `sources`. */
+  dir: string
+  /** The package whose `dist/index.js` runs as the target's HTTP server. */
+  api: string
+  /** The package whose `dist/` is served to a browser. */
+  web: string
+  /** The shared library the other two compile against. */
+  common: string
+  /**
+   * The package whose `dist/index.js` runs as the target's queue worker, when the target has one.
+   *
+   * Absent for v1, which had no such package and never will — a target's tree is the one it was
+   * initialized with. Present for v2 as a NAME, not as a promise: every caller checks the disk
+   * before acting on it.
+   */
+  worker?: string
+  /**
+   * Every package a full build runs, in dependency order.
+   *
+   * Longer than the three roles for v2, whose `backend` is a library that both `api` and `worker`
+   * import. A caller skips whatever is not on disk — a target need not have a worker.
+   */
+  build: string[]
+  /**
+   * The packages built with `tsc -b` and consumed through their `build/` output, in dependency
+   * order — never bundled, so their output has to be on disk at RUN time, not only at build time.
+   *
+   * The bundled packages keep every dependency external, so `bun dist/index.js` resolves
+   * `project-backend` from `node_modules` at startup, follows its `main` to `build/index.js` — and
+   * if nothing built it, Bun answers `Cannot find package 'project-backend'` and the target exits 1
+   * with a message that names a dependency rather than a missing build.
+   *
+   * v1 got away without this list: it had ONE library and the template shipped its `build/`
+   * prebuilt. v2 deleted those artifacts and added a second library, so every path that builds a
+   * target has to build these first or it can never start.
+   */
+  libraries: string[]
+}

package/src/slot/utils.ts

@@ -0,0 +1,45 @@
+import { COMMAND_DEADLINES, COMMAND_TIMEOUTS, DEFAULT_COMMAND_DEADLINE, DEFAULT_COMMAND_TIMEOUT, DEFAULT_FILE_COMMAND_DEADLINE, DEFAULT_GIT_COMMAND_DEADLINE, FILE_COMMAND_DEADLINES, FILE_COMMAND_TIMEOUTS, GIT_COMMAND_DEADLINES, GIT_COMMAND_TIMEOUTS, SHELL_COMMAND_TIMEOUTS, SlotCommandType, SlotFileCommand, SlotGitCommand } from './consts.js'
+
+/** The per-command caller bound for one command, or nothing where its type's default is right. */
+const perCommandTimeout = (type: SlotCommandType, command: string): number | undefined => {
+  switch (type) {
+    case SlotCommandType.Shell: return SHELL_COMMAND_TIMEOUTS[command]
+    case SlotCommandType.Git: return GIT_COMMAND_TIMEOUTS[command as SlotGitCommand]
+    case SlotCommandType.Database: return COMMAND_TIMEOUTS[SlotCommandType.Database]
+    default: return FILE_COMMAND_TIMEOUTS[command as SlotFileCommand]
+  }
+}
+
+/**
+ * Resolve the caller-side bound for one command.
+ *
+ * One function rather than three lookups at each call site: an asker that forgets the per-command
+ * table inherits twenty minutes for a fifteen-second command, which is the failure this table was
+ * added to stop.
+ */
+export const commandTimeout = (
+  type: SlotCommandType, command: string, override?: number
+): number => override
+  ?? perCommandTimeout(type, command)
+  ?? COMMAND_TIMEOUTS[type]
+  ?? DEFAULT_COMMAND_TIMEOUT
+
+/**
+ * Resolve the executor-side deadline for one command.
+ *
+ * Per-command first, per-type second. It was per-type only, which is how a clone inherited the
+ * bound of a `git status` — the same shape as the shell table above, and added for the same
+ * reason.
+ */
+export const commandDeadline = (type: SlotCommandType, command: string): number => {
+  switch (type) {
+    case SlotCommandType.Shell:
+      return COMMAND_DEADLINES[command] ?? DEFAULT_COMMAND_DEADLINE
+    case SlotCommandType.Git:
+      return GIT_COMMAND_DEADLINES[command as SlotGitCommand] ?? DEFAULT_GIT_COMMAND_DEADLINE
+    case SlotCommandType.Database:
+      return 30_000
+    default:
+      return FILE_COMMAND_DEADLINES[command as SlotFileCommand] ?? DEFAULT_FILE_COMMAND_DEADLINE
+  }
+}

package/src/topology/card.ts

@@ -1,16 +1,9 @@
 import { SubProject } from '../slot/consts.js'
 import { TOPOLOGY_VERSION } from './consts.js'
 import { orderPackages } from './helpers.js'
-import type { TargetPackageDescriptor, TargetPackageKind, TopologyDescriptor } from './types.js'
+import type { TargetPackageDescriptor, TargetPackageKind, TopologyDescriptor, TopologyMeta } from './types.js'
+import { KINDS, ROLES } from './consts.local.js'
 
-/** What `.agents/memory/topology.md` carries in its frontmatter. */
-export interface TopologyMeta extends TopologyDescriptor {
-  version: number
-  updatedAt: string
-}
-
-const ROLES = new Set<string>(Object.values(SubProject))
-const KINDS = new Set<TargetPackageKind>(['library', 'bundle'])
 
 const asStrings = (value: unknown): string[] =>
   Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : []

package/src/topology/consts.local.ts

@@ -0,0 +1,6 @@
+import { SubProject } from '../slot/consts.js'
+import type { TargetPackageKind } from './types.js'
+
+export const ROLES = new Set<string>(Object.values(SubProject))
+
+export const KINDS = new Set<TargetPackageKind>(['library', 'bundle'])

package/src/topology/types.ts

@@ -84,3 +84,9 @@ export interface ResolvedTopology extends TopologyDescriptor {
   /** Role → the packages holding it, in topology order. */
   byRole: Partial<Record<SubProject, TargetPackageDescriptor[]>>
 }
+
+/** What `.agents/memory/topology.md` carries in its frontmatter. */
+export interface TopologyMeta extends TopologyDescriptor {
+  version: number
+  updatedAt: string
+}

package/tests/branding.spec.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'bun:test'
 
-import { BRANDING_ENV_KEYS, brandingEnv } from '../src/branding.js'
-import { metadataConfigs, metadataLists } from '../src/consts.js'
+import { brandingEnv } from '../src/branding.js'
+import { BRANDING_ENV_KEYS, metadataConfigs, metadataLists } from '../src/consts.js'
 
 /**
  * `BRANDING_CREDIT` is the one key whose ABSENCE means something different from an explicit

package/tests/connect-convert.spec.ts

@@ -8,7 +8,7 @@ import { connectProtocols } from '../src/connect/entrypoints.js'
 import { connectRef } from '../src/connect/references.js'
 import {
   ConnectCapabilitiesSchema, ConnectConvertCreateBodySchema, ConnectConvertProceedBodySchema,
-  ConnectInquiryParamsSchema, ConnectPipelineResumeBodySchema, InquiryAnswerSchema
+  ConnectConvertStartBodySchema, ConnectInquiryParamsSchema, ConnectPipelineResumeBodySchema, InquiryAnswerSchema
 } from '../src/connect/schemas.js'
 import { ConnectExecutor } from '../src/connect/consts.js'
 import { InquiryKind } from '@owlmeans/llm-common'
@@ -39,6 +39,7 @@ describe('viable-common - the conversion additions to the connector contract', (
       ['InquiryAnswerSchema', InquiryAnswerSchema],
       ['ConnectInquiryParamsSchema', ConnectInquiryParamsSchema],
       ['ConnectConvertCreateBodySchema', ConnectConvertCreateBodySchema],
+      ['ConnectConvertStartBodySchema', ConnectConvertStartBodySchema],
       ['ConnectConvertProceedBodySchema', ConnectConvertProceedBodySchema],
       ['ConnectPipelineResumeBodySchema', ConnectPipelineResumeBodySchema],
       ['ConnectCapabilitiesSchema', ConnectCapabilitiesSchema],
@@ -81,6 +82,25 @@ describe('viable-common - the conversion additions to the connector contract', (
     expect(proceed({ decision: 'teleport' })).toBe(false)
   })
 
+  test('start and proceed carry the person\'s confirmation, and nothing else new', () => {
+    const ajv = compiler()
+    const start = ajv.compile(ConnectConvertStartBodySchema as never)
+    const proceed = ajv.compile(ConnectConvertProceedBodySchema as never)
+
+    expect(start({})).toBe(true)
+    expect(start({ confirm: true })).toBe(true)
+    // An unset optional serialised as `null` is "not confirmed", never a refused body.
+    expect(start({ confirm: null })).toBe(true)
+    expect(start({ confirm: 'yes' })).toBe(false)
+    expect(start({ restart: true })).toBe(false)
+    expect(proceed({ decision: ConversionDecision.Implement, confirm: true })).toBe(true)
+    expect(proceed({ decision: ConversionDecision.Implement, confirm: 1 })).toBe(false)
+  })
+
+  test('the start declares its body, so a confirmation reaches the handler', () => {
+    expect(entrypointOf(connect.convert.start).contract?.requestSchemas.body).toEqual(ConnectConvertStartBodySchema as never)
+  })
+
   test('capabilities accept an executor kind this platform has never heard of', () => {
     // The SDK and the platform ship separately: a connector built against a newer package must not
     // be refused a session because it advertises one more capability than this platform knows.