@owlmeans/viable-common 0.0.33 → 0.0.34

package/src/intent/types.ts

@@ -0,0 +1,45 @@
+import type { ResourceRecord } from '@owlmeans/resource'
+
+/** What the public site sends: the prompt and the person's confirmation of its processing. */
+export interface IntentStashBody {
+  prompt: string
+  /** Always `true` — the site's checkbox; a request without it is refused by the schema. */
+  consent: true
+}
+
+/** The reference the platform answers with, and the moment its record expires. */
+export interface IntentStashResult {
+  ref: string
+  /** Epoch milliseconds. */
+  expiresAt: number
+}
+
+export interface IntentPickupBody {
+  ref: string
+}
+
+export interface IntentPickupResult {
+  prompt: string
+}
+
+/**
+ * The prompt as it waits in the visitor's browser between pickup and the decision on the home
+ * screen. `expiresAt` is checked on read — browser storage has no TTL of its own.
+ */
+export interface IntentDraft extends ResourceRecord {
+  id: string
+  /** The reference it was picked up with; a reload of the landing reuses the draft of that ref. */
+  ref: string
+  prompt: string
+  expiresAt: number
+}
+
+/**
+ * Options of {@link makeIntentProtocols}.
+ */
+export interface IntentProtocolOptions {
+  /** Path prefix of the guest API; defaults to `/public/intent`. */
+  path?: string
+  /** Path of the landing screen; defaults to `/start`. */
+  landing?: string
+}

package/src/skills/consts.ts

@@ -85,115 +85,3 @@ export enum ViableSkill {
   LibrariesAi = 'libraries-ai',
   LibrariesGame = 'libraries-game',
 }
