@owlmeans/viable-common 0.0.23 → 0.0.25

package/src/skills/catalogue.ts

@@ -82,9 +82,6 @@ export const ALIAS_CONVENTION = `
   \`web:layout:\` alias and no \`app.web.layout\` — writing either addresses nothing.
 - An endpoint alias is \`api:<entity>:<action>\` — \`api:task:list\`, \`api:task:create\`. The
   group alias that carries the shared path and guard is \`api:<entity>\` — \`api:task\`.
-- A queued job alias is \`job:<entity>:<action>\` — \`job:report:build\`, \`job:contract:analyze\`.
-  A job is never given a \`web:\` or \`api:\` alias, and an endpoint is never given a \`job:\` one:
-  the prefix is what says which side serves it.
 - Lowercase kebab-case in every segment. The prefix is NOT optional and NOT decorative: access
   rules are applied per side by it.
 `.trim()
@@ -103,11 +100,12 @@ The generated project is a \`@owlmeans/create-app\` monorepo with five workspace
 - \`sources/web\` — the react application.
 - \`sources/worker\` — the queue consumer. Same context, no HTTP routes, one processor per job.
 
-These files are the CONTRACT between the packages. Every screen, endpoint and job passes through
-them, and each has a sentinel comment marking where a new line goes:
+These files are the CONTRACT between the public packages. Every screen and endpoint passes through
+them; technical worker protocols live in the backend package instead:
 
 - \`sources/common/src/consts.ts\` — the \`app\` alias tree.
 - \`sources/common/src/entrypoints.ts\` — the shared immutable protocol tree (\`appEntrypoints\`).
+- \`sources/backend/src/jobs/index.ts\` — backend-only queue protocols and declarations.
 - \`sources/api/src/entrypoints.ts\` — server bindings: \`bind\` + one \`handlers<Context>()\` wrap
   per handler.
 - \`sources/web/src/entrypoints.ts\` — client bindings (\`bindAll\` + \`bindScreen\`).
@@ -1390,25 +1388,34 @@ the work is invisible and the user is left pressing a button that appears to do
   `),
 
   skill(ViableSkill.WorkerJobs, 'Queues, jobs and processors', `
-Three files have to agree, and a job that exists in two of the three is worse than one that
+Three server-side bindings have to agree, and a job that exists in two of the three is worse than one that
 exists in none — a declared name nothing processes is a message that piles up, and a processor
 with no declaration is dead code the barrel still imports.
 
-## 1. The queue — \`sources/backend/src/jobs/index.ts\`
+## 1. The protocol and queue — \`sources/backend/src/jobs/index.ts\`
 A queue is an ADDRESS: it says what exists and which job names it accepts. Both the api (which
 enqueues) and the worker (which consumes) read this one list, and a job name the queue does not
-declare is refused at enqueue time.
+declare is refused at enqueue time. The technical protocol belongs here too; common and web must
+not import it.
 
 \`\`\`ts
+export const jobProtocols = {
+  reportBuild: protocol(route(
+    'job:report:build', '/report-build',
+    queueRoute({ service: APP_WORKER, queue: APP_QUEUE, timeout: 30_000 }),
+  ), contract(typed())),
+}
 export const queues: QueueDeclaration[] = [
-  { name: APP_QUEUE, jobs: [app.job.test, app.job.<name>],
+  { name: APP_QUEUE, jobs: [jobProtocols.reportBuild.alias],
     worker: { concurrency: 4, lockDuration: 60_000 } },
 ]
 \`\`\`
 
-## 2. The alias and the entrypoint — \`sources/common/src\`
-The job's name IS its entrypoint alias. Declare \`app.job.<name>\` in \`consts.ts\` above the
-sentinel, and the protocol in \`entrypoints.ts\` with \`job()\` from \`@owlmeans/route\`.
+Use \`job()\` from \`@owlmeans/queue\`, never from the generic route package.
+
+## 2. The producer — \`sources/api/src/entrypoints.ts\`
+Bind \`bindClient(jobProtocols.reportBuild)\`. Public API contracts in common describe the domain
+operation and do not disclose that the handler delegates to a queue.
 
 ## 3. The processor — \`sources/worker/src/jobs/<name>.ts\`
 A PLAIN exported async function — named exports only, exactly like an endpoint handler. It never
@@ -1421,7 +1428,7 @@ imports \`handlers\` and never calls \`handlers<Context>()\`; that belongs only
     // 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))
+    bind(jobProtocols.reportBuild, worker.request(jobProtocols.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
@@ -1430,7 +1437,7 @@ function\`:
 
     // WRONG — sources/worker/src/jobs/report-build.ts
     const worker = handlers<Context>()
-    export const handleReportBuildJob = worker.request(protocols.job.reportBuild, async (req, ctx) => { ... })
+    export const handleReportBuildJob = worker.request(jobProtocols.reportBuild, async (req, ctx) => { ... })
 
 It RETURNS its result; throwing a \`ResilientError\` subclass is how a refusal is reported, and the
 class survives the broker.
@@ -1443,7 +1450,7 @@ Two rules with no equivalent on the HTTP side:
   what it created, and say in a comment which of the two this one does.
 
 Enqueue from an endpoint with the same typed call used for HTTP:
-\`context.entrypoint(appEntrypoints.job.<name>).call({ body: data })\`.
+\`context.entrypoint(jobProtocols.<name>).call({ body: data })\`.
   `),
 
   skill(ViableSkill.TargetAgents, 'LLM agents inside the application', `

package/tests/connect-convert.spec.ts

@@ -3,7 +3,7 @@ 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 { connect, ConnectInquiryKind, ConnectOpKind } from '../src/connect/consts.js'
 import { connectProtocols } from '../src/connect/entrypoints.js'
 import { connectRef } from '../src/connect/references.js'
 import {
@@ -151,12 +151,6 @@ describe('viable-common - the conversion additions to the connector contract', (
     // 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')
+    expect(connect.convert.status).toBe('viable:manager-api:connect:convert:status')
   })
 })

package/tests/connect-entrypoints.spec.ts

@@ -2,9 +2,8 @@ import { describe, expect, test } from 'bun:test'
 import { openProtocol, protocols } from '@owlmeans/entrypoint'
 import { DEFAULT_GUARD } from '@owlmeans/auth-common'
 import { route } from '@owlmeans/route'
-import { connect, ConnectJobKind } from '../src/connect/consts.js'
+import { connect } from '../src/connect/consts.js'
 import { connectProtocols } from '../src/connect/entrypoints.js'
-import { JOB_SEPARATOR, jobIdOf, parseJobId } from '../src/connect/jobs.js'
 import { connectRef } from '../src/connect/references.js'
 
 describe('@owlmeans/viable-common — connector protocol tree', () => {
@@ -18,6 +17,7 @@ describe('@owlmeans/viable-common — connector protocol tree', () => {
     expect(tree.session.open.alias).toBe(connect.session.open)
     expect(tree.project.llm.alias).toBe(connect.project.llm)
     expect(tree.project.converterLlm.alias).toBe(connect.project.converterLlm)
+    expect(tree.story.status.alias).toBe(connect.story.status)
     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)
@@ -25,33 +25,15 @@ describe('@owlmeans/viable-common — connector protocol tree', () => {
     expect(new Set(protocols(tree).map(protocol => protocol.alias)).size).toBe(32)
   })
 
-  test('carries no story routes: stories are planning cards served by the planning tree', () => {
-    expect((tree as Record<string, unknown>).story).toBeUndefined()
-    expect((connect as Record<string, unknown>).story).toBeUndefined()
-    expect((connectRef as unknown as Record<string, unknown>).story).toBeUndefined()
-    expect(protocols(tree).some(protocol => protocol.alias.includes(':story:'))).toBe(false)
+  test('keeps story mutations in planning and exposes only the composed story status', () => {
+    expect(Object.keys(tree.story)).toEqual(['status'])
+    expect(Object.keys(connect.story)).toEqual(['status'])
+    expect(Object.keys(connectRef.story)).toEqual(['status'])
+    expect(tree.story.status.route.route.path).toBe('/project/:id/story/:storyId/status')
   })
-})
-
-describe('@owlmeans/viable-common — connector job ids', () => {
-  test('a story job id names the card and splits back into its parts', () => {
-    const id = jobIdOf(ConnectJobKind.StoryDevelop, 'project-card', 'story-card')
-
-    expect(id).toBe(['story-develop', 'project-card', 'story-card'].join(JOB_SEPARATOR))
-    expect(parseJobId(id)).toEqual({
-      kind: ConnectJobKind.StoryDevelop, projectId: 'project-card', suffix: 'story-card',
-    })
-  })
-
-  test('a job with no subject carries no suffix', () => {
-    expect(parseJobId(jobIdOf(ConnectJobKind.ProjectInit, 'p1'))).toEqual({
-      kind: ConnectJobKind.ProjectInit, projectId: 'p1',
-    })
-  })
-
-  test('a suffix that contains the separator is rejoined, never truncated', () => {
-    const suffix = `run${JOB_SEPARATOR}tail`
-
-    expect(parseJobId(jobIdOf(ConnectJobKind.PipelineResume, 'p1', suffix)).suffix).toBe(suffix)
+  test('has no generic connector job endpoint', () => {
+    expect((tree.project as Record<string, unknown>).job).toBeUndefined()
+    expect((connect.project as Record<string, unknown>).job).toBeUndefined()
+    expect((connectRef.project as Record<string, unknown>).job).toBeUndefined()
   })
 })

package/build/connect/jobs.d.ts

@@ -1,25 +0,0 @@
-import type { ConnectJobKind } from './consts.js';
-/**
- * The separator a job id is joined with.
- *
- * `~`, because every other separator in play is already spoken for: a route alias is
- * colon-delimited and so is every run id (`init:<projectId>`, `story:<storyId>`), so a job id
- * built with one could not be split back apart.
- */
-export declare const JOB_SEPARATOR = "~";
-/**
- * A job's id: its kind, the project card it belongs to, and the subject it is about.
- *
- * The suffix is a CARD id for a story job and a run id for a pipeline job — never a story code.
- * Declared here rather than by whoever answers the job, because the SDK composes the id it then
- * polls for: two spellings of one id is a job nobody can find.
- */
-export declare const jobIdOf: (kind: ConnectJobKind, projectId: string, suffix?: string) => string;
-export interface ParsedJobId {
-    kind: ConnectJobKind;
-    projectId: string;
-    suffix?: string;
-}
-/** Split a job id back into what {@link jobIdOf} composed it from. */
-export declare const parseJobId: (jobId: string) => ParsedJobId;
-//# sourceMappingURL=jobs.d.ts.map

package/build/connect/jobs.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"jobs.d.ts","sourceRoot":"","sources":["../../src/connect/jobs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEjD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,MAAM,CAAA;AAEhC;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,SAAU,cAAc,aAAa,MAAM,WAAW,MAAM,KAAG,MACP,CAAA;AAE5E,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,cAAc,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,sEAAsE;AACtE,eAAO,MAAM,UAAU,UAAW,MAAM,KAAG,WAW1C,CAAA"}

package/build/connect/jobs.js

@@ -1,29 +0,0 @@
-/**
- * The separator a job id is joined with.
- *
- * `~`, because every other separator in play is already spoken for: a route alias is
- * colon-delimited and so is every run id (`init:<projectId>`, `story:<storyId>`), so a job id
- * built with one could not be split back apart.
- */
-export const JOB_SEPARATOR = '~';
-/**
- * A job's id: its kind, the project card it belongs to, and the subject it is about.
- *
- * The suffix is a CARD id for a story job and a run id for a pipeline job — never a story code.
- * Declared here rather than by whoever answers the job, because the SDK composes the id it then
- * polls for: two spellings of one id is a job nobody can find.
- */
-export const jobIdOf = (kind, projectId, suffix) => [kind, projectId, ...(suffix != null ? [suffix] : [])].join(JOB_SEPARATOR);
-/** Split a job id back into what {@link jobIdOf} composed it from. */
-export const parseJobId = (jobId) => {
-    const [kind, projectId, ...rest] = jobId.split(JOB_SEPARATOR);
-    // A suffix may carry the separator back if one ever ends up in a card or run id, so the tail is
-    // rejoined rather than taken as its first segment.
-    const suffix = rest.length > 0 ? rest.join(JOB_SEPARATOR) : undefined;
-    return {
-        kind: kind,
-        projectId: projectId ?? '',
-        ...(suffix != null ? { suffix } : {}),
-    };
-};
-//# sourceMappingURL=jobs.js.map

package/build/connect/jobs.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"jobs.js","sourceRoot":"","sources":["../../src/connect/jobs.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAA;AAEhC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,IAAoB,EAAE,SAAiB,EAAE,MAAe,EAAU,EAAE,CAC1F,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAA;AAQ5E,sEAAsE;AACtE,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAa,EAAe,EAAE;IACvD,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC,CAAA;IAC7D,gGAAgG;IAChG,mDAAmD;IACnD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IAErE,OAAO;QACL,IAAI,EAAE,IAAsB;QAC5B,SAAS,EAAE,SAAS,IAAI,EAAE;QAC1B,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtC,CAAA;AACH,CAAC,CAAA"}

package/src/connect/jobs.ts

@@ -1,40 +0,0 @@
-import type { ConnectJobKind } from './consts.js'
-
-/**
- * The separator a job id is joined with.
- *
- * `~`, because every other separator in play is already spoken for: a route alias is
- * colon-delimited and so is every run id (`init:<projectId>`, `story:<storyId>`), so a job id
- * built with one could not be split back apart.
- */
-export const JOB_SEPARATOR = '~'
-
-/**
- * A job's id: its kind, the project card it belongs to, and the subject it is about.
- *
- * The suffix is a CARD id for a story job and a run id for a pipeline job — never a story code.
- * Declared here rather than by whoever answers the job, because the SDK composes the id it then
- * polls for: two spellings of one id is a job nobody can find.
- */
-export const jobIdOf = (kind: ConnectJobKind, projectId: string, suffix?: string): string =>
-  [kind, projectId, ...(suffix != null ? [suffix] : [])].join(JOB_SEPARATOR)
-
-export interface ParsedJobId {
-  kind: ConnectJobKind
-  projectId: string
-  suffix?: string
-}
-
-/** Split a job id back into what {@link jobIdOf} composed it from. */
-export const parseJobId = (jobId: string): ParsedJobId => {
-  const [kind, projectId, ...rest] = jobId.split(JOB_SEPARATOR)
-  // A suffix may carry the separator back if one ever ends up in a card or run id, so the tail is
-  // rejoined rather than taken as its first segment.
-  const suffix = rest.length > 0 ? rest.join(JOB_SEPARATOR) : undefined
-
-  return {
-    kind: kind as ConnectJobKind,
-    projectId: projectId ?? '',
-    ...(suffix != null ? { suffix } : {}),
-  }
-}