@owlmeans/viable-common 0.0.4

package/src/blueprint/case.ts

@@ -0,0 +1,272 @@
+import { SubProject } from '../slot/consts.js'
+import { ViableSkill } from '../skills/consts.js'
+import { ViablePersona } from '../skills/roles.js'
+import { aiLibraryList, gameLibraryList } from '../skills/catalogue.js'
+import type { BlueprintPatch } from './types.js'
+
+/**
+ * WHICH KIND of product is being built on a blueprint.
+ *
+ * A blueprint says what the STACK is — the language, the framework, the topology, the seeds. A
+ * case says what is being built ON it, and that is a different question with different consumers:
+ * the analyst framing the brief, the architect deciding whether a story needs a queue, the coder
+ * choosing which packages it may import.
+ *
+ * Deliberately NOT a second blueprint. Everything a case has to say is already a blueprint field,
+ * so a case is a PATCH and the resolution order stays base → case → per-run overrides. That is
+ * also why adding one is a data change: nothing reads `BlueprintCase` except the table below and
+ * the prompt that classifies a project into it.
+ */
+export enum BlueprintCase {
+  /** A web application whose every feature fits inside a request. No queue, no worker, no agents. */
+  Web = 'web',
+  /** A web application with work that genuinely belongs off the request path. */
+  Scalable = 'scalable',
+  /** The product's value comes from ordered, deterministic model-driven steps. */
+  AiPipeline = 'ai-pipeline',
+  /** The product's value comes from an agent that decides its own path through tools. */
+  AiAgent = 'ai-agent',
+  /** A browser game: a three.js scene with an ordinary React interface over it. */
+  Game = 'game',
+}
+
+/**
+ * How a game is played, which decides who owns its state.
+ *
+ * Recorded beside the case rather than folded into it, because it changes nothing about the
+ * dependencies and everything about where the logic goes. `OnlineTurn` is the default for
+ * anything multiplayer unless the brief plainly asks for live play — it is the shape that
+ * actually builds, and it needs no socket, no tick loop and no reconciliation.
+ */
+export enum GameKind {
+  Casual = 'casual',
+  OnlineTurn = 'online-turn',
+  OnlineLive = 'online-live',
+}
+
+export interface BlueprintCaseDefinition {
+  id: BlueprintCase
+  title: string
+  /**
+   * What this case is FOR, as the classifier prompt reads it.
+   *
+   * A pure constant, like every skill body: it lands in a cached prompt region, and one
+   * interpolated byte invalidates the prefix for every project classified after it.
+   */
+  when: string
+  /** Applied between the base blueprint and the run's own overrides. A case is nothing else. */
+  patch: BlueprintPatch
+}
+
+/** What every AI case installs. The langchain peers are declared here, at ONE range. */
+const AI_DEPS = {
+  [SubProject.Backend]: {
+    '@owlmeans/llm': '^0.1.18-rc.13',
+    '@owlmeans/agent': '^0.1.18-rc.16',
+    '@langchain/core': '^1.2.9',
+    '@langchain/anthropic': '^1.5.8',
+    '@langchain/openai': '^1.5.10',
+    '@langchain/langgraph': '^1.4.13',
+    '@langchain/langgraph-checkpoint': '^1.1.5',
+  },
+}
+
+/** The library allow-list a backend persona gets once the AI packages are installed. */
+const AI_LIBRARIES = {
+  [SubProject.Backend]: aiLibraryList,
+  [SubProject.Api]: aiLibraryList,
+  [SubProject.Worker]: aiLibraryList,
+}
+
+/** Skills every AI case adds on top of the blueprint's own. */
+const AI_SKILLS = [
+  ViableSkill.AgenticChoice,
+  ViableSkill.TargetLlm,
+  ViableSkill.LibrariesAi,
+]
+
+/**
+ * What the analysis stage is told about a product whose value is a model.
+ *
+ * The pairing rule is the load-bearing one: an agent holds no permissions and owns no screen, so
+ * a story that is the AGENT's work is invisible unless a human story starts it and watches it.
+ */
+/**
+ * What the API side is told once a project may have a queue.
+ *
+ * The endpoint that starts slow work is the PRODUCER, and it is generated by a persona that
+ * otherwise has no reason to know a broker exists. Its job alias is declared before it runs
+ * (`runtime-declare`), so by the time this coder writes the handler there is something to enqueue
+ * onto — and this is what tells it to, instead of doing the work inline behind a request the user
+ * is waiting on.
+ */
+const PRODUCER_PERSONA_SKILLS = {
+  [ViablePersona.ApiArchitect]: [ViableSkill.QueueDiscipline, ViableSkill.WorkerJobs],
+  [ViablePersona.ApiCoder]: [ViableSkill.WorkerJobs],
+}
+
+const AI_PERSONA_SKILLS = {
+  ...PRODUCER_PERSONA_SKILLS,
+  [ViablePersona.BusinessAnalyst]: [ViableSkill.AgenticChoice],
+  [ViablePersona.UxDesigner]: [ViableSkill.AgenticChoice],
+  [ViablePersona.RuntimeArchitect]: [ViableSkill.AgenticChoice, ViableSkill.TargetLlm],
+  [ViablePersona.WorkerCoder]: [
+    ViableSkill.AgenticChoice, ViableSkill.TargetLlm, ViableSkill.LibrariesAi,
+  ],
+}
+
+const GAME_PERSONA_SKILLS = {
+  [ViablePersona.BusinessAnalyst]: [ViableSkill.GameDesign],
+  [ViablePersona.UxDesigner]: [ViableSkill.GameDesign, ViableSkill.GameUi],
+  [ViablePersona.VisualDesigner]: [ViableSkill.GameUi],
+  [ViablePersona.ComponentArchitect]: [ViableSkill.GameScene, ViableSkill.GameUi],
+  [ViablePersona.LayoutArchitect]: [ViableSkill.GameScene, ViableSkill.GameUi],
+  [ViablePersona.UiViewCoder]: [
+    ViableSkill.GameScene, ViableSkill.GameUi, ViableSkill.LibrariesGame,
+  ],
+  [ViablePersona.RuntimeArchitect]: [ViableSkill.GameNetworking],
+  [ViablePersona.WorkerCoder]: [ViableSkill.GameNetworking],
+  [ViablePersona.ApiArchitect]: [ViableSkill.GameNetworking],
+  [ViablePersona.ApiCoder]: [ViableSkill.GameNetworking],
+}
+
+/**
+ * The cases the platform ships.
+ *
+ * Read as a table: the left column is what a prompt has to look like, the right column is what
+ * that costs the generated application. Nothing here turns a capability on without also
+ * installing what makes it real — a blueprint that promises `agents` over a manifest with no
+ * `@owlmeans/agent` in it produces a story that reports success and a library that will not
+ * compile.
+ */
+export const BLUEPRINT_CASES: Record<BlueprintCase, BlueprintCaseDefinition> = {
+  [BlueprintCase.Web]: {
+    id: BlueprintCase.Web,
+    title: 'Web application',
+    when: `
+Everything the product does fits inside a request: forms, lists, records, search, reports a
+person waits a second for. Nothing has to survive the tab closing, nothing calls a slow third
+party, nothing walks an unbounded set, nothing is scheduled. Most products are this.
+`.trim(),
+    patch: {
+      packages: {
+        capabilities: { postgres: true, kv: false, queue: false, worker: false, agents: false, validation: true },
+      },
+    },
+  },
+
+  [BlueprintCase.Scalable]: {
+    id: BlueprintCase.Scalable,
+    title: 'Web application with background work',
+    when: `
+Like a web application, except that some named part of it genuinely cannot run inside a request:
+it walks every row a user owns, talks to a slow or rate-limited third party, is scheduled or
+repeated, must survive the tab closing, or must be retried without the user doing anything.
+Choose this only when you can NAME that part; "it might get slow" is not it.
+
+NOT this when the slow part is a MODEL. Background work whose content comes out of a language
+model is one of the two AI kinds below, and choosing this one for it leaves the application unable
+to call a model at all.
+`.trim(),
+    patch: {
+      packages: {
+        capabilities: { postgres: true, kv: true, queue: true, worker: true, agents: false, validation: true },
+        personaSkills: PRODUCER_PERSONA_SKILLS,
+      },
+    },
+  },
+
+  [BlueprintCase.AiPipeline]: {
+    id: BlueprintCase.AiPipeline,
+    title: 'AI pipeline',
+    when: `
+The product's value comes from a language model, and the work it does is a KNOWN sequence:
+transcribe then summarise then file; extract then validate then store; draft then check then send.
+You can name the steps before it runs. The application decides the order; the model performs each
+step.
+
+Any product whose OUTPUT is written by a model is this kind or the one below — never a plain web
+application, and never merely a scalable one.
+`.trim(),
+    patch: {
+      packages: {
+        capabilities: { postgres: true, kv: true, queue: true, worker: true, agents: true, validation: true },
+        deps: AI_DEPS,
+        libraries: AI_LIBRARIES,
+        skills: AI_SKILLS,
+        personaSkills: AI_PERSONA_SKILLS,
+      },
+    },
+  },
+
+  [BlueprintCase.AiAgent]: {
+    id: BlueprintCase.AiAgent,
+    title: 'AI agent',
+    when: `
+The product's value comes from a model that decides its own path: how many steps the work takes
+cannot be predicted, and which tool to reach for next is a judgement rather than a rule anyone
+could write down. Choose this over an AI pipeline only when the order genuinely cannot be fixed
+in advance.
+`.trim(),
+    patch: {
+      packages: {
+        capabilities: { postgres: true, kv: true, queue: true, worker: true, agents: true, validation: true },
+        deps: {
+          [SubProject.Backend]: {
+            ...AI_DEPS[SubProject.Backend],
+            '@owlmeans/agent-skills': '^0.1.18-rc.12',
+          },
+        },
+        libraries: AI_LIBRARIES,
+        skills: [...AI_SKILLS, ViableSkill.TargetAgentTools],
+        personaSkills: {
+          ...AI_PERSONA_SKILLS,
+          [ViablePersona.WorkerCoder]: [
+            ...AI_PERSONA_SKILLS[ViablePersona.WorkerCoder], ViableSkill.TargetAgentTools,
+          ],
+        },
+      },
+    },
+  },
+
+  [BlueprintCase.Game]: {
+    id: BlueprintCase.Game,
+    title: 'Browser game',
+    when: `
+The person asked for a GAME, in those words or unmistakably — something played rather than used,
+with a loop, a score or a win condition. Never infer this from "gamified", "playful", "fun" or a
+leaderboard attached to an ordinary product. If the prompt does not plainly ask for a game, this
+is not it.
+`.trim(),
+    patch: {
+      packages: {
+        capabilities: { postgres: true, kv: true, queue: true, worker: true, agents: false, validation: true },
+        deps: {
+          [SubProject.Web]: { three: '^0.186.0', '@types/three': '^0.185.4' },
+        },
+        libraries: { [SubProject.Web]: gameLibraryList, 'ui-state': gameLibraryList },
+        skills: [ViableSkill.GameScene, ViableSkill.GameUi, ViableSkill.LibrariesGame],
+        personaSkills: { ...PRODUCER_PERSONA_SKILLS, ...GAME_PERSONA_SKILLS },
+      },
+    },
+  },
+}
+
+/**
+ * The case a reference names, or `undefined`.
+ *
+ * Total over anything: an unknown name, a name from a deploy this one does not have, and an
+ * absent one all read the same way — no patch, which is the base blueprint. That is the only
+ * answer that cannot take a capability away from a project that already has it.
+ */
+export const blueprintCaseOf = (name?: string): BlueprintCaseDefinition | undefined =>
+  name == null ? undefined : (BLUEPRINT_CASES as Record<string, BlueprintCaseDefinition>)[name]
+
+/** Every case the platform ships, in the order a classifier should weigh them. */
+export const BLUEPRINT_CASE_ORDER: BlueprintCase[] = [
+  BlueprintCase.Web,
+  BlueprintCase.Scalable,
+  BlueprintCase.AiPipeline,
+  BlueprintCase.AiAgent,
+  BlueprintCase.Game,
+]

