@vectoriox/iox-ui 5.52.0 → 5.54.0

package/generation-core/index.d.ts

@@ -3025,5 +3025,153 @@ interface BuildStepFacts {
 }
 declare function buildStepFacts(plan: SitePlan, actions?: Readonly<Record<string, `${ContentTypeAction}`>>): BuildStepFacts;
 
-export { ACTIVE_BUILD_STATUSES, BAR_ITEMS_MAX, BAR_ITEMS_MIN, BASELINE_ROLES, BUILD_STEPS, BaselineRole, BindScope, BuildNoticeCode, BuildStep, CardBindTarget, ComposeError, ComposeIssueCode, ContentTypeAction, CreatedKind, DANGLING_LINK_CODES, DEFAULT_PHONE_MENU_BREAKPOINT, ENTRANCE_EASING, ENTRANCE_ORIGIN_LOOK, ENTRANCE_TRIGGER, EntrancePart, FACT_KEYS, GlobalSlot, KeptReason, NAV_PART_LABELS, NAV_SHAPE_COPY, NEUTRAL_STYLE_PROPS, NODE_BASELINES, NavPagesSource, NavRole, NavShape, NavShapeError, PRICING_PATTERN, PUBLISH_BLOCKING_PLACEHOLDERS, PageDataKind, PathIssueCollector, PatternDirective, PatternGlobalPosition, PatternOpens, PatternPlaceholder, PatternRecipe, PhoneMenuBreakpoint, PlaceholderKind, PlanDataSourceMode, PlanDataSourceType, PreflightRefusalCode, RelativeOp, SAMPLE_IMAGE_REF, SITE_FACT_LABELS, SITE_HEADER_PATTERN, SITE_PATTERNS, SITE_PLAN_VERSION, SITE_TEMPLATES, SPEC_SITE_FACTS, SPEC_SITE_LIBRARY, SPEC_SITE_PATTERNS, SPEC_SITE_PLAN_SHAPE, SPEC_SITE_TEMPLATES, STUDIO_TEMPLATE, SiteBuildKind, SiteBuildStatus, SitePlanError, SitePlanIssueCode, SitePlanSourceKind, SiteTemplateError, SiteTemplateId, StepState, addBarItem, altSourceScopes, assertStyleSlots, assertValidSitePlan, barIconForRoute, blocksPublish, buildKeys, buildStepFacts, builtHomePageId, composeNavHeader, composeSection, composeSite, createSerializedNode, describePlanData, entranceAction, entranceInteraction, failedBuildStep, findNavRoot, isActiveBuild, isNonEmptyString, isPlainObject, moveBarItem, navPages, navShapeBreakpoint, navShapeOf, nextSourceOf, nodeBindPaths, parseSampleImageRef, pathAt, patternById, patternNeedsBinding, patternNodes, patternOptionalParts, patternScopes, patternSlots, patternTakesBinding, phoneMenuPages, planFromTemplate, planNavShape, releasedLayoutDefaults, removeBarItem, requiredShapeKeys, routeParams, sampleImageRef, sectionEntrances, setStyleProps, shapeKeys, siteNavPages, staggerDelay, validateSitePlan, walkSerialized };
-export type { AddBarItemResult, BarItemsEditResult, BuildNotice, BuildStepError, BuildStepFacts, BuildStepRecord, CmsDataSourcePlan, ComposeContext, ComposeIssue, ComposedDataSource, ComposedItem, ComposedNavHeader, ComposedPage, ComposedPlaceholder, ComposedRoute, ComposedSection, ComposedSite, ContentFieldPlan, ContentSeedPlan, ContentTypePlan, CreateNodeOptions, CreatedRecord, DataSourcePlan, EntranceAction, EntranceInteraction, EntranceSpec, FactKey, NavHeaderInput, NavHeaderOptions, NavPage, NavShapeOptions, NavShapeResult, NodeBaseline, PageData, PageDataLine, PagePlan, PageSectionPlan, PathIssue, PatternNode, PlainObject, PreflightRefusal, RelativeDataSourcePlan, SectionEntrances, SectionInput, SectionOptions, SerializedBinding, SerializedNode, SerializedResponsive, ShapeEntry, ShapeIssueCodes, SiteBuildRun, SiteBusiness, SitePageRef, SitePattern, SitePlan, SitePlanIssue, SitePlanSource, SitePlanValidation, SiteTemplate, TemplatePlanInput, UndoKept, UndoPreview, UndoRecord };
+/**
+ * The AI pipeline's WIRE vocabulary (AI plan §3c, §3n, M0): what iox-cms's `ai` API answers and what every client
+ * of it reads — the steps a model works on, who pays (IOX credits or the studio's own key), a model of the vetted
+ * list with its price per token class, the one cost → credits rule (1 credit = 1 US cent of what the AI cost, D4),
+ * the refusals (board 11) and a generation's stages. ONE definition: iox-cms meters and refuses with it, the
+ * Settings ▸ AI screen and the wizard show it. Pure types, enums and helpers; no transport, no prices typed here.
+ * The step and capability spellings are the control plane's (`GET /instances/me/entitlements`, AI plan "M0 control
+ * plane — the instance-route contract") — the platform has ONE spelling of each.
+ */
+declare enum AiProviderId {
+    Anthropic = "anthropic",
+    OpenRouter = "openrouter"
+}
+/** Who pays: the platform's credits, or the studio's own provider key (metered for display, never charged). */
+declare enum AiKeyMode {
+    Platform = "platform",
+    Own = "own"
+}
+/** The steps a model works on (board 9's rows), in screen order. */
+declare enum AiStep {
+    ReadMessage = "analysis",
+    PlanSite = "plan",
+    ChangePlan = "planEdit",
+    MakePictures = "image",
+    NameStructures = "scanNaming"
+}
+declare const AI_STEPS: ReadonlyArray<AiStep>;
+/** What a model must be able to do for a step to run on it. */
+declare enum AiCapability {
+    StructuredOutput = "structuredOutputs",
+    ImageInput = "imageInput",
+    ImageOutput = "imageOutput"
+}
+declare const AI_STEP_NEEDS: Readonly<Record<AiStep, ReadonlyArray<AiCapability>>>;
+/** Tokens a typical use of a step reads and writes (plan §3d "Where credits go") — what a shown estimate is made of. */
+declare const AI_STEP_TYPICAL_TOKENS: Readonly<Record<AiStep, AiTokenCounts>>;
+/** Tokens by the class a provider prices them in. */
+interface AiTokenCounts {
+    input: number;
+    output: number;
+    /** Written to the prompt cache (priced above input). */
+    cacheWrite: number;
+    /** Read from the prompt cache (priced well below input). */
+    cacheRead: number;
+}
+/** US dollars per million tokens, per class. A class without a price is priced as input. */
+interface AiTokenPrice {
+    input: number;
+    output: number;
+    cacheWrite?: number;
+    cacheRead?: number;
+}
+/** A model of the vetted list (served by the control plane with the entitlements, §3n) — its price travels with it. */
+interface AiModelEntry {
+    id: string;
+    provider: `${AiProviderId}`;
+    label: string;
+    /** The steps it may be chosen for. */
+    steps: ReadonlyArray<`${AiStep}`>;
+    /** The steps it is the default for (board 9's "recommended"). */
+    recommendedFor?: ReadonlyArray<`${AiStep}`>;
+    /** The steps it runs when the default is not available (the control plane's `fallbackModel`). */
+    fallbackFor?: ReadonlyArray<`${AiStep}`>;
+    capabilities: ReadonlyArray<`${AiCapability}`>;
+    /** Null when the provider reports each call's cost itself and the list carries no price. */
+    price: AiTokenPrice | null;
+    /** Kept so old ledger rows still name it; never offered, and a studio's choice of it falls back to the default. */
+    retired?: boolean;
+}
+/** 1 credit = 1 US cent of what the AI actually cost (decision D4). */
+declare const CREDITS_PER_USD = 100;
+declare const NO_TOKENS: Readonly<AiTokenCounts>;
+/** What `tokens` cost at `price`, in US dollars. */
+declare function costUsd(tokens: AiTokenCounts, price: AiTokenPrice): number;
+/** Dollars → credits, kept to a millionth of a credit (a short read costs a fraction of one). */
+declare function creditsOfUsd(usd: number): number;
+/** The credits a typical use of `step` costs on a model of `price` — never typed, always computed (§3d). */
+declare function estimateStepCredits(step: AiStep, price: AiTokenPrice, tokens?: AiTokenCounts): number;
+/** Can `model` do `step`? The step's needs against the model's capabilities. */
+declare function modelCanDo(model: Pick<AiModelEntry, 'capabilities'>, step: AiStep): boolean;
+/** Why AI did not run (board 11). The server refuses with these BEFORE any model call. */
+declare enum AiRefusalCode {
+    NotInPlan = "ai.notInPlan",
+    OutOfCredits = "ai.outOfCredits",
+    CapReached = "ai.capReached",
+    NotConnected = "ai.notConnected",
+    KeyInvalid = "ai.keyInvalid",
+    PlanUnknown = "ai.planUnknown"
+}
+/** The HTTP status each refusal answers with (board 11). */
+declare const AI_REFUSAL_STATUS: Readonly<Record<AiRefusalCode, number>>;
+/** What a refusal offers next. */
+declare enum AiNextKind {
+    /** Ask IOX (a prefilled email to the operator, until a plan can be bought — D2). */
+    Contact = "contact",
+    /** Open Settings ▸ AI. */
+    Settings = "settings",
+    /** Try again later, or with less. */
+    Retry = "retry"
+}
+declare const AI_REFUSAL_NEXT: Readonly<Record<AiRefusalCode, AiNextKind>>;
+interface AiRefusal {
+    code: AiRefusalCode;
+    planName?: string;
+    /** Credits left this period (platform credits only). */
+    remaining?: number;
+    /** What the refused call would have cost, about. */
+    estimate?: number;
+    next: {
+        kind: AiNextKind;
+        href?: string;
+    };
+}
+/** The studio's AI credits this period (the connector's meter, E4). `allowance: null` = unlimited. */
+interface AiMeter {
+    used: number;
+    allowance: number | null;
+    remaining: number | null;
+    periodStart: string;
+    periodEnd: string;
+}
+/** A generation's stages (§3d). The runner works while `task` is set; otherwise the owner has the next move. */
+declare enum AiGenerationStage {
+    Reading = "reading",
+    Analysis = "analysis",
+    Design = "design",
+    Plan = "plan",
+    Build = "build",
+    Done = "done",
+    Failed = "failed",
+    Cancelled = "cancelled"
+}
+/** The stages nothing advances any more. */
+declare const FINAL_GENERATION_STAGES: ReadonlyArray<AiGenerationStage>;
+/** How one model call ended — a ledger row's status. */
+declare enum AiCallStatus {
+    /** Written before the call: a reservation at the estimate until the call settles. */
+    Started = "started",
+    Ok = "ok",
+    /** The answer came back and the shared validator refused it (with a path). */
+    Invalid = "invalid",
+    /** The model declined (a provider refusal) — charged what the provider reports. */
+    Refused = "refused",
+    Error = "error",
+    /** The process died during the call: charged at the estimate, since what it cost was never reported. */
+    Interrupted = "interrupted"
+}
+
+export { ACTIVE_BUILD_STATUSES, AI_REFUSAL_NEXT, AI_REFUSAL_STATUS, AI_STEPS, AI_STEP_NEEDS, AI_STEP_TYPICAL_TOKENS, AiCallStatus, AiCapability, AiGenerationStage, AiKeyMode, AiNextKind, AiProviderId, AiRefusalCode, AiStep, BAR_ITEMS_MAX, BAR_ITEMS_MIN, BASELINE_ROLES, BUILD_STEPS, BaselineRole, BindScope, BuildNoticeCode, BuildStep, CREDITS_PER_USD, CardBindTarget, ComposeError, ComposeIssueCode, ContentTypeAction, CreatedKind, DANGLING_LINK_CODES, DEFAULT_PHONE_MENU_BREAKPOINT, ENTRANCE_EASING, ENTRANCE_ORIGIN_LOOK, ENTRANCE_TRIGGER, EntrancePart, FACT_KEYS, FINAL_GENERATION_STAGES, GlobalSlot, KeptReason, NAV_PART_LABELS, NAV_SHAPE_COPY, NEUTRAL_STYLE_PROPS, NODE_BASELINES, NO_TOKENS, NavPagesSource, NavRole, NavShape, NavShapeError, PRICING_PATTERN, PUBLISH_BLOCKING_PLACEHOLDERS, PageDataKind, PathIssueCollector, PatternDirective, PatternGlobalPosition, PatternOpens, PatternPlaceholder, PatternRecipe, PhoneMenuBreakpoint, PlaceholderKind, PlanDataSourceMode, PlanDataSourceType, PreflightRefusalCode, RelativeOp, SAMPLE_IMAGE_REF, SITE_FACT_LABELS, SITE_HEADER_PATTERN, SITE_PATTERNS, SITE_PLAN_VERSION, SITE_TEMPLATES, SPEC_SITE_FACTS, SPEC_SITE_LIBRARY, SPEC_SITE_PATTERNS, SPEC_SITE_PLAN_SHAPE, SPEC_SITE_TEMPLATES, STUDIO_TEMPLATE, SiteBuildKind, SiteBuildStatus, SitePlanError, SitePlanIssueCode, SitePlanSourceKind, SiteTemplateError, SiteTemplateId, StepState, addBarItem, altSourceScopes, assertStyleSlots, assertValidSitePlan, barIconForRoute, blocksPublish, buildKeys, buildStepFacts, builtHomePageId, composeNavHeader, composeSection, composeSite, costUsd, createSerializedNode, creditsOfUsd, describePlanData, entranceAction, entranceInteraction, estimateStepCredits, failedBuildStep, findNavRoot, isActiveBuild, isNonEmptyString, isPlainObject, modelCanDo, moveBarItem, navPages, navShapeBreakpoint, navShapeOf, nextSourceOf, nodeBindPaths, parseSampleImageRef, pathAt, patternById, patternNeedsBinding, patternNodes, patternOptionalParts, patternScopes, patternSlots, patternTakesBinding, phoneMenuPages, planFromTemplate, planNavShape, releasedLayoutDefaults, removeBarItem, requiredShapeKeys, routeParams, sampleImageRef, sectionEntrances, setStyleProps, shapeKeys, siteNavPages, staggerDelay, validateSitePlan, walkSerialized };
+export type { AddBarItemResult, AiMeter, AiModelEntry, AiRefusal, AiTokenCounts, AiTokenPrice, BarItemsEditResult, BuildNotice, BuildStepError, BuildStepFacts, BuildStepRecord, CmsDataSourcePlan, ComposeContext, ComposeIssue, ComposedDataSource, ComposedItem, ComposedNavHeader, ComposedPage, ComposedPlaceholder, ComposedRoute, ComposedSection, ComposedSite, ContentFieldPlan, ContentSeedPlan, ContentTypePlan, CreateNodeOptions, CreatedRecord, DataSourcePlan, EntranceAction, EntranceInteraction, EntranceSpec, FactKey, NavHeaderInput, NavHeaderOptions, NavPage, NavShapeOptions, NavShapeResult, NodeBaseline, PageData, PageDataLine, PagePlan, PageSectionPlan, PathIssue, PatternNode, PlainObject, PreflightRefusal, RelativeDataSourcePlan, SectionEntrances, SectionInput, SectionOptions, SerializedBinding, SerializedNode, SerializedResponsive, ShapeEntry, ShapeIssueCodes, SiteBuildRun, SiteBusiness, SitePageRef, SitePattern, SitePlan, SitePlanIssue, SitePlanSource, SitePlanValidation, SiteTemplate, TemplatePlanInput, UndoKept, UndoPreview, UndoRecord };

