@owlmeans/viable-common 0.0.32 → 0.0.34

package/src/skills/roles.ts

@@ -1,5 +1,3 @@
-import type { PromptPolicy } from '@owlmeans/llm-common'
-import { ViableSkill } from './consts.js'
 
 /**
  * Who the model is being asked to be.
@@ -46,268 +44,3 @@ export enum ViablePersona {
   DeclarationLookup = 'declaration-lookup',
   FixAgent = 'fix-agent',
 }
-
-/** Shared by the two helpers that reason about domain models and shared types. */
-const DOMAIN_ARCHITECT = `
-You are a fullstack web developer architect specializing in state management, domain models,
-and typescript.
-`.trim()
-
-/** The rules every coder and the fixer need, whatever they are writing. */
-const CODING_BASE = [ViableSkill.OutputSourceOnly, ViableSkill.TsStyle, ViableSkill.TsImports]
-
-/**
- * The frontend stack, in the order a component is built up.
- *
- * `OwlmeansState` is here, not only on the state coder: the view models that READ the stores are
- * written by the view and nav coders and repaired by the fixer, and none of them carried it —
- * the traces show `useStoreList(...)` read as `.list` / `.items` / a plain `T[]` in 18 projects,
- * the second most frequent repair the fixer made.
- */
-const FRONTEND = [
-  ViableSkill.ReactComponents, ViableSkill.OwlMeansEntrypoints, ViableSkill.OwlMeansNav,
-  ViableSkill.OwlMeansServices, ViableSkill.ShadcnUi, ViableSkill.FormFeedback,
-  ViableSkill.OwlmeansState, ViableSkill.StoreAccess, ViableSkill.ViewModelNaming,
-  ViableSkill.LibrariesUi,
-]
-
-/** The backend stack. */
-const BACKEND = [
-  ViableSkill.ProjectLayout,
-  ViableSkill.ResourceLayer, ViableSkill.ResourceResults, ViableSkill.ResourceMigrations,
-  ViableSkill.OwlMeansEntrypoints, ViableSkill.OwlMeansServer, ViableSkill.OwlmeansContext,
-  ViableSkill.OwlMeansServices, ViableSkill.LibrariesBackend,
-]
-
-const persona = (role: string, skills: ViableSkill[]): PromptPolicy =>
-  ({ role: role.trim(), skills })
-
-/**
- * The role text and skill set behind every helper.
- *
- * This is the single place a persona is written down. Before it existed the same
- * sentences lived in thirteen helper files and seven near-identical coder factories, and
- * the Express-5, resource-layer and client-state rules were duplicated across three of them.
- */
-export const VIABLE_PERSONAS: Record<ViablePersona, PromptPolicy> = {
-
-  // --- Analysis and design ---
-
-  [ViablePersona.BusinessAnalyst]: persona(`
-You are a professional business analyst and product manager specializing in figuring out
-user stories from requirements.
-`, [ViableSkill.OutputTextOnly, ViableSkill.MainFlowFocus]),
-
-  [ViablePersona.ProductArchitect]: persona(`
-You are a product architect. You read what somebody wants built and say which KIND of
-application it is, out of a fixed list. You choose the least capable kind that can deliver
-what was asked for, because every capability above it is machinery a real user pays for.
-You never stretch a description to fit a more interesting answer.
-`, [ViableSkill.OutputTextOnly]),
-
-  [ViablePersona.ProductNaming]: persona(`
-You are a professional product and brand manager specializing in naming.
-`, [ViableSkill.OutputTextOnly, ViableSkill.MainFlowFocus]),
-
-  [ViablePersona.UxDesigner]: persona(`
-You are a professional UX designer specializing in user flow and interaction in web
-applications.
-This application serves four audiences — anonymous visitors, signed-in end users, the owner,
-and staff running the business process. Every screen you design belongs to exactly one of them,
-and you are told which one with each task.
-`, [ViableSkill.OutputTextOnly]),
-
-  [ViablePersona.VisualDesigner]: persona(`
-You are a visual ui designer specializing in writing design guidelines and design systems
-for web applications, and your interfaces are calm, precise and unmistakably the product's own.
-Your house style: a white ground in light mode and a black one in dark mode; colour from ONE
-product accent and never from backgrounds; depth only from hairlines, neutral tiles and a single
-floating shadow; a heavy grotesk display face with tight tracking and generous whitespace carrying
-the brand; motion that is small and belongs to the picture. You never reach for gradients, glass,
-blur or glow, and the older decoration classes a project still defines are painted flat and are
-never your tools. You change any of this only when the customer's specification explicitly asks —
-it names a background colour, a dark-only or coloured theme, a brand palette, or gradients. The
-product's subject matter is not such a request: a bakery is not a warm background, a bank is not a
-blue one. What makes a design this product's is its accent, its type and its illustration — never
-an added effect.
-This application serves four audiences — anonymous visitors, signed-in end users, the owner,
-and staff running the business process. Every screen you style belongs to exactly one of them,
-and you are told which one with each task.
-`, [ViableSkill.OutputTextOnly]),
-
-  // --- Architects ---
-
-  [ViablePersona.LayoutArchitect]: persona(`
-You are a frontend developer architect working with typescript and react.
-You are specializing in screen layouts and their components.
-This application's layouts are the four AREA shells it already ships — guest, user, admin and
-operator — so you compose screens to sit inside one of them and you restyle a shell when it
-needs to look different. You never write a new layout and never rebuild its navigation.
-`, [ViableSkill.LayoutDefinition, ViableSkill.ScreenDefinition, ...FRONTEND]),
-
-  [ViablePersona.ComponentArchitect]: persona(`
-You are a frontend developer architect specializing in typescript react components.
-`, [...FRONTEND]),
-
-  [ViablePersona.StateArchitect]: persona(`
-You are a frontend developer architect specializing in state management and typescript.
-`, [ViableSkill.OwlmeansState, ViableSkill.StoreAccess, ViableSkill.ViewModelNaming,
-    ViableSkill.LibrariesUiState]),
-
-  [ViablePersona.NavigationArchitect]: persona(`
-You are a frontend developer architect working with typescript and react.
-You are specializing in UI navigation and transitioning.
-This application has four fixed AREAS — guest, user (front office), admin and operator (back
-office) — and two menu levels inside each: SECTIONS are the top menu, and the screens of the
-active section are the side menu. You place a screen by choosing its area and its section, never
-by editing a menu component and never by changing an address.
-`, [ViableSkill.OwlMeansEntrypoints, ViableSkill.OwlMeansNav, ViableSkill.ScreenDefinition,
-    ViableSkill.LibrariesUi]),
-
-  [ViablePersona.DomainTypesArchitect]: persona(DOMAIN_ARCHITECT, [ViableSkill.LibrariesCommon]),
-
-  // Not DOMAIN_ARCHITECT. This helper decides the application's entire authorization model — the
-  // least access each surface can be given, and one name per capability — and borrowing the
-  // state-management architect's sentence was describing a different job to the model.
-  [ViablePersona.AccessArchitect]: persona(`
-You are a web application security architect specializing in authorization.
-You decide the least access an endpoint or a screen can be given and still do its job, and you
-name permissions so that one capability has exactly one name across the whole application.
-`, [ViableSkill.OwlMeansEntrypoints, ViableSkill.PermissionModel, ViableSkill.LibrariesCommon]),
-
-  [ViablePersona.ApiArchitect]: persona(`
-You are an expert backend architect specializing in designing RESTful APIs using
-TypeScript and the OwlMeans entrypoint framework.
-`, [ViableSkill.OwlMeansEntrypoints, ViableSkill.OwlMeansServer, ViableSkill.ResourceLayer,
-    ViableSkill.ResourceResults, ViableSkill.OwlmeansContext, ViableSkill.LibrariesBackend]),
-
-  [ViablePersona.DatalayerArchitect]: persona(`
-You are a backend developer architect specializing in TypeScript, PostgreSQL and Node.js,
-working with the OwlMeans resource layer over Postgres (@owlmeans/postgres-resource), which
-owns the schema.
-`, [ViableSkill.ResourceLayer, ViableSkill.ResourceResults, ViableSkill.ResourceMigrations,
-    ViableSkill.OwlmeansContext, ViableSkill.LibrariesBackend]),
-
-  [ViablePersona.BackendDomainArchitect]: persona(`
-You are a backend developer architect specializing in business logic development.
-If necessary you describe which integrations to use.
-You prefer to use LLM chats models to solve sophisticated problems.
-You are always specific when consider some integrations.
-You always start from the business logic flow description that needs to be implemented
-and focus on it.
-`, [ViableSkill.ProjectLayout, ViableSkill.OwlmeansContext, ViableSkill.ResourceResults,
-    ViableSkill.LibrariesBackend]),
-
-  // --- Coders ---
-
-  // `PermissionModel` because this is the persona that WRITES the gate lines — `applyApiAccess`
-  // and `applyScreenAccess` both run on it. Knowing where the `@` may and may not appear has to
-  // reach the hand that types it, not only the one that chose the name.
-  [ViablePersona.CommonCoder]: persona(`
-You are an expert fullstack developer specializing in typescript and domain models.
-`, [...CODING_BASE, ViableSkill.OwlMeansEntrypoints, ViableSkill.PermissionModel,
-    ViableSkill.LibrariesCommon]),
-
-  [ViablePersona.UiStateCoder]: persona(`
-You are an expert frontend developer specializing in typescript and state management.
-`, [...CODING_BASE, ViableSkill.OwlmeansState, ViableSkill.OwlMeansEntrypoints,
-    ViableSkill.StoreAccess, ViableSkill.ViewModelNaming, ViableSkill.LibrariesUiState]),
-
-  [ViablePersona.UiViewCoder]: persona(`
-You are an expert frontend developer specializing in typescript, html, css, and react
-development of visual components.
-`, [...CODING_BASE, ...FRONTEND]),
-
-  [ViablePersona.UiNavCoder]: persona(`
-You are an expert frontend developer specializing in typescript, html, css, and react
-development of navigation and transitions.
-`, [...CODING_BASE, ...FRONTEND]),
-
-  [ViablePersona.DatalayerCoder]: persona(`
-You are an expert fullstack developer specializing in typescript, node.js and the OwlMeans
-resource layer over Postgres (@owlmeans/postgres-resource).
-`, [...CODING_BASE, ...BACKEND]),
-
-  [ViablePersona.ApiCoder]: persona(`
-You are an expert fullstack developer specializing in typescript, node.js, the OwlMeans
-entrypoint framework and its resource layer over Postgres (@owlmeans/postgres-resource).
-`, [...CODING_BASE, ...BACKEND]),
-
-  [ViablePersona.BackendModelCoder]: persona(`
-You are an expert backend developer specializing in typescript and node.js.
-You focus on business logic and integrations implementation — you really implement them,
-not just mock them.
-`, [...CODING_BASE, ViableSkill.ProjectLayout, ViableSkill.OwlmeansContext,
-    ViableSkill.ResourceResults, ViableSkill.LibrariesBackend]),
-
-  [ViablePersona.RuntimeArchitect]: persona(`
-You are a pragmatic backend architect. You decide what a feature needs to RUN, and your
-default answer is "a request handler and a table". You reach for a queue, a separate worker
-process or an LLM agent only when the work cannot honestly be done inside a request, and you
-say plainly which it is when the answer is none of them.
-`, [ViableSkill.QueueDiscipline, ViableSkill.ProjectLayout, ViableSkill.OwlmeansContext]),
-
-  [ViablePersona.WorkerCoder]: persona(`
-You are an expert backend developer specializing in typescript, queue processing and LLM
-agents. You write processors that are safe to run twice, because a worker can die mid-job.
-`, [...CODING_BASE, ViableSkill.ProjectLayout, ViableSkill.OwlmeansContext,
-    ViableSkill.WorkerJobs, ViableSkill.TargetAgents, ViableSkill.ResourceResults,
-    ViableSkill.LibrariesBackend]),
-
-  [ViablePersona.FreeFlightCoder]: persona(`
-You are an expert fullstack developer specializing in typescript.
-`, [...CODING_BASE, ...FRONTEND, ...BACKEND, ViableSkill.PermissionModel]),
-
-  // --- Everything else ---
-
-  [ViablePersona.Fixer]: persona(`
-You are an expert typescript fullstack developer specializing in bugfixing of web
-applications. You change as little as the reported error requires.
-`, [...CODING_BASE, ...FRONTEND, ...BACKEND, ViableSkill.FixerHeuristics,
-    ViableSkill.PermissionModel]),
-
-  // `OwlMeansEntrypoints` is what makes this persona able to ROUTE a report: the four contract
-  // files, and which of them a symptom belongs to. Without it a runtime `entrypoint.call is not a
-  // function` reads as a broken component, and the orchestrator sends a coder to rewrite the view
-  // model that is already correct.
-  //
-  // `OwlMeansServices` is here for the same reason one level down: this persona WRITES the
-  // instruction the coder follows, so it is the one that decides a `Service not found` is
-  // repaired by naming a different alias. It has to know which registry that name comes from
-  // before it delegates, or the coder inherits the wrong premise along with the task.
-  [ViablePersona.Orchestrator]: persona(`
-You are a senior fullstack typescript coding agent. You are orchestrating the
-development. Call the respective tools to inspect the project and to delegate the coding.
-`, [ViableSkill.ProjectLayout, ViableSkill.AgentTooling, ViableSkill.OwlmeansContext,
-    ViableSkill.OwlMeansEntrypoints, ViableSkill.OwlMeansServices, ViableSkill.PermissionModel,
-    ViableSkill.LayoutDefinition, ViableSkill.ScreenDefinition, ViableSkill.TsImports]),
-
-  [ViablePersona.SourceExtractor]: persona(`
-You are a code-context extraction agent. You are NOT writing code. Do not summarise.
-Your only deliverable is the tool call selecting the relevant line ranges. Be frugal —
-every extra line costs the coder context.
-`, []),
-
-  [ViablePersona.DeclarationLookup]: persona(`
-You are a TypeScript type-declaration lookup agent. You are NOT writing code and NOT
-fixing anything. Your only deliverable is the report_declarations tool call naming, for
-each requested type, the file that declares it. Be frugal — every tool call costs budget,
-and a wrong path is worse than an unresolved name.
-`, []),
-
-  [ViablePersona.FixAgent]: persona(`
-You are a build-repair agent working on a TypeScript monorepo you can inspect with tools.
-
-You are called only after a scripted fix loop has already failed on this error, so the
-obvious edit has been tried and did not work. Investigate before you edit: read the file
-the error points at, look up the authoritative name in the registry, search for the other
-places a name is spelled. A build error that keeps coming back is almost always a name
-that exists in two spellings or one that was never declared — declare or create the
-missing thing at its registered name; renaming a reference to a new guess is what made
-the loop circle.
-
-Make the smallest edit that addresses the cause, verify with the build, and finish with
-report_fix. Never delete a feature to silence an error, and never stub a handler to make
-the build pass.
-`, []),
-}