package/src/blueprint/consts.ts

@@ -0,0 +1,11 @@
+/**
+ * The blueprint the platform ships and every project uses until something says otherwise.
+ *
+ * A string rather than an enum: a blueprint may be registered by a consumer, and an enum would
+ * make the platform's own list the closed set of everything that can exist — which is the shape
+ * this whole abstraction was introduced to remove.
+ */
+export const DEFAULT_BLUEPRINT_ID = 'owlmeans-fullstack-ts'
+
+/** Recorded on a project so a later run knows which blueprint drew it. */
+export const BLUEPRINT_META_KEY = 'blueprint'

package/src/blueprint/index.ts

@@ -0,0 +1,6 @@
+export * from './types.js'
+
+export * from './consts.js'
+export * from './case.js'
+export * from './schemas.js'
+export * from './resolve.js'

package/src/blueprint/resolve.ts

@@ -0,0 +1,133 @@
+import type { ViablePersona } from '../skills/roles.js'
+import type { ViableSkill } from '../skills/consts.js'
+import { blueprintCaseOf } from './case.js'
+import type { Blueprint, BlueprintPatch } from './types.js'
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  value != null && typeof value === 'object' && !Array.isArray(value)
+
+/**
+ * Merge one layer's override over a resolved value.
+ *
+ * Objects merge key by key; ARRAYS REPLACE. That asymmetry is deliberate and is the difference
+ * between an override and an addition: a blueprint that narrows a library allow-list to three
+ * entries means those three, and a concatenating merge would hand the coder back the very imports
+ * the override existed to forbid. A layer that wants to add spreads the base itself.
+ */
+export const mergeBlueprintValue = <T>(base: T, patch: unknown): T => {
+  if (patch === undefined) return base
+  if (!isPlainObject(base) || !isPlainObject(patch)) return patch as T
+
+  const out: Record<string, unknown> = { ...base }
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === undefined) continue
+    out[key] = mergeBlueprintValue(out[key], value)
+  }
+
+  return out as T
+}
+
+/**
+ * Apply an override patch to a blueprint, layer by layer.
+ *
+ * Frozen on the way out — shallowly at each layer, which is enough to make the accidental
+ * `blueprint.packages.capabilities.worker = true` a visible failure rather than a change every
+ * later helper silently inherits.
+ */
+export const applyBlueprintPatch = (base: Blueprint, patch?: BlueprintPatch): Blueprint => {
+  if (patch == null) return base
+
+  const merged = mergeBlueprintValue(
+    base as unknown as Record<string, unknown>, patch
+  ) as unknown as Blueprint
+
+  return freezeBlueprint(merged)
+}
+
+export const freezeBlueprint = (blueprint: Blueprint): Blueprint => Object.freeze({
+  ...blueprint,
+  technology: Object.freeze({ ...blueprint.technology }),
+  stack: Object.freeze({ ...blueprint.stack }),
+  template: Object.freeze({ ...blueprint.template }),
+  createApp: Object.freeze({ ...blueprint.createApp }),
+  packages: Object.freeze({
+    ...blueprint.packages,
+    capabilities: Object.freeze({ ...blueprint.packages.capabilities }),
+  }),
+})
+
+/** Every skill the blueprint asks for, stack first, deduped, order preserved. */
+export const blueprintSkills = (blueprint: Blueprint): Blueprint['stack']['skills'] =>
+  [...new Set([...blueprint.stack.skills, ...blueprint.packages.skills])]
+
+
+const union = <T>(base: readonly T[] = [], extra: readonly T[] = []): T[] =>
+  [...new Set([...base, ...extra])]
+
+/**
+ * Apply a CASE to a blueprint — which kind of product is being built on this stack.
+ *
+ * A case is an ordinary {@link BlueprintPatch} and follows every rule an override does, with two
+ * deliberate exceptions: `skills` and `personaSkills` are UNIONED with the base rather than
+ * replacing it.
+ *
+ * The asymmetry is the difference between the two things a patch can be. An override is written
+ * by somebody looking at the resolved value and narrowing it — "these three libraries and no
+ * others" — and a concatenating merge would hand back the very imports it existed to forbid. A
+ * case is written once, in a table, by somebody who cannot see the blueprint it will be applied
+ * to; it says what this KIND of product needs IN ADDITION, and replacing there would silently
+ * drop every rule the stack itself established. A case that genuinely needs to take a skill away
+ * does it by narrowing a capability, which is what stops the prompt being asked at all.
+ *
+ * Unknown, absent and unregistered case names all resolve to the blueprint unchanged. A project
+ * records the case it was drawn with, that record outlives the deploy that knew the name, and
+ * "built against the stack as it stands" is a far better answer than a project that cannot open.
+ */
+export const applyBlueprintCase = (base: Blueprint, name?: string): Blueprint => {
+  const cased = blueprintCaseOf(name)
+  if (cased == null) return base
+
+  const merged = applyBlueprintPatch(base, cased.patch)
+  const patch = cased.patch
+
+  const personaSkills = patch.packages?.personaSkills
+  const stackSkills = patch.stack?.skills as ViableSkill[] | undefined
+  const packageSkills = patch.packages?.skills as ViableSkill[] | undefined
+
+  return freezeBlueprint({
+    ...merged,
+    stack: { ...merged.stack, skills: union(base.stack.skills, stackSkills) },
+    packages: {
+      ...merged.packages,
+      skills: union(base.packages.skills, packageSkills),
+      ...(personaSkills != null || base.packages.personaSkills != null
+        ? {
+          personaSkills: mergePersonaSkills(base.packages.personaSkills, personaSkills),
+        }
+        : {}),
+    },
+  })
+}
+
+const mergePersonaSkills = (
+  base?: Partial<Record<ViablePersona, ViableSkill[]>>,
+  extra?: Partial<Record<ViablePersona, ViableSkill[]>>,
+): Partial<Record<ViablePersona, ViableSkill[]>> => {
+  const out: Partial<Record<ViablePersona, ViableSkill[]>> = { ...base }
+  for (const [persona, skills] of Object.entries(extra ?? {})) {
+    const key = persona as ViablePersona
+    out[key] = union(out[key], skills as ViableSkill[])
+  }
+
+  return out
+}
+
+/**
+ * The skills ONE persona gets from the blueprint, beyond its own.
+ *
+ * Total, and empty for every persona a blueprint says nothing about — which is every one of them
+ * on the blueprint the platform ships. `withPersona` unions this into the policy it composes.
+ */
+export const personaSkillsOf = (
+  blueprint: Blueprint, persona: ViablePersona
+): ViableSkill[] => blueprint.packages.personaSkills?.[persona] ?? []