package/harness-core/index.d.ts

@@ -2572,6 +2572,21 @@ interface AnalysisContext {
 /** At most this many moods (the closed list a preset carries too). */
 declare const MAX_ANALYSIS_MOODS = 3;
 declare function validateSiteAnalysis(value: unknown, ctx: AnalysisContext): AnalysisValidation;
+/**
+ * The structured-output schema a model is given to write a `SiteAnalysis` (AI plan §3c/§3d, M0-5): built from the
+ * SAME shape table `validateSiteAnalysis` reads (keys, which are required, each key's explanation as its
+ * description) and the same closed lists (30 business types, needs, facts, moods, avoids) — so the shape the model
+ * is told about is the shape the gate refuses. Written to the strictest common subset of JSON Schema the providers'
+ * native strict modes accept (Anthropic `output_config.format`, OpenRouter `json_schema` + `strict`): every object
+ * closes with `additionalProperties: false`; no length, count or number bounds (the gate checks those). The
+ * schema is a hint the provider enforces; `validateSiteAnalysis` stays the gate.
+ */
+type JsonSchema = {
+    [key: string]: unknown;
+};
+/** The name a provider shows the format under (`json_schema.name`). */
+declare const SITE_ANALYSIS_SCHEMA_NAME = "site_analysis";
+declare function siteAnalysisJsonSchema(): JsonSchema;
 
 /**
  * What the PLAN prompt is given (AI plan rev 3 §3f "Retrieval, not the whole knowledge base"): the one matched
@@ -2658,5 +2673,5 @@ interface StructureChoice {
  */
 declare function structureFor(typeId: string | null | undefined): StructureChoice;
 
-export { ANIMATE_ADVICE_STEPS, AnalysisIssueCode, AnalysisLocale, AvoidCheck, BUSINESS_TYPES, BUSINESS_TYPE_IDS, BookingNeed, COPY_LENGTH_ORDER, CopyLength, HARNESS_SOURCE, LITTLE_MOVEMENT_AVOID, LITTLE_MOVEMENT_CAP, LintKind, MAX_ANALYSIS_MOODS, NEEDS, NEED_IDS, NeedSource, PresetFit, RANK_WEIGHTS, READ_ANIMATE, READ_WEIGHTS, RankReason, SPEC_ANALYSIS_SHAPE, SPEC_BUSINESS_TYPES, SPEC_HARNESS_EXAMPLES, SPEC_HARNESS_SOURCE, SPEC_NEEDS, SPEC_STRUCTURES, SPEC_USER_AVOIDS, STRUCTURES, StyleReadGround, StyleReadHeadings, StyleReadMotion, StyleReadSourceKind, USER_AVOID_IDS, VoiceFormality, VoicePerson, addressesIn, analysisPromptContext, businessTypeById, calmerChoice, inferNeeds, isLookRule, lintDesign, lookMatches, mapStyleRead, matchBusinessType, matchBusinessTypes, motionAdvice, motionFor, normalizeAddress, oklchHue, presetHasSerifHeadings, presetLook, presetReason, rankStylePresets, rankWithReferences, structureFor, userAvoidRule, validateSiteAnalysis, withoutAddress };
-export type { AnalysisContext, AnalysisIssue, AnalysisValidation, AvoidRule, BusinessType, BusinessTypeMatch, CheckRule, FactRead, GoodFit, LintFinding, LintSite, LookCondition, LookDesign, LookRule, MotionBasis, MotionInput, MotionStart, NeedDef, NeedId, PromptContext, PromptContextOptions, PromptSection, RankInput, RankedPreset, SiteAnalysis, SiteNeed, StructureChoice, StructureId, StyleHints, StyleRead, UserAvoidId };
+export { ANIMATE_ADVICE_STEPS, AnalysisIssueCode, AnalysisLocale, AvoidCheck, BUSINESS_TYPES, BUSINESS_TYPE_IDS, BookingNeed, COPY_LENGTH_ORDER, CopyLength, HARNESS_SOURCE, LITTLE_MOVEMENT_AVOID, LITTLE_MOVEMENT_CAP, LintKind, MAX_ANALYSIS_MOODS, NEEDS, NEED_IDS, NeedSource, PresetFit, RANK_WEIGHTS, READ_ANIMATE, READ_WEIGHTS, RankReason, SITE_ANALYSIS_SCHEMA_NAME, SPEC_ANALYSIS_SHAPE, SPEC_BUSINESS_TYPES, SPEC_HARNESS_EXAMPLES, SPEC_HARNESS_SOURCE, SPEC_NEEDS, SPEC_STRUCTURES, SPEC_USER_AVOIDS, STRUCTURES, StyleReadGround, StyleReadHeadings, StyleReadMotion, StyleReadSourceKind, USER_AVOID_IDS, VoiceFormality, VoicePerson, addressesIn, analysisPromptContext, businessTypeById, calmerChoice, inferNeeds, isLookRule, lintDesign, lookMatches, mapStyleRead, matchBusinessType, matchBusinessTypes, motionAdvice, motionFor, normalizeAddress, oklchHue, presetHasSerifHeadings, presetLook, presetReason, rankStylePresets, rankWithReferences, siteAnalysisJsonSchema, structureFor, userAvoidRule, validateSiteAnalysis, withoutAddress };
+export type { AnalysisContext, AnalysisIssue, AnalysisValidation, AvoidRule, BusinessType, BusinessTypeMatch, CheckRule, FactRead, GoodFit, JsonSchema, LintFinding, LintSite, LookCondition, LookDesign, LookRule, MotionBasis, MotionInput, MotionStart, NeedDef, NeedId, PromptContext, PromptContextOptions, PromptSection, RankInput, RankedPreset, SiteAnalysis, SiteNeed, StructureChoice, StructureId, StyleHints, StyleRead, UserAvoidId };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.52.0",
+  "version": "5.54.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/src/generation-core/ai-run.ts

@@ -0,0 +1,209 @@
+/**
+ * The AI pipeline's WIRE vocabulary (AI plan §3c, §3n, M0): what iox-cms's `ai` API answers and what every client
+ * of it reads — the steps a model works on, who pays (IOX credits or the studio's own key), a model of the vetted
+ * list with its price per token class, the one cost → credits rule (1 credit = 1 US cent of what the AI cost, D4),
+ * the refusals (board 11) and a generation's stages. ONE definition: iox-cms meters and refuses with it, the
+ * Settings ▸ AI screen and the wizard show it. Pure types, enums and helpers; no transport, no prices typed here.
+ * The step and capability spellings are the control plane's (`GET /instances/me/entitlements`, AI plan "M0 control
+ * plane — the instance-route contract") — the platform has ONE spelling of each.
+ */
+
+export enum AiProviderId {
+    Anthropic = 'anthropic',
+    OpenRouter = 'openrouter',
+}
+
+/** Who pays: the platform's credits, or the studio's own provider key (metered for display, never charged). */
+export enum AiKeyMode {
+    Platform = 'platform',
+    Own = 'own',
+}
+
+/** The steps a model works on (board 9's rows), in screen order. */
+export enum AiStep {
+    ReadMessage = 'analysis',
+    PlanSite = 'plan',
+    ChangePlan = 'planEdit',
+    MakePictures = 'image',
+    NameStructures = 'scanNaming',
+}
+
+export const AI_STEPS: ReadonlyArray<AiStep> = Object.values(AiStep);
+
+/** What a model must be able to do for a step to run on it. */
+export enum AiCapability {
+    StructuredOutput = 'structuredOutputs',
+    ImageInput = 'imageInput',
+    ImageOutput = 'imageOutput',
+}
+
+export const AI_STEP_NEEDS: Readonly<Record<AiStep, ReadonlyArray<AiCapability>>> = {
+    [AiStep.ReadMessage]: [AiCapability.StructuredOutput, AiCapability.ImageInput],
+    [AiStep.PlanSite]: [AiCapability.StructuredOutput],
+    [AiStep.ChangePlan]: [AiCapability.StructuredOutput],
+    [AiStep.MakePictures]: [AiCapability.ImageOutput],
+    [AiStep.NameStructures]: [AiCapability.StructuredOutput],
+};
+
+/** Tokens a typical use of a step reads and writes (plan §3d "Where credits go") — what a shown estimate is made of. */
+export const AI_STEP_TYPICAL_TOKENS: Readonly<Record<AiStep, AiTokenCounts>> = {
+    [AiStep.ReadMessage]: { input: 8_800, output: 1_500, cacheWrite: 0, cacheRead: 0 },
+    [AiStep.PlanSite]: { input: 12_000, output: 7_000, cacheWrite: 0, cacheRead: 0 },
+    [AiStep.ChangePlan]: { input: 6_000, output: 500, cacheWrite: 0, cacheRead: 0 },
+    [AiStep.MakePictures]: { input: 1_120, output: 0, cacheWrite: 0, cacheRead: 0 },
+    [AiStep.NameStructures]: { input: 80_000, output: 10_000, cacheWrite: 0, cacheRead: 0 },
+};
+
+/** Tokens by the class a provider prices them in. */
+export interface AiTokenCounts {
+    input: number;
+    output: number;
+    /** Written to the prompt cache (priced above input). */
+    cacheWrite: number;
+    /** Read from the prompt cache (priced well below input). */
+    cacheRead: number;
+}
+
+/** US dollars per million tokens, per class. A class without a price is priced as input. */
+export interface AiTokenPrice {
+    input: number;
+    output: number;
+    cacheWrite?: number;
+    cacheRead?: number;
+}
+
+/** A model of the vetted list (served by the control plane with the entitlements, §3n) — its price travels with it. */
+export interface AiModelEntry {
+    id: string;
+    provider: `${AiProviderId}`;
+    label: string;
+    /** The steps it may be chosen for. */
+    steps: ReadonlyArray<`${AiStep}`>;
+    /** The steps it is the default for (board 9's "recommended"). */
+    recommendedFor?: ReadonlyArray<`${AiStep}`>;
+    /** The steps it runs when the default is not available (the control plane's `fallbackModel`). */
+    fallbackFor?: ReadonlyArray<`${AiStep}`>;
+    capabilities: ReadonlyArray<`${AiCapability}`>;
+    /** Null when the provider reports each call's cost itself and the list carries no price. */
+    price: AiTokenPrice | null;
+    /** Kept so old ledger rows still name it; never offered, and a studio's choice of it falls back to the default. */
+    retired?: boolean;
+}
+
+/** 1 credit = 1 US cent of what the AI actually cost (decision D4). */
+export const CREDITS_PER_USD = 100;
+const TOKENS_PER_PRICE_UNIT = 1_000_000;
+const CREDIT_PRECISION = 1e6;
+
+export const NO_TOKENS: Readonly<AiTokenCounts> = Object.freeze({ input: 0, output: 0, cacheWrite: 0, cacheRead: 0 });
+
+/** What `tokens` cost at `price`, in US dollars. */
+export function costUsd(tokens: AiTokenCounts, price: AiTokenPrice): number {
+    const perToken = (perMillion: number | undefined, fallback: number) => (perMillion ?? fallback) / TOKENS_PER_PRICE_UNIT;
+    return tokens.input * perToken(price.input, 0)
+        + tokens.output * perToken(price.output, 0)
+        + tokens.cacheWrite * perToken(price.cacheWrite, price.input)
+        + tokens.cacheRead * perToken(price.cacheRead, price.input);
+}
+
+/** Dollars → credits, kept to a millionth of a credit (a short read costs a fraction of one). */
+export function creditsOfUsd(usd: number): number {
+    return Math.round(usd * CREDITS_PER_USD * CREDIT_PRECISION) / CREDIT_PRECISION;
+}
+
+/** The credits a typical use of `step` costs on a model of `price` — never typed, always computed (§3d). */
+export function estimateStepCredits(step: AiStep, price: AiTokenPrice, tokens: AiTokenCounts = AI_STEP_TYPICAL_TOKENS[step]): number {
+    return creditsOfUsd(costUsd(tokens, price));
+}
+
+/** Can `model` do `step`? The step's needs against the model's capabilities. */
+export function modelCanDo(model: Pick<AiModelEntry, 'capabilities'>, step: AiStep): boolean {
+    return AI_STEP_NEEDS[step].every(need => model.capabilities.includes(need));
+}
+
+/** Why AI did not run (board 11). The server refuses with these BEFORE any model call. */
+export enum AiRefusalCode {
+    NotInPlan = 'ai.notInPlan',
+    OutOfCredits = 'ai.outOfCredits',
+    CapReached = 'ai.capReached',
+    NotConnected = 'ai.notConnected',
+    KeyInvalid = 'ai.keyInvalid',
+    PlanUnknown = 'ai.planUnknown',
+}
+
+/** The HTTP status each refusal answers with (board 11). */
+export const AI_REFUSAL_STATUS: Readonly<Record<AiRefusalCode, number>> = {
+    [AiRefusalCode.NotInPlan]: 403,
+    [AiRefusalCode.OutOfCredits]: 402,
+    [AiRefusalCode.CapReached]: 402,
+    [AiRefusalCode.NotConnected]: 409,
+    [AiRefusalCode.KeyInvalid]: 409,
+    [AiRefusalCode.PlanUnknown]: 503,
+};
+
+/** What a refusal offers next. */
+export enum AiNextKind {
+    /** Ask IOX (a prefilled email to the operator, until a plan can be bought — D2). */
+    Contact = 'contact',
+    /** Open Settings ▸ AI. */
+    Settings = 'settings',
+    /** Try again later, or with less. */
+    Retry = 'retry',
+}
+
+export const AI_REFUSAL_NEXT: Readonly<Record<AiRefusalCode, AiNextKind>> = {
+    [AiRefusalCode.NotInPlan]: AiNextKind.Contact,
+    [AiRefusalCode.OutOfCredits]: AiNextKind.Contact,
+    [AiRefusalCode.CapReached]: AiNextKind.Retry,
+    [AiRefusalCode.NotConnected]: AiNextKind.Settings,
+    [AiRefusalCode.KeyInvalid]: AiNextKind.Settings,
+    [AiRefusalCode.PlanUnknown]: AiNextKind.Retry,
+};
+
+export interface AiRefusal {
+    code: AiRefusalCode;
+    planName?: string;
+    /** Credits left this period (platform credits only). */
+    remaining?: number;
+    /** What the refused call would have cost, about. */
+    estimate?: number;
+    next: { kind: AiNextKind; href?: string };
+}
+
+/** The studio's AI credits this period (the connector's meter, E4). `allowance: null` = unlimited. */
+export interface AiMeter {
+    used: number;
+    allowance: number | null;
+    remaining: number | null;
+    periodStart: string;
+    periodEnd: string;
+}
+
+/** A generation's stages (§3d). The runner works while `task` is set; otherwise the owner has the next move. */
+export enum AiGenerationStage {
+    Reading = 'reading',
+    Analysis = 'analysis',
+    Design = 'design',
+    Plan = 'plan',
+    Build = 'build',
+    Done = 'done',
+    Failed = 'failed',
+    Cancelled = 'cancelled',
+}
+
+/** The stages nothing advances any more. */
+export const FINAL_GENERATION_STAGES: ReadonlyArray<AiGenerationStage> = [AiGenerationStage.Done, AiGenerationStage.Failed, AiGenerationStage.Cancelled];
+
+/** How one model call ended — a ledger row's status. */
+export enum AiCallStatus {
+    /** Written before the call: a reservation at the estimate until the call settles. */
+    Started = 'started',
+    Ok = 'ok',
+    /** The answer came back and the shared validator refused it (with a path). */
+    Invalid = 'invalid',
+    /** The model declined (a provider refusal) — charged what the provider reports. */
+    Refused = 'refused',
+    Error = 'error',
+    /** The process died during the call: charged at the estimate, since what it cost was never reported. */
+    Interrupted = 'interrupted',
+}

package/src/generation-core/public-api.ts

@@ -24,3 +24,4 @@ export * from './nav-shape';
 export * from './entrances';
 export * from './plan-data';
 export * from './site-build-run';
+export * from './ai-run';

package/src/harness-core/site-analysis.ts

@@ -178,3 +178,73 @@ export function validateSiteAnalysis(value: unknown, ctx: AnalysisContext): Anal
 
     return { valid: c.issues.length === 0, issues: c.issues };
 }