-
-/**
- * Sort weights. Skills render in this order inside the cached block, so the sequence is
- * part of the cache key — reordering them invalidates every prefix at once. Grouped in
- * tens to leave room for a consumer's own skills between them.
- */
-export const SKILL_ORDER: Record<ViableSkill, number> = {
-  [ViableSkill.OutputSourceOnly]: 10,
-  [ViableSkill.OutputTextOnly]: 10,
-  [ViableSkill.ScopeDiscipline]: 15,
-  [ViableSkill.MainFlowFocus]: 12,
-  [ViableSkill.NonTypescriptOutput]: 18,
-  [ViableSkill.TsStyle]: 20,
-  [ViableSkill.TsImports]: 30,
-  [ViableSkill.ReactComponents]: 40,
-  [ViableSkill.OwlMeansEntrypoints]: 41,
-  [ViableSkill.OwlMeansNav]: 42,
-  [ViableSkill.PermissionModel]: 43,
-  [ViableSkill.ShadcnUi]: 44,
-  [ViableSkill.OwlmeansState]: 50,
-  [ViableSkill.FormFeedback]: 51,
-  [ViableSkill.StoreAccess]: 52,
-  [ViableSkill.ViewModelNaming]: 55,
-  // After the frontend rules it builds on (entrypoints, nav, shadcn, form feedback, the store), and
-  // before the backend block — it is only ever carried by analysis and frontend personas.
-  [ViableSkill.LandingGate]: 56,
-  // Analysis and frontend read it the same way LandingGate is read — after the frontend rules it
-  // references (nav, shadcn) — and a backend coder reads it as a server-side check, so it sits
-  // just ahead of the backend block for either audience.
-  [ViableSkill.MarketingConsent]: 57,
-  [ViableSkill.ResourceLayer]: 60,
-  [ViableSkill.ResourceResults]: 62,
-  [ViableSkill.ResourceMigrations]: 64,
-  [ViableSkill.OwlMeansServer]: 70,
-  [ViableSkill.OwlmeansContext]: 65,
-  [ViableSkill.OwlMeansServices]: 66,
-  [ViableSkill.FixerHeuristics]: 75,
-  [ViableSkill.ProjectLayout]: 5,
-  [ViableSkill.AgentTooling]: 8,
-  [ViableSkill.QueueDiscipline]: 67,
-  [ViableSkill.WorkerJobs]: 68,
-  [ViableSkill.TargetAgents]: 69,
-  [ViableSkill.AgenticChoice]: 71,
-  [ViableSkill.TargetLlm]: 72,
-  [ViableSkill.TargetAgentTools]: 73,
-  [ViableSkill.GameDesign]: 45,
-  [ViableSkill.GameScene]: 46,
-  [ViableSkill.GameUi]: 47,
-  [ViableSkill.GameNetworking]: 48,
-  [ViableSkill.LayoutDefinition]: 80,
-  [ViableSkill.ScreenDefinition]: 82,
-  [ViableSkill.LibrariesCommon]: 90,
-  [ViableSkill.LibrariesUiState]: 90,
-  [ViableSkill.LibrariesUi]: 90,
-  [ViableSkill.LibrariesBackend]: 90,
-  [ViableSkill.LibrariesAi]: 90,
-  [ViableSkill.LibrariesGame]: 90,
-}
-
-/**
- * The catalogue entries whose subject a PUBLISHED `@owlmeans` package already documents.
- *
- * The catalogue and `agent-meta/skills/*` state the same contract twice — the P1 duplication —
- * and the duplication is not symmetric: a package skill is versioned with the package and reaches
- * a prompt through `owlmeansPackagesPlugin` whenever the request names that package, while a
- * catalogue entry is a constant here that has to be edited by hand every time the framework moves.
- *
- * Naming the overlap is what makes it a DATA decision instead of a code one. A blueprint lists
- * which of these its prompts carry, and a persona's skills are filtered against that list — so
- * dropping one is a line in a blueprint, and restoring it is the same line. Everything NOT in this
- * set is viable's own (output discipline, scope, the view-model convention, the fixer heuristics,
- * where files live) and always loads, because no published package documents it.
- *
- * The default blueprint currently lists every one of them: the reduction is a real change to what
- * a coder is told, and it is measured against a green end-to-end baseline rather than guessed.
- */
-export const FRAMEWORK_OWNED_SKILLS: ViableSkill[] = [
-  ViableSkill.ResourceLayer,
-  ViableSkill.ResourceResults,
-  ViableSkill.ResourceMigrations,
-  ViableSkill.OwlmeansContext,
-  ViableSkill.OwlMeansServices,
-  ViableSkill.OwlMeansServer,
-  ViableSkill.OwlMeansEntrypoints,
-  ViableSkill.OwlMeansNav,
-  ViableSkill.PermissionModel,
-  ViableSkill.OwlmeansState,
-  ViableSkill.StoreAccess,
-  ViableSkill.ShadcnUi,
-  ViableSkill.ReactComponents,
-  ViableSkill.FormFeedback,
-]
-
-const FRAMEWORK_OWNED = new Set<ViableSkill>(FRAMEWORK_OWNED_SKILLS)
-
-/**
- * Filter a persona's skills against what a blueprint asks for.
- *
- * A skill nobody owns always survives. A framework-owned one survives only while the blueprint
- * lists it — so a blueprint built on another persistence layer stops teaching the Postgres
- * resource contract without anybody editing a persona, and a blueprint that lists nothing at all
- * (the shape a test builds) is read as "everything", because an empty allow-list almost always
- * means "not stated" rather than "none".
- */
-export const skillsForBlueprint = (
-  skills: ViableSkill[], allowed?: ViableSkill[]
-): ViableSkill[] => {
-  if (allowed == null || allowed.length === 0) return skills
-  const permitted = new Set(allowed)
-
-  return skills.filter(skill => !FRAMEWORK_OWNED.has(skill) || permitted.has(skill))
-}

package/src/skills/index.ts

@@ -1,4 +1,3 @@
 
 export * from './consts.js'
-export * from './catalogue.js'
 export * from './roles.js'

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/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)
+  })
+})