package/src/blueprint/schemas.ts

@@ -0,0 +1,44 @@
+import { BlueprintCase, GameKind } from './case.js'
+
+/**
+ * What kind of product a prompt describes.
+ *
+ * A schema rather than a free answer because the value is a KEY: it is written onto the project
+ * record, resolved into a blueprint patch on every run afterwards, and decides which dependencies
+ * the tree is staged with. A model that answered "an AI-powered agent app" in prose would leave
+ * the caller matching strings, and a miss there is silent — the project simply builds as the
+ * default and nobody can say why.
+ */
+export interface BlueprintCaseChoice {
+  case: BlueprintCase
+  /** Only meaningful for the game case; ignored everywhere else. */
+  gameKind?: GameKind
+  /** One sentence, from the prompt. Recorded so a later run can disagree with it. */
+  rationale: string
+}
+
+export const BlueprintCaseChoiceSchema = {
+  type: 'object',
+  title: 'BlueprintCaseChoice',
+  description: 'Which kind of application the described product is',
+  properties: {
+    case: {
+      type: 'string',
+      enum: Object.values(BlueprintCase),
+      description: 'The least capable kind that can deliver what was asked for.',
+    },
+    gameKind: {
+      type: 'string',
+      enum: Object.values(GameKind),
+      description: 'Only when the case is `game`. `casual` for one player in one browser, '
+        + '`online-turn` for players acting one after another, `online-live` only when the brief '
+        + 'plainly asks for players acting at the same moment.',
+    },
+    rationale: {
+      type: 'string',
+      description: 'One sentence naming what in the prompt decided it.',
+    },
+  },
+  required: ['case', 'rationale'],
+  additionalProperties: false,
+} as const