+
+/**
+ * The structured-output schema a model is given to write a `SiteAnalysis` (AI plan §3c/§3d, M0-5): built from the
+ * SAME shape table `validateSiteAnalysis` reads (keys, which are required, each key's explanation as its
+ * description) and the same closed lists (30 business types, needs, facts, moods, avoids) — so the shape the model
+ * is told about is the shape the gate refuses. Written to the strictest common subset of JSON Schema the providers'
+ * native strict modes accept (Anthropic `output_config.format`, OpenRouter `json_schema` + `strict`): every object
+ * closes with `additionalProperties: false`; no length, count or number bounds (the gate checks those). The
+ * schema is a hint the provider enforces; `validateSiteAnalysis` stays the gate.
+ */
+
+export type JsonSchema = { [key: string]: unknown };
+
+/** The name a provider shows the format under (`json_schema.name`). */
+export const SITE_ANALYSIS_SCHEMA_NAME = 'site_analysis';
+
+const OPTIONAL_MARK = '?';
+
+const text = (): JsonSchema => ({ type: 'string' });
+const oneOf = (values: ReadonlyArray<string>): JsonSchema => ({ type: 'string', enum: [...values] });
+const listOf = (items: JsonSchema): JsonSchema => ({ type: 'array', items });
+
+/** The shape table's own words for a key — the description the model reads. */
+function describe(shape: string, key: string): string {
+    const entry = SHAPE[shape];
+    return String(entry[key] ?? entry[`${key}${OPTIONAL_MARK}`] ?? '');
+}
+
+/** An object of `shape`: exactly its keys, its required ones required, each described by the table. */
+function shaped(shape: string, properties: Record<string, JsonSchema>): JsonSchema {
+    return {
+        type: 'object',
+        properties: Object.fromEntries(Object.entries(properties).map(([key, schema]) => [key, { ...schema, description: describe(shape, key) }])),
+        required: requiredShapeKeys(SHAPE[shape]),
+        additionalProperties: false,
+    };
+}
+
+/** `{ [fact]: factRead }`: the closed fact keys, each optional — a fact the prompt does not state is left out. */
+function factsSchema(factRead: JsonSchema): JsonSchema {
+    return {
+        type: 'object',
+        properties: Object.fromEntries(FACT_KEYS.map(key => [key, factRead])),
+        required: [],
+        additionalProperties: false,
+        description: describe('analysis', 'facts'),
+    };
+}
+
+export function siteAnalysisJsonSchema(): JsonSchema {
+    const factRead = shaped('factRead', { value: text(), quote: text() });
+    return shaped('analysis', {
+        businessType: oneOf(BUSINESS_TYPE_IDS),
+        alternatives: listOf(oneOf(BUSINESS_TYPE_IDS)),
+        business: shaped('business', { name: text(), audience: text() }),
+        needs: listOf(shaped('need', { id: oneOf(NEED_IDS), from: oneOf(Object.values(NeedSource)), name: text() })),
+        facts: factsSchema(factRead),
+        missingFacts: listOf(oneOf(FACT_KEYS)),
+        voice: shaped('voice', {
+            tone: text(),
+            person: oneOf(Object.values(VoicePerson)),
+            formality: oneOf(Object.values(VoiceFormality)),
+            avoidWords: listOf(text()),
+        }),
+        moods: listOf(oneOf(MOOD_IDS)),
+        avoid: listOf(oneOf(USER_AVOID_IDS)),
+        hero: shaped('hero', { headline: text(), lead: text() }),
+        locale: oneOf(Object.values(AnalysisLocale)),
+    });
+}