@owlmeans/viable-common 0.0.11 → 0.0.13

package/src/index.ts

@@ -16,6 +16,7 @@ export * from './topology/index.js'
 export * from './blueprint/index.js'
 export * from './slot/index.js'
 export * from './connect/index.js'
+export * from './convert/index.js'
 export * from './scaffold/index.js'
 export * from './design/index.js'
 export * from './branding.js'

package/src/skills/catalogue.ts

@@ -108,7 +108,8 @@ them, and each has a sentinel comment marking where a new line goes:
 
 - \`sources/common/src/consts.ts\` — the \`app\` alias tree.
 - \`sources/common/src/entrypoints.ts\` — the shared immutable protocol tree (\`appEntrypoints\`).
-- \`sources/api/src/entrypoints.ts\` — server bindings (\`bind\` + \`handlers<Context>()\`).
+- \`sources/api/src/entrypoints.ts\` — server bindings: \`bind\` + one \`handlers<Context>()\` wrap
+  per handler.
 - \`sources/web/src/entrypoints.ts\` — client bindings (\`bindAll\` + \`bindScreen\`).
 - \`sources/worker/src/entrypoints.ts\` — job bindings (\`bind\`).
 - \`sources/web/src/nav.ts\` — the navigation registry: one line per screen, which
@@ -702,7 +703,7 @@ It declares the alias and the hooks that READ it, and nothing else:
     import { useStoreList, useStoreModel } from '@owlmeans/client'
     import { useContext } from '@owlmeans/web-client'
     import type { Criteria } from '@owlmeans/resource'
-    import type { Task } from 'project-common/models/task/task.type.js'
+    import type { Task } from 'project-common/models/task/task'
 
     export const TASK_STATE = 'task-state'
 
@@ -982,7 +983,7 @@ Write this instead, and let the route handler import the function directly:
     export const getSummary = async (ctx: BasicContext<BasicConfig>, guestId: string) => { ... }
 
     // RIGHT — sources/api/src/app/dashboard/activity.ts
-    import { getSummary } from 'project-backend/models/dashboard/activity.js'
+    import { getSummary } from 'project-backend/models/dashboard/activity'
     const summary = await getSummary(ctx, guestId)
 
 Do not create a service just to hold functions.
@@ -1101,37 +1102,43 @@ There is NO express here. \`express\`, \`cors\` and \`@types/express\` are not i
 no \`app.get(...)\`, no \`req\`/\`res\` of a web server, no \`next\`, and no middleware. Anything
 written for express fails to resolve.
 
-A handler is a plain async function that RETURNS its result, created from the protocol with a
-typed helper from \`@owlmeans/server-api\`. Pick by what the handler reads:
+A handler is a PLAIN exported async function that RETURNS its result — named exports only, one
+file per entity: \`sources/api/src/app/<entity>/<action>.ts\`. It NEVER imports \`handlers\` and
+NEVER calls \`handlers<Context>()\`; that belongs only in the file that BINDS it:
+
+    // sources/api/src/app/task/create.ts — the handler module
+    export const handleTaskCreate = async (payload: TaskCreatePayload, ctx: Context) => {
+      const tasks = getTaskResource(ctx)
+      return await tasks.create(payload)
+    }
+
+sources/api/src/entrypoints.ts wraps that export EXACTLY ONCE, choosing the helper by what the
+protocol carries — the request BODY → \`api.body\`, route PARAMS (the ':' segments of the declared
+path) → \`api.params\`, anything else (query, headers, nothing at all) → \`api.request\`:
 
     import { handlers } from '@owlmeans/server-api'
     import { bind } from '@owlmeans/server-entrypoint'
     import { protocols } from 'project-common/entrypoints'
+    import { handleTaskCreate } from '@/app/task/create.js'
     const api = handlers<Context>()
 
-    // the request BODY — the payload type comes from the protocol contract
-    const createTask = api.body(protocols.api.task.create, async (payload, ctx) => {
-      const tasks = getTaskResource(ctx)
-      return await tasks.create(payload)
-    })
+    export const entrypoints = [
+      bind(protocols.api.task.create, api.body(protocols.api.task.create, handleTaskCreate)),
+    ]
 
-    // the route PARAMS — names match the ':' segments of the declared path
-    const getTask = api.params(protocols.api.task.get, async ({ taskId }, ctx) => {
-      return await tasks(ctx).load(taskId)
-    })
+WRONG — the handler module ALSO calls \`handlers()\` and wraps itself, so the export bound above is
+wrapped a SECOND time. \`tsc\` catches it: \`TS2345 "Argument of type 'BoundEntrypointHandler<…>' is
+not assignable"\`. Left unfixed, the build stays clean anyway if nothing runs \`tsc\` on this
+package, and every request to the route then fails with \`TypeError: handler is not a function\`
+(\`execute is not a function\` for \`.request\`) — an endpoint that "completed" and answers nothing:
 
-    // anything else (query, headers, nothing at all) — the whole request
-    const listTasks = api.request(protocols.api.task.list, async (req, ctx) => {
-      const query = req.query as { search?: string }
-      return await tasks(ctx).list(query.search != null ? { search: query.search } : {})
+    // WRONG — sources/api/src/app/task/create.ts
+    const api = handlers<Context>()
+    export const handleTaskCreate = api.body(protocols.api.task.create, async (payload, ctx) => {
+      const tasks = getTaskResource(ctx)
+      return await tasks.create(payload)
     })
 
-    export const entrypoints = [
-      bind(protocols.api.task.create, createTask),
-      bind(protocols.api.task.get, getTask),
-      bind(protocols.api.task.list, listTasks),
-    ]
-
 - The SECOND argument is the OwlMeans context. Reach every resource through it — never
   import a database connection and never write raw SQL in a handler.
 - RETURN the value. \`res.json(...)\`, \`res.status(...)\`, \`res.send(...)\` do not exist; a
@@ -1141,9 +1148,9 @@ typed helper from \`@owlmeans/server-api\`. Pick by what the handler reads:
   200 carrying an error object instead.
 - Never read a token, never check a role, never look at an \`Authorization\` header. Access is
   declared on the protocol (\`guards\` / \`gate\` options) and enforced before the handler runs.
-- A handler is inert until a \`bind(protocols.api.<name>, handler)\` line in
-  \`sources/api/src/entrypoints.ts\` binds it to its protocol. Without that line the endpoint
-  answers 404 and nothing reports an error.
+- A handler is inert until the \`bind(protocols.api.<name>, api.body/params/request(protocols.api.<name>, handler))\`
+  line in \`sources/api/src/entrypoints.ts\` binds it to its protocol. Without that line the
+  endpoint answers 404 and nothing reports an error.
 - Handlers are ENTITY-SCOPED: \`sources/api/src/app/<entity>/<action>.ts\`, named exports only.
   The directory is what keeps two entities' \`list\` apart — the file name carries no marker.
 `),