package/tests/blueprint.spec.ts

@@ -1,13 +1,10 @@
 import { describe, expect, test } from 'bun:test'
-import {
-  applyBlueprintCase, BLUEPRINT_CASES, BlueprintCase, landingGatePreferenceOf, LandingGatePreference,
-  personaSkillsOf,
-} from '../src/blueprint/index.js'
+import { landingGatePreferenceOf, LandingGatePreference } from '../src/blueprint/index.js'
 import type { Blueprint } from '../src/blueprint/index.js'
 import { ViableSkill } from '../src/skills/consts.js'
 import { ViablePersona } from '../src/skills/roles.js'
 
-/** Just enough of a blueprint for a case to be applied to — the shape a test builds. */
+/** Just enough of a blueprint to read a preference from — the shape a test builds. */
 const base = (extra: Partial<Blueprint> = {}): Blueprint => ({
   id: 'test-blueprint',
   title: 'Test',
@@ -34,65 +31,4 @@ describe('viable-common - the landing-gate preference', () => {
     expect(landingGatePreferenceOf({ experience: { landingGate: LandingGatePreference.Discourage } }))
       .toBe(LandingGatePreference.Discourage)
   })
-
-  test('each case weighs the gate: web and the AI kinds encourage, scalable allows, a game discourages', () => {
-    const preferences = Object.fromEntries(Object.values(BlueprintCase).map(id =>
-      [id, landingGatePreferenceOf(applyBlueprintCase(base(), id))]))
-
-    expect(preferences).toEqual({
-      [BlueprintCase.Web]: LandingGatePreference.Encourage,
-      [BlueprintCase.Scalable]: LandingGatePreference.Allow,
-      [BlueprintCase.AiPipeline]: LandingGatePreference.Encourage,
-      [BlueprintCase.AiAgent]: LandingGatePreference.Encourage,
-      [BlueprintCase.Game]: LandingGatePreference.Discourage,
-    })
-  })
-
-  test('a case overrides the base layer key by key, and no case leaves a blueprint without one', () => {
-    const allowing = base({ experience: { landingGate: LandingGatePreference.Allow } })
-
-    expect(landingGatePreferenceOf(applyBlueprintCase(allowing, BlueprintCase.Game)))
-      .toBe(LandingGatePreference.Discourage)
-    expect(applyBlueprintCase(base(), undefined).experience).toBeUndefined()
-    expect(Object.isFrozen(applyBlueprintCase(base(), BlueprintCase.Web).experience)).toBe(true)
-  })
-})
-
-describe('viable-common - the landing-gate skill in the cases', () => {
-  const gatePersonas = [
-    ViablePersona.BusinessAnalyst, ViablePersona.UxDesigner, ViablePersona.LayoutArchitect,
-    ViablePersona.ComponentArchitect, ViablePersona.UiViewCoder, ViablePersona.UiNavCoder,
-  ]
-
-  test('reaches the analyst and the frontend personas of every encouraging case, and nobody else', () => {
-    for (const id of [BlueprintCase.Web, BlueprintCase.AiPipeline, BlueprintCase.AiAgent]) {
-      const cased = applyBlueprintCase(base(), id)
-      for (const persona of gatePersonas) {
-        expect(personaSkillsOf(cased, persona), `${id} → ${persona}`).toContain(ViableSkill.LandingGate)
-      }
-      expect(personaSkillsOf(cased, ViablePersona.ApiCoder)).not.toContain(ViableSkill.LandingGate)
-    }
-    for (const id of [BlueprintCase.Scalable, BlueprintCase.Game]) {
-      const cased = applyBlueprintCase(base(), id)
-      for (const persona of gatePersonas) {
-        expect(personaSkillsOf(cased, persona), `${id} → ${persona}`).not.toContain(ViableSkill.LandingGate)
-      }
-    }
-  })
-
-  test('is merged with what a case and the base already give a persona, never in place of it', () => {
-    const agent = applyBlueprintCase(base(), BlueprintCase.AiAgent)
-
-    expect(personaSkillsOf(agent, ViablePersona.BusinessAnalyst)).toEqual([
-      ViableSkill.MainFlowFocus, ViableSkill.AgenticChoice, ViableSkill.LandingGate,
-    ])
-    expect(personaSkillsOf(agent, ViablePersona.UxDesigner))
-      .toEqual([ViableSkill.AgenticChoice, ViableSkill.LandingGate])
-    expect(personaSkillsOf(agent, ViablePersona.WorkerCoder)).toEqual([
-      ViableSkill.AgenticChoice, ViableSkill.TargetLlm, ViableSkill.LibrariesAi,
-      ViableSkill.TargetAgentTools,
-    ])
-    expect(BLUEPRINT_CASES[BlueprintCase.AiPipeline].patch.packages?.personaSkills?.[ViablePersona.BusinessAnalyst])
-      .toEqual([ViableSkill.AgenticChoice, ViableSkill.LandingGate])
-  })
 })