package/src/blueprint/types.ts

@@ -0,0 +1,204 @@
+import type { SubProject } from '../slot/consts.js'
+import type { ViableSkill } from '../skills/consts.js'
+import type { ViablePersona } from '../skills/roles.js'
+import type { TopologyDescriptor } from '../topology/types.js'
+
+/**
+ * A BLUEPRINT is everything that decides what kind of project the pipeline is building — the
+ * language, the framework, the scaffolder, the seed files and the dependencies — as one named,
+ * layered value carried on an execution.
+ *
+ * Before it, each of those was a constant somewhere: one template directory, one hardwired set of
+ * five package names, one `VIABLE_SKILLS` catalogue, one `Libraries*` allow-list per area. Nothing
+ * was wrong with any of them individually; what was wrong is that they could not be ANSWERED — a
+ * helper could not ask "which stack am I generating for", because there was only ever one.
+ *
+ * Deliberately NOT called a preset: `presets/` in the agent library already means the LLM
+ * model/provider configurations, and the two are asked at different moments about different
+ * things.
+ */
+export interface Blueprint {
+  id: string
+  title: string
+  technology: TechnologyLayer
+  stack: StackLayer
+  template: TemplateLayer
+  createApp: CreateAppLayer
+  packages: PackagesLayer
+}
+
+/**
+ * The layers, lowest first. A higher layer's value replaces the same key from a lower one.
+ *
+ * The ordering is the point: `technology` overrides everything, because a change of language
+ * invalidates every template, prompt and package below it. Nothing today has more than one
+ * technology — the ladder exists so that adding one is a data change.
+ */
+export enum BlueprintLayer {
+  Technology = 'technology',
+  Stack = 'stack',
+  Template = 'template',
+  CreateApp = 'create-app',
+  Packages = 'packages',
+}
+
+export const BLUEPRINT_LAYER_ORDER: BlueprintLayer[] = [
+  BlueprintLayer.Technology,
+  BlueprintLayer.Stack,
+  BlueprintLayer.Template,
+  BlueprintLayer.CreateApp,
+  BlueprintLayer.Packages,
+]
+
+/** Language and toolchain. Overrides everything below it. */
+export interface TechnologyLayer {
+  id: string
+  language: string
+  runtime: string
+  /** Extensions a source file may carry, most specific first. Used by the location ladder. */
+  extensions: string[]
+  /** What a package's manifest must declare, per package kind. */
+  buildScripts: Record<string, string>
+  packageManager: string
+}
+
+/** Framework family — what the generated code is written AGAINST. */
+export interface StackLayer {
+  id: string
+  framework: string
+  /** The arrangement a new project of this stack is created with. */
+  topology: TopologyDescriptor
+  /** The skills every prompt of this stack carries, before any per-helper persona. */
+  skills: ViableSkill[]
+}
+
+/**
+ * The seed: what is laid over the scaffolder's output, and what is then patched.
+ *
+ * `overlay` is a REFERENCE, never a path — the host resolves it, because the same blueprint is
+ * read in an agent container, in a test and (eventually) from a published package, and a path
+ * baked in here would be right in exactly one of them.
+ */
+export interface TemplateLayer {
+  id: string
+  overlay: string
+  /**
+   * Paths the scaffolder writes that this overlay SUPERSEDES — deleted after the overlay lands.
+   *
+   * Not tidiness. The two seeds are both complete, opinionated projects, and where they disagree
+   * the loser's file does not become inert: it stays in the workspace, is compiled by `tsc`, and
+   * imports packages the winner's manifest never declared. The scaffolder's Vite entry, its
+   * `vite.config.ts` and its shell layout each name a dependency or an export the overlay's own
+   * wiring does not have, and every one of them fails the type check of a project that is
+   * otherwise perfectly correct.
+   *
+   * A directory takes its whole subtree. A path that is not there is a no-op, because the two
+   * seeds move independently and an overlay must not break when the scaffolder stops shipping
+   * something it used to supersede.
+   */
+  remove?: string[]
+  /** Deterministic patches applied after the overlay, in order. */
+  patches: BlueprintPatchSpec[]
+  /** Overlay subtrees that belong to one role only — the per-package half of a template. */
+  perRole?: Partial<Record<SubProject, string>>
+}
+
+export interface BlueprintPatchSpec {
+  /** Target path, relative to the project root. */
+  path: string
+  kind: BlueprintPatchKind
+}
+
+export enum BlueprintPatchKind {
+  /** Deep-merge a JSON document — the manifests, the tsconfigs. */
+  JsonMerge = 'json-merge',
+  /** Rewrite the `<head>` of an HTML document from the project's identity. */
+  HtmlHead = 'html-head',
+  /** Write a document composed from the project's identity. */
+  Compose = 'compose',
+}
+
+/** Which scaffolder runs first, and how. */
+export interface CreateAppLayer {
+  id: string
+  /** The npm name, for the record. The template itself is always resolved as DATA. */
+  package: string
+  /** Scaffold the shell without the example/demo code. Always true for a generated target. */
+  bare: boolean
+  /** A reference the host resolves to the scaffolder's template directory. */
+  template: string
+}
+
+/**
+ * The dependency choices — and therefore the prompts and skills those choices imply.
+ *
+ * This is the layer that makes "postgres or mongo" a blueprint question rather than a hardwired
+ * catalogue. `capabilities` is what a design stage gates on; `libraries` is what a coder prompt is
+ * allowed to import; `skills` is what gets loaded on top of the stack's.
+ */
+export interface PackagesLayer {
+  id: string
+  capabilities: BlueprintCapabilities
+  /** Per-topic allow-lists, rendered verbatim into coder prompts. */
+  libraries: Record<string, string[]>
+  skills: ViableSkill[]
+  /**
+   * Skills added to ONE persona, rather than to every prompt of the blueprint.
+   *
+   * The additive twin of {@link skillsForBlueprint}, which subtracts. `skills` above is what is
+   * true of the whole stack; this is what is true of one performer — the analyst who has to know
+   * that a game brief is a core loop rather than a numbered flow, the architect who has to know
+   * when a tool loop is warranted. Without it a case could only change what a CODER is told, and
+   * a case changes the product analysis first.
+   */
+  personaSkills?: Partial<Record<ViablePersona, ViableSkill[]>>
+  /** Extra dependencies a role's manifest carries, beyond what the overlay ships. */
+  deps?: Partial<Record<SubProject, Record<string, string>>>
+}
+
+/**
+ * What a target of this blueprint is ABLE to do — read by the design stage before it decides
+ * whether a story needs any of it.
+ *
+ * A capability being on never means a story uses it. It means the question may be asked.
+ */
+export interface BlueprintCapabilities {
+  /** Relational persistence — the default resource kind. */
+  postgres: boolean
+  /** A pod-local key/value store: TTL, locks, counters, fan-out. */
+  kv: boolean
+  /** A broker, and therefore the possibility of work off the request path. */
+  queue: boolean
+  /** A separate process consuming that broker. */
+  worker: boolean
+  /** LLM agents and pipelines generated INTO the target. */
+  agents: boolean
+  /** Request-body validation from generated AJV schemas. */
+  validation: boolean
+}
+
+/** A partial override of a blueprint, deep-merged over the resolved value. */
+export type BlueprintPatch = {
+  [K in keyof Blueprint]?: Blueprint[K] extends string ? Blueprint[K] : Partial<Blueprint[K]>
+}
+
+/**
+ * What an EXECUTION carries — an id and an override patch, never the resolved blueprint.
+ *
+ * An execution state is serialized into a pipeline run row at every step boundary, and that row
+ * holds keys, never artifacts. A resolved blueprint is an artifact: it embeds a whole topology, a
+ * patch list and two skill sets, and it is reconstructible from these two fields at any time.
+ */
+export interface BlueprintRef {
+  id: string
+  /**
+   * WHICH KIND of product is being built on that blueprint — the case.
+   *
+   * A key like the id beside it, resolved into a patch on demand, so a run row still holds no
+   * artifact and a case the platform has since corrected reaches a resumed run. Absent applies no
+   * patch at all: every project created before cases existed keeps exactly the blueprint it had,
+   * which is the only reading that cannot silently take a capability away from a live project.
+   */
+  case?: string
+  overrides?: BlueprintPatch
+}