@@ -1169,6 +1176,21 @@ says before rewriting anything.
   its \`.js\` suffix — \`'../../resources/task/task.js'\`. Adding, removing or changing the
   extension on the alias fixes nothing and the same error comes back under the other spelling;
   two attempts that differ only in the suffix mean you are in this case.
+- **"Cannot find module 'project-common/…' or 'project-backend/…'" is almost always the
+  extension, not the path.** These two are PACKAGES, resolved through their published
+  \`exports\` map, and a deep import into either carries NO suffix — no \`.js\`, no \`.ts\`, no
+  \`.type\`. \`project-backend/models/enquiry/enquiry.js\` resolves to a file
+  (\`build/models/enquiry/enquiry.js.js\`) that can never exist; drop the extension entirely.
+  This is unrelated to the \`sources/backend/\` bullet above it: that one is the SAME package
+  importing itself and keeps \`.js\`; this one is a DIFFERENT package importing it by name.
+- **\`TS2345\` naming \`BoundEntrypointHandler\` at a \`bind(...)\` line in
+  \`sources/api/src/entrypoints.ts\` or \`sources/worker/src/entrypoints.ts\` is a handler wrapped
+  TWICE** — the handler module already exported a bound handler, and this line wraps it again
+  with \`.body\`/\`.params\`/\`.request\`. Bind the already-bound export DIRECTLY
+  (\`bind(protocol, handler)\`, no wrapper) — never cast around the type error, and never touch the
+  handler module. Left as a type error, this is also the runtime fingerprint of the same defect:
+  a story reported \`completed\` whose every request to that route fails with
+  \`TypeError: handler is not a function\` (\`execute is not a function\` for \`.request\`).
 - "Cannot find module" for \`postgres\`, \`@/lib/db.js\` or \`@/db/schema/...\` inside a
   \`resources/**\` file means the file was written against the REMOVED Drizzle-DDL layout.
   Rewrite it as an OwlMeans resource: an AJV schema on \`resource.schema\`, built with
@@ -1203,8 +1225,8 @@ says before rewriting anything.
   \`@reduxjs/toolkit\`, \`react-redux\`, \`@/state/store\` or \`@/lib/fetch\` means the file was
   written against the REMOVED stack. None of those packages are installed and none will be.
   Rewrite the file against entrypoints: \`useNavigate\` from \`@owlmeans/client\` for navigation,
-  \`ctx.entrypoint(protocol).call(...)\` for a backend call, a typed
-  \`handlers<Context>()\` callback bound to its protocol for an endpoint, and the state hooks
+  \`ctx.entrypoint(protocol).call(...)\` for a backend call, a plain exported handler wrapped ONCE
+  where it is bound for an endpoint (see "Writing an endpoint handler"), and the state hooks
   (\`useStoreModel\`/\`useStoreList\` over a state resource) for client state. Do NOT install the
   package and do NOT create the missing module.
 - A missing export from a \`*.ts\` module — a selector, an action creator, a thunk, a
@@ -1389,9 +1411,29 @@ The job's name IS its entrypoint alias. Declare \`app.job.<name>\` in \`consts.t
 sentinel, and the protocol in \`entrypoints.ts\` with \`job()\` from \`@owlmeans/route\`.
 
 ## 3. The processor — \`sources/worker/src/jobs/<name>.ts\`
-A plain async function created with \`handlers<Context>()\` and bound to the job protocol, exactly
-like an endpoint handler. It RETURNS its result; throwing a \`ResilientError\` subclass is how a
-refusal is reported, and the class survives the broker.
+A PLAIN exported async function — named exports only, exactly like an endpoint handler. It never
+imports \`handlers\` and never calls \`handlers<Context>()\`; that belongs only in
+\`sources/worker/src/entrypoints.ts\`, which wraps it EXACTLY ONCE when binding it:
+
+    // sources/worker/src/jobs/report-build.ts — the processor module
+    export const handleReportBuildJob = async (req: ReportBuildRequest, ctx: Context) => { ... }
+
+    // sources/worker/src/entrypoints.ts — the ONLY wrap
+    import * as jobs from '@/jobs/index.js'
+    const worker = handlers<Context>()
+    bind(protocols.job.reportBuild, worker.request(protocols.job.reportBuild, jobs.handleReportBuildJob))
+
+WRONG — the processor module ALSO calls \`handlers()\` and wraps itself, so the export bound above
+is wrapped a SECOND time. \`tsc\` catches it (\`TS2345 "BoundEntrypointHandler<…> is not
+assignable"\`); left unfixed, every enqueued job then fails with \`TypeError: handler is not a
+function\`:
+
+    // WRONG — sources/worker/src/jobs/report-build.ts
+    const worker = handlers<Context>()
+    export const handleReportBuildJob = worker.request(protocols.job.reportBuild, async (req, ctx) => { ... })
+
+It RETURNS its result; throwing a \`ResilientError\` subclass is how a refusal is reported, and the
+class survives the broker.
 
 Two rules with no equivalent on the HTTP side:
 - **Call \`job.touch()\` inside every long loop.** The broker judges liveness by the lock, and
@@ -1400,8 +1442,8 @@ Two rules with no equivalent on the HTTP side:
 - **A processor must be safe to run twice.** Skip what a previous attempt recorded, or delete
   what it created, and say in a comment which of the two this one does.
 
-Bind it in \`sources/worker/src/entrypoints.ts\` above the sentinel. Enqueue from an endpoint
-with the same typed call used for HTTP: \`context.entrypoint(appEntrypoints.job.<name>).call({ body: data })\`.
+Enqueue from an endpoint with the same typed call used for HTTP:
+\`context.entrypoint(appEntrypoints.job.<name>).call({ body: data })\`.
   `),
 
   skill(ViableSkill.TargetAgents, 'LLM agents inside the application', `

package/src/slot/consts.ts

@@ -41,6 +41,14 @@ export enum SlotCommandType {
 
 export enum SlotGitCommand {
   Ensure = 'ensure',
+  /**
+   * Bring a remote repository's tree onto a volume that already exists.
+   *
+   * NOT `git clone`: a slot's directory is never empty — provisioning leaves its own metadata
+   * there — and `git clone` refuses a non-empty destination. The executor therefore initializes,
+   * adds the remote, fetches at a bounded depth and checks the branch out over the tree.
+   */
+  Clone = 'clone',
   Status = 'status',
   Commit = 'commit',
   Log = 'log',
@@ -66,6 +74,34 @@ export enum SlotFileCommand {
   DeleteFile = 'deleteFile',
   FindFilesWithEnvVars = 'findFilesWithEnvVars',
   GetRootPath = 'getRootPath',
+  /**
+   * List a tree with a size and a binary flag per entry, bounded by a caller-given limit.
+   *
+   * The reason it exists rather than being composed out of {@link SlotFileCommand.GetSourceList}
+   * plus a read per file: a foreign repository can hold a hundred thousand files, and one round
+   * trip each — over a signed HTTP call to a pod, or over a connector on somebody's laptop — is
+   * not a slower version of the same thing, it is a walk that never finishes.
+   */
+  StatTree = 'statTree',
+  /**
+   * Read the first N bytes of one file.
+   *
+   * A census classifies a file from its head; reading whole files to do it would hold a 1 MB
+   * export in memory to look at its first line. The answer is text, so a binary head comes back
+   * as whatever decoding produced — which is exactly the signal the entropy classification wants.
+   */
+  ReadHead = 'readHead',
+  /**
+   * Move everything in the project root into a subdirectory, keeping a named few in place.
+   *
+   * One command rather than a listing plus a move per file, because it must be ATOMIC from the
+   * caller's point of view: a relocation interrupted half way leaves a tree that is neither the
+   * origin nor a target, and nothing downstream can tell which files already moved. Binary-safe —
+   * it moves paths and never reads contents.
+   */
+  Relocate = 'relocate',
+  /** Delete a directory and everything under it. The purge of a relocated origin. */
+  RemoveTree = 'removeTree',
 }
 
 export enum SlotShellCommand {
@@ -228,6 +264,37 @@ export const COMMAND_DEADLINES: Record<string, number> = {
 
 export const DEFAULT_COMMAND_DEADLINE = 60_000
 
+/**
+ * EXECUTOR-side ceilings for the git commands whose real duration is not a git command's.
+ *
+ * Everything git does inside a slot is local and takes seconds — except a clone, which is a
+ * network fetch of somebody else's repository and is measured in minutes. Bounding it by the
+ * generic git deadline made a conversion's very first step fail on any repository large enough
+ * to be worth converting.
+ */
+export const GIT_COMMAND_DEADLINES: Partial<Record<SlotGitCommand, number>> = {
+  [SlotGitCommand.Clone]: 600_000,
+}
+
+/** What every other git command gets. The value the type-level branch used to hard-code. */
+export const DEFAULT_GIT_COMMAND_DEADLINE = 60_000
+
+/**
+ * EXECUTOR-side ceilings for the file commands that walk or move a whole tree.
+ *
+ * The other file commands are one path each and finish in milliseconds; these three are bounded
+ * by how big the tree is, which for an origin project is set by whoever wrote it.
+ */
+export const FILE_COMMAND_DEADLINES: Partial<Record<SlotFileCommand, number>> = {
+  [SlotFileCommand.StatTree]: 120_000,
+  [SlotFileCommand.Relocate]: 300_000,
+  [SlotFileCommand.RemoveTree]: 120_000,
+  [SlotFileCommand.ReadHead]: 30_000,
+}
+
+/** What every other file command gets. The value the type-level branch used to hard-code. */
+export const DEFAULT_FILE_COMMAND_DEADLINE = 30_000
+
 /**
  * CALLER-side ceilings per command type: how long the asker waits for an answer.
  *
@@ -266,6 +333,33 @@ export const SHELL_COMMAND_TIMEOUTS: Record<string, number> = {
   [SlotShellCommand.Integrity]: 25_000,       // executor deadline (15s) + margin
 }
 
+/**
+ * Per-COMMAND caller ceilings for git and for files.
+ *
+ * Each is its executor deadline plus the same 40 s margin: the caller's bound must outlast the
+ * executor's, or a command that failed cleanly inside its own deadline reaches the caller as a
+ * timeout and the real reason — the one the executor took the trouble to produce — is lost.
+ */
+export const GIT_COMMAND_TIMEOUTS: Partial<Record<SlotGitCommand, number>> = {
+  [SlotGitCommand.Clone]: 640_000,
+}
+
+export const FILE_COMMAND_TIMEOUTS: Partial<Record<SlotFileCommand, number>> = {
+  [SlotFileCommand.StatTree]: 160_000,
+  [SlotFileCommand.Relocate]: 340_000,
+  [SlotFileCommand.RemoveTree]: 160_000,
+  [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]
+    default: return FILE_COMMAND_TIMEOUTS[command as SlotFileCommand]
+  }
+}
+
 /**
  * Resolve the caller-side bound for one command.
  *
@@ -276,12 +370,24 @@ export const SHELL_COMMAND_TIMEOUTS: Record<string, number> = {
 export const commandTimeout = (
   type: SlotCommandType, command: string, override?: number
 ): number => override
-  ?? (type === SlotCommandType.Shell ? SHELL_COMMAND_TIMEOUTS[command] : undefined)
+  ?? perCommandTimeout(type, command)
   ?? COMMAND_TIMEOUTS[type]
   ?? DEFAULT_COMMAND_TIMEOUT
 
-/** Resolve the executor-side deadline for one command. */
-export const commandDeadline = (type: SlotCommandType, command: string): number =>
-  type === SlotCommandType.Shell
-    ? COMMAND_DEADLINES[command] ?? DEFAULT_COMMAND_DEADLINE
-    : type === SlotCommandType.Git ? 60_000 : 30_000
+/**
+ * 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
+    default:
+      return FILE_COMMAND_DEADLINES[command as SlotFileCommand] ?? DEFAULT_FILE_COMMAND_DEADLINE
+  }
+}

package/src/slot/schemas.ts

@@ -1,6 +1,6 @@
 import type { JSONSchemaType } from 'ajv'
 import { SlotCommandType, SlotFileCommand, SlotGitCommand, SlotShellCommand } from './consts.js'
-import type { SlotCommandPayload } from './types.js'
+import type { SlotCommandPayload, SlotGitCloneArgs } from './types.js'
 
 export const SlotCommandPayloadSchema = {
   type: 'object',
@@ -25,3 +25,22 @@ export const SlotCommandPayloadSchema = {
   required: ['type', 'command'],
   additionalProperties: false
 } as JSONSchemaType<SlotCommandPayload>
+
+/**
+ * The clone command's arguments, as a signed body carries them.
+ *
+ * `token` is declared because it is SENT — a body field the schema does not declare is stripped
+ * by validation and then verified against a signature the sender made over the whole thing, which
+ * the guard reports as a 401 rather than as the validation gap it is.
+ */
+export const SlotGitCloneArgsSchema = {
+  type: 'object',
+  properties: {
+    remoteUrl: { type: 'string', minLength: 1, maxLength: 2048 },
+    branch: { type: 'string', maxLength: 256, nullable: true },
+    depth: { type: 'number', minimum: 0, nullable: true },
+    token: { type: 'string', maxLength: 4096, nullable: true },
+  },
+  required: ['remoteUrl'],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<SlotGitCloneArgs>

package/src/slot/types.ts

@@ -75,6 +75,86 @@ export interface SlotGitLogResult {
   commits: SlotGitCommitInfo[]
 }
 
+/**
+ * Bring a remote repository onto the volume.
+ *
+ * `token` is a per-invocation credential and never reaches the tree: the executor passes it
+ * through the process environment for the one fetch, exactly as push and pull already do, so it
+ * appears in no `.git/config`, no remote URL and no argv anything can observe.
+ */
+export interface SlotGitCloneArgs {
+  remoteUrl: string
+  /** The branch to check out. Absent means whatever the remote calls its default. */
+  branch?: string
+  /** Fetch depth; 0 means the whole history. Defaults to a shallow fetch. */
+  depth?: number
+  token?: string
+}
+
+export interface SlotGitCloneResult {
+  cloned: boolean
+  /** The branch actually checked out — the resolved default, when none was asked for. */
+  branch: string
+  head: SlotGitCommitInfo | null
+  /** Executor diagnostics, when it has any worth reporting. */
+  result?: string
+}
+
+/**
+ * One entry of a {@link SlotFileCommand.StatTree} listing.
+ *
+ * The shape both a publisher and a connector answer with, so a census walks a pod's volume and a
+ * developer's own directory through one contract. `binary` is the executor's own verdict — the
+ * caller has not read the file and cannot form one.
+ */
+export interface FileStat {
+  path: string
+  bytes: number
+  binary: boolean
+  modifiedAt?: string
+}
+
+export interface StatTreeArgs {
+  /** Project-relative directory to walk. Absent means the whole project. */
+  dir?: string
+  /** Entries to return before the answer reports itself truncated. */
+  limit?: number
+}
+
+/**
+ * `total` is what the walk SAW, `entries` what it returned.
+ *
+ * The two differ on a truncated walk, and the difference is what tells a caller its picture of the
+ * tree is partial — a bounded listing that reported only what it returned would be indistinguish-
+ * able from a small repository.
+ */
+export interface StatTreeResult {
+  entries: FileStat[]
+  truncated: boolean
+  total: number
+}
+
+export interface ReadHeadArgs {
+  path: string
+  bytes: number
+}
+
+/** Move everything in the project root under `dir`, leaving the named entries where they are. */
+export interface RelocateArgs {
+  dir: string
+  /** Root-relative names that stay put — the slot's own metadata and markers. */
+  keep?: string[]
+}
+
+export interface RelocateResult {
+  moved: number
+  kept: string[]
+}
+
+export interface RemoveTreeArgs {
+  dir: string
+}
+
 /** Arguments a shell command may carry. */
 export interface SlotShellArgs {
   subproject?: SubProject

package/tests/connect-convert.spec.ts

@@ -0,0 +1,162 @@
+import { describe, expect, test } from 'bun:test'
+import Ajv from 'ajv'
+import addFormats from 'ajv-formats'
+import { RouteMethod, route } from '@owlmeans/route'
+import { aliasOf, openProtocol, protocols } from '@owlmeans/entrypoint'
+import { connect, ConnectInquiryKind, ConnectJobKind, ConnectOpKind } from '../src/connect/consts.js'
+import { connectProtocols } from '../src/connect/entrypoints.js'
+import { connectRef } from '../src/connect/references.js'
+import {
+  ConnectCapabilitiesSchema, ConnectConvertCreateBodySchema, ConnectConvertProceedBodySchema,
+  ConnectInquiryParamsSchema, ConnectPipelineResumeBodySchema, InquiryAnswerSchema
+} from '../src/connect/schemas.js'
+import { ConnectExecutor } from '../src/connect/consts.js'
+import { InquiryKind } from '@owlmeans/llm-common'
+import { ConversionDecision, OriginKind } from '../src/convert/consts.js'
+
+const compiler = () => addFormats(new Ajv({ strict: false }))
+
+const entrypoints = () => connectProtocols({
+  guard: 'test-guard',
+  gate: { alias: 'test-gate', params: ['id'] },
+  localLlm: { alias: 'test-paid-llm', params: ['id'] },
+  updateBase: openProtocol(route('test:update:base', '/update')),
+})
+
+const entrypointOf = (alias: string) => {
+  const found = protocols(entrypoints()).find(item => item.alias === alias)
+  expect(found, alias).toBeDefined()
+
+  return found!
+}
+
+/** The immutable declaration a route model wraps — path, method and parent as written. */
+const routeOf = (alias: string) => entrypointOf(alias).route.route
+
+describe('viable-common - the conversion additions to the connector contract', () => {
+  test('every new schema compiles', () => {
+    const ajv = compiler()
+    const schemas: [string, object][] = [
+      ['InquiryAnswerSchema', InquiryAnswerSchema],
+      ['ConnectInquiryParamsSchema', ConnectInquiryParamsSchema],
+      ['ConnectConvertCreateBodySchema', ConnectConvertCreateBodySchema],
+      ['ConnectConvertProceedBodySchema', ConnectConvertProceedBodySchema],
+      ['ConnectPipelineResumeBodySchema', ConnectPipelineResumeBodySchema],
+      ['ConnectCapabilitiesSchema', ConnectCapabilitiesSchema],
+    ]
+
+    for (const [name, schema] of schemas) {
+      expect(() => ajv.compile(schema as never), name).not.toThrow()
+    }
+  })
+
+  test('an answer carries one value or several, and declining is a value too', () => {
+    const validate = compiler().compile(InquiryAnswerSchema as never)
+
+    expect(validate({ inquiryId: 'q1', value: 'yes' })).toBe(true)
+    expect(validate({ inquiryId: 'q1', value: ['a', 'b'] })).toBe(true)
+    expect(validate({ inquiryId: 'q1', declined: true })).toBe(true)
+    expect(validate({ inquiryId: 'q1', text: 'because the origin has two admin roles' })).toBe(true)
+    expect(validate({ value: 'orphaned' })).toBe(false)
+  })
+
+  test('a resume carries the answers the parked run asked for', () => {
+    const validate = compiler().compile(ConnectPipelineResumeBodySchema as never)
+
+    expect(validate({ answers: { q1: { inquiryId: 'q1', value: 'yes' } } })).toBe(true)
+    expect(validate({})).toBe(true)
+  })
+
+  test('the convert bodies accept an origin and a decision', () => {
+    const ajv = compiler()
+    const create = ajv.compile(ConnectConvertCreateBodySchema as never)
+    const proceed = ajv.compile(ConnectConvertProceedBodySchema as never)
+
+    expect(create({
+      name: 'Deskflow',
+      origin: { kind: OriginKind.Github, repoUrl: 'https://github.com/acme/deskflow' },
+    })).toBe(true)
+    // A local target the connector is already attached to fetches nothing.
+    expect(create({})).toBe(true)
+    expect(proceed({ decision: ConversionDecision.Extract })).toBe(true)
+    expect(proceed({ decision: 'teleport' })).toBe(false)
+  })
+
+  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.
+    const validate = compiler().compile(ConnectCapabilitiesSchema as never)
+
+    expect(validate({
+      harness: 'claude-code',
+      tiers: {},
+      subagents: true,
+      effortControl: true,
+      executors: [ConnectExecutor.Files, ConnectExecutor.Human, 'telepathy'],
+    })).toBe(true)
+  })
+
+  test('the conversion and generated-file routes are declared, at their paths and methods', () => {
+    const expected: [string, string, RouteMethod][] = [
+      [connect.convert.create, '/convert', RouteMethod.POST],
+      [connect.convert.check, '/convert/:id/check', RouteMethod.GET],
+      [connect.convert.start, '/convert/:id/start', RouteMethod.POST],
+      [connect.convert.proceed, '/convert/:id/proceed', RouteMethod.POST],
+      [connect.convert.cancel, '/convert/:id/cancel', RouteMethod.POST],
+      [connect.convert.status, '/convert/:id', RouteMethod.GET],
+      [connect.convert.purge, '/convert/:id/purge', RouteMethod.POST],
+      [connect.inquiry.answer, '/project/:id/inquiry/:inquiryId', RouteMethod.POST],
+      [connect.project.converterLlm, '/project/:id/converter-llm', RouteMethod.POST],
+      [connect.files.list, '/project/:id/files', RouteMethod.GET],
+    ]
+
+    for (const [alias, path, method] of expected) {
+      const route = routeOf(alias)
+      expect(route.path, alias).toBe(path)
+      expect(route.method, alias).toBe(method)
+    }
+  })
+
+  test('every conversion route has the typed reference used by connector adapters', () => {
+    expect(connectRef.convert.create.alias).toBe(connect.convert.create)
+    expect(connectRef.convert.check.alias).toBe(connect.convert.check)
+    expect(connectRef.convert.start.alias).toBe(connect.convert.start)
+    expect(connectRef.convert.proceed.alias).toBe(connect.convert.proceed)
+    expect(connectRef.convert.cancel.alias).toBe(connect.convert.cancel)
+    expect(connectRef.convert.status.alias).toBe(connect.convert.status)
+    expect(connectRef.convert.purge.alias).toBe(connect.convert.purge)
+    expect(connectRef.inquiry.answer.alias).toBe(connect.inquiry.answer)
+    expect(connectRef.project.converterLlm.alias).toBe(connect.project.converterLlm)
+    expect(connectRef.files.list.alias).toBe(connect.files.list)
+  })
+
+  test('the conversion routes hang under the connector base and carry no paid gate', () => {
+    // Delegated inference is the DEFAULT for a conversion, not an experimental capability — so
+    // unlike `project.llm`, nothing here sits behind the local-LLM gate.
+    expect(entrypointOf(connect.project.llm).gate?.alias).toBe('test-paid-llm')
+
+    const gated = [...Object.values(connect.convert), connect.inquiry.answer,
+      connect.project.converterLlm]
+    for (const alias of gated) {
+      expect(entrypointOf(alias).gate, alias).toBeUndefined()
+      expect(aliasOf(routeOf(alias).parent!), alias).toBe(connect.base)
+    }
+  })
+
+  test('the vocabulary a conversion adds to the connector is declared', () => {
+    expect(ConnectOpKind.Inquiry).toBe('inquiry')
+    expect(ConnectExecutor.Human).toBe('human')
+    expect(Object.values(ConnectInquiryKind)).toEqual(['choice', 'text', 'confirm'])
+    // The platform's mapper is a widening rather than a translation table, which is only true
+    // while the two enums stay byte-identical — `manager-api` does not depend on the model
+    // runtime, so nothing else in the stack would notice one of them gaining a fourth shape.
+    expect(Object.values(ConnectInquiryKind)).toEqual(Object.values(InquiryKind))
+    // One job kind per stage: each stage is its own pipeline run, looked up by the alias its kind
+    // names, so a single `convert` kind would match whichever run row happened to be newest.
+    expect(ConnectJobKind.ConvertIntake).toBe('convert-intake')
+    expect(ConnectJobKind.ConvertAnalysis).toBe('convert-analysis')
+    expect(ConnectJobKind.ConvertExtraction).toBe('convert-extraction')
+    expect(ConnectJobKind.ConvertImplementation).toBe('convert-implementation')
+    expect(ConnectJobKind.ConvertPurge).toBe('convert-purge')
+  })
+})

package/tests/connect-entrypoints.spec.ts

@@ -1,17 +1,25 @@
 import { describe, expect, test } from 'bun:test'
-import { protocols } from '@owlmeans/entrypoint'
+import { openProtocol, protocols } from '@owlmeans/entrypoint'
 import { DEFAULT_GUARD } from '@owlmeans/auth-common'
+import { route } from '@owlmeans/route'
 import { connect } from '../src/connect/consts.js'
 import { connectProtocols } from '../src/connect/entrypoints.js'
 
 describe('@owlmeans/viable-common — connector protocol tree', () => {
-  const tree = connectProtocols({ guard: DEFAULT_GUARD, updateBase: 'manager:update' })
+  const tree = connectProtocols({
+    guard: DEFAULT_GUARD,
+    updateBase: openProtocol(route('manager:update', '/update')),
+  })
 
   test('exports named immutable declarations and a complete flat materialization view', () => {
     expect(tree.base.alias).toBe(connect.base)
     expect(tree.session.open.alias).toBe(connect.session.open)
     expect(tree.project.llm.alias).toBe(connect.project.llm)
-    expect(protocols(tree)).toHaveLength(28)
-    expect(new Set(protocols(tree).map(protocol => protocol.alias)).size).toBe(28)
+    expect(tree.project.converterLlm.alias).toBe(connect.project.converterLlm)
+    expect(tree.convert.proceed.alias).toBe(connect.convert.proceed)
+    expect(tree.inquiry.answer.alias).toBe(connect.inquiry.answer)
+    expect(tree.files.list.alias).toBe(connect.files.list)
+    expect(protocols(tree)).toHaveLength(38)
+    expect(new Set(protocols(tree).map(protocol => protocol.alias)).size).toBe(38)
   })
 })