package/tests/connect-errors.spec.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test'
 import { ResilientError } from '@owlmeans/error'
-import { ConnectOutOfCredits } from '../src/connect/errors.js'
+import { ConnectConsentRequired, ConnectOutOfCredits } from '../src/connect/errors.js'
 
 describe('@owlmeans/viable-common — ConnectOutOfCredits', () => {
   test('carries its fields fresh, and survives a marshal/unmarshal round trip', () => {
@@ -20,3 +20,33 @@ describe('@owlmeans/viable-common — ConnectOutOfCredits', () => {
     }))
   })
 })
+
+describe('@owlmeans/viable-common — ConnectConsentRequired', () => {
+  const url = 'https://vib-stage.owlmeans.org/account/billing?consent=1&from=mcp:story'
+  const deadline = new Date('2026-10-09T00:00:00.000Z')
+
+  test('packs gate, deadline and URL, and survives a marshal/unmarshal round trip', () => {
+    const fresh = new ConnectConsentRequired(ConnectConsentRequired.encode('story', url, deadline))
+
+    expect(fresh.message).toBe(`viable-connect:consent-required:story:${deadline.getTime()}:${encodeURIComponent(url)}`)
+    expect(fresh.gate).toBe('story')
+    expect(fresh.deadline?.toISOString()).toBe(deadline.toISOString())
+    expect(fresh.consentUrl).toBe(url)
+    expect((fresh.constructor as { httpStatus?: number }).httpStatus).toBe(428)
+
+    const restored = ResilientError.ensure(fresh.marshal())
+
+    expect(restored).toBeInstanceOf(ConnectConsentRequired)
+    expect(restored).toEqual(expect.objectContaining({ gate: 'story', consentUrl: url }))
+    expect((restored as ConnectConsentRequired).deadline?.toISOString()).toBe(deadline.toISOString())
+  })
+
+  test('an unknown deadline travels as 0 and reads back as absent', () => {
+    const fresh = new ConnectConsentRequired(ConnectConsentRequired.encode('create', url))
+
+    expect(fresh.message).toContain(':create:0:')
+    expect(fresh.deadline).toBeUndefined()
+    expect(fresh.consentUrl).toBe(url)
+    expect((ResilientError.ensure(fresh.marshal()) as ConnectConsentRequired).deadline).toBeUndefined()
+  })
+})

package/tests/error-status.spec.ts

@@ -18,6 +18,7 @@ const DECLARED: Record<string, number | undefined> = {
   LocalSlotUnsupported: 409,
   ConnectOpRefused: 422,
   ConnectOutOfCredits: 402,
+  ConnectConsentRequired: 428,
   ConnectOpTimeout: undefined,
   ProjectResourceError: undefined,
   ProjectNotFound: 404,
@@ -40,7 +41,7 @@ describe('viable-common refusals — declared HTTP statuses', () => {
     expect(classes.map(([name]) => name).sort()).toEqual(Object.keys(DECLARED).sort())
   })
 
-  test('balance 402, an absent target 404, a conflicting state 409, refused content 422; faults nothing', () => {
+  test('balance 402, an absent target 404, a conflicting state 409, refused content 422, a consent only a person gives 428; faults nothing', () => {
     for (const [name, Class] of classes) {
       expect([name, statusOf(new Class('x'))]).toEqual([name, DECLARED[name]])
     }
@@ -55,5 +56,9 @@ describe('viable-common refusals — declared HTTP statuses', () => {
       new connect.ConnectOutOfCredits(connect.ConnectOutOfCredits.encode('story', 1, 0, 'https://x.test')).marshal()
     )
     expect([statusOf(credits), (credits as connect.ConnectOutOfCredits).gate]).toEqual([402, 'story'])
+    const consent = ResilientError.ensure(
+      new connect.ConnectConsentRequired(connect.ConnectConsentRequired.encode('story', 'https://x.test/?consent=1')).marshal()
+    )
+    expect([statusOf(consent), (consent as connect.ConnectConsentRequired).consentUrl]).toEqual([428, 'https://x.test/?consent=1'])
   })
 })

package/tests/intent.spec.ts

@@ -0,0 +1,121 @@
+import { describe, expect, test } from 'bun:test'
+import Ajv from 'ajv'
+import addFormats from 'ajv-formats'
+import { DISPATCHER } from '@owlmeans/auth'
+import { HOME } from '@owlmeans/context'
+import { aliasOf, protocols } from '@owlmeans/entrypoint'
+import { makeFlowModel } from '@owlmeans/flow'
+import { AppType } from '@owlmeans/context'
+import { RouteMethod } from '@owlmeans/route'
+import {
+  INTENT_PAYLOAD_REF, INTENT_PROMPT_MAX, INTENT_TTL_SECONDS, IntentExpired, IntentFlowStep,
+  IntentPickupBodySchema, IntentStashBodySchema, IntentThrottled, intent, intentFlow, makeIntentProtocols,
+} from '../src/intent/index.js'
+
+const ajv = new Ajv({ allErrors: true, strict: false })
+addFormats(ajv)
+
+// The platform mints references with `createIdOfLength(24)` (Base58); mirrored here so the spec
+// needs no dependency beyond the package's own.
+const BASE58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
+const createIdOfLength = (length: number): string =>
+  Array.from({ length }, () => BASE58[Math.floor(Math.random() * BASE58.length)]).join('')
+
+describe('@owlmeans/viable-common — intent-first hand-off', () => {
+  const tree = makeIntentProtocols()
+
+  test('declares one guest base, two guest routes and a landing screen — no guard, no gate, no service', () => {
+    expect(tree.base.alias).toBe(intent.base)
+    expect(tree.stash.alias).toBe(intent.stash)
+    expect(tree.pickup.alias).toBe(intent.pickup)
+    expect(tree.landing.alias).toBe(intent.landing)
+    expect(new Set(protocols(tree).map(protocol => protocol.alias)).size).toBe(4)
+    for (const declaration of [tree.base, tree.stash, tree.pickup, tree.landing]) {
+      expect(declaration.guards ?? []).toEqual([])
+      expect(declaration.gate).toBeUndefined()
+      expect(declaration.route.route.service).toBeUndefined()
+    }
+    expect(tree.stash.route.route.path).toBe('/')
+    expect(tree.stash.route.route.method).toBe(RouteMethod.POST)
+    expect(tree.pickup.route.route.path).toBe('/pickup')
+    expect(tree.landing.route.route.path).toBe('/start')
+    expect(tree.landing.route.route.type).toBe(AppType.Frontend)
+    expect(aliasOf(tree.stash)).toBe(intent.stash)
+  })
+
+  test('a stash needs a non-empty bounded prompt AND the confirmation, and nothing else', () => {
+    const validate = ajv.compile(IntentStashBodySchema)
+    expect(validate({ prompt: 'A booking app', consent: true })).toBe(true)
+    expect(validate({ prompt: 'A booking app' })).toBe(false)
+    expect(validate({ prompt: 'A booking app', consent: false })).toBe(false)
+    expect(validate({ prompt: '', consent: true })).toBe(false)
+    expect(validate({ prompt: 'x'.repeat(INTENT_PROMPT_MAX), consent: true })).toBe(true)
+    expect(validate({ prompt: 'x'.repeat(INTENT_PROMPT_MAX + 1), consent: true })).toBe(false)
+    expect(validate({ prompt: 'A booking app', consent: true, extra: 1 })).toBe(false)
+  })
+
+  test('a pickup reference is exactly what createIdOfLength(24) makes, and nothing that could be a cache key trick', () => {
+    const validate = ajv.compile(IntentPickupBodySchema)
+    for (let i = 0; i < 50; i++) {
+      expect(validate({ ref: createIdOfLength(24) })).toBe(true)
+    }
+    expect(validate({ ref: 'short' })).toBe(false)
+    expect(validate({ ref: `${createIdOfLength(23)}:` })).toBe(false)
+    expect(validate({ ref: `intent:${createIdOfLength(17)}` })).toBe(false)
+    expect(validate({ ref: `${createIdOfLength(23)}*` })).toBe(false)
+    expect(validate({ ref: `${createIdOfLength(23)}0` })).toBe(false)
+    expect(validate({ ref: createIdOfLength(24), extra: 1 })).toBe(false)
+  })
+
+  test('the site half: compose → handoff lands on the platform screen with the reference as payload', async () => {
+    const ref = createIdOfLength(24)
+    const model = await makeFlowModel(intentFlow)
+    expect(model.state().step).toBe(IntentFlowStep.Compose)
+
+    model.transit('handoff', true, { [INTENT_PAYLOAD_REF]: ref })
+
+    expect(model.state().step).toBe(IntentFlowStep.Land)
+    expect(model.step().module).toBe(intent.landing)
+    expect(model.payload()).toEqual({ [INTENT_PAYLOAD_REF]: ref })
+  })
+
+  test('the landing half, signed in: enter(land) → review resolves to HOME', async () => {
+    const model = await makeFlowModel(intentFlow)
+    model.enter(IntentFlowStep.Land).updatePayload({ [INTENT_PAYLOAD_REF]: createIdOfLength(24) })
+    expect(model.next().step).toBe(IntentFlowStep.Review)
+
+    model.transit('review', true)
+    expect(model.step().module).toBe(HOME)
+  })
+
+  test('the landing half, signed out: sign-in is explicit, and from sign-in the way forward is HOME (what suspendFlow persists)', async () => {
+    const model = await makeFlowModel(intentFlow)
+    model.enter(IntentFlowStep.Land).updatePayload({ [INTENT_PAYLOAD_REF]: createIdOfLength(24) })
+
+    // `next()` must never pick the sign-in edge on its own.
+    expect(model.transitions(true).map(t => t.transition)).toEqual(['sign-in'])
+    expect(model.next().transition).toBe('review')
+
+    model.transit('sign-in', true)
+    expect(model.step().module).toBe(DISPATCHER)
+    // `suspendFlow` stores `model.step(model.next().step).module` — the home screen.
+    const forward = model.next()
+    expect(forward.step).toBe(IntentFlowStep.Review)
+    expect(model.step(forward.step).module).toBe(HOME)
+  })
+
+  test('the serialized token round-trips the reference (the site never sends it, but the model must survive it)', async () => {
+    const ref = createIdOfLength(24)
+    const model = await makeFlowModel(intentFlow)
+    const token = model.transit('handoff', true, { [INTENT_PAYLOAD_REF]: ref })
+    expect(typeof token).toBe('string')
+    expect(token.length).toBeGreaterThan(0)
+  })
+
+  test('the errors answer the statuses the wire depends on', () => {
+    expect((IntentExpired as unknown as { httpStatus: number }).httpStatus).toBe(404)
+    expect((IntentThrottled as unknown as { httpStatus: number }).httpStatus).toBe(429)
+    expect(new IntentExpired().message).toContain('expired')
+    expect(INTENT_TTL_SECONDS).toBe(120)
+  })
+})