create-ailk 0.1.0 → 0.2.0

package/templates/database/config/schema.prisma

@@ -0,0 +1,234 @@
+// config namespace — site-wide settings and customer configuration (ADR-0009).
+//
+// SiteSetting is the site-wide key-value config store. Generator + datasource
+// live in database/schema.prisma (the folder's single config file).
+//
+// The three site-config models (WorkspaceTheme / WorkspaceSiteIdentity /
+// WorkspaceSEO) are workspace-scoped: keyed on a plain `workspaceId String` with
+// NO cross-namespace @relation to auth/Workspace (a stable-ID per ADR-0009
+// invariant #1). Cross-namespace integrity + cascade are the service layer's
+// (ADR-0009 D3), delivered by the Phase 4 workspace-scoped write surface. Every
+// model here is fenced by the architecture.yaml tenant-scope forbidden-pattern.
+
+/// SiteSetting - Key-value settings for the customer site
+/// Use for: feature flags, custom config, cached Platform data
+model SiteSetting {
+  id        String   @id @default(dbgenerated("('siteset_'::text || (uuidv7())::text)")) @db.Text
+  key       String   @unique // "feature_flags", "cached_config", "custom_theme"
+  value     Json
+
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+
+  @@map("site_settings")
+}
+
+// ============================================================================
+// Workspace site config — workspace-scoped design-system persistence (#3641).
+//
+// Three tables, one per @working-theory/site-config schema. Each row stores the
+// Zod-validated JSON blob for a single workspace. Validation is enforced at the
+// API layer; the DB stores the already-validated blob in a Json column.
+//
+// Design decisions (site-config-reanchor-spec §3):
+//   - workspaceId is a plain String stable-ID — NO @relation to auth/Workspace
+//     (ADR-0009 invariant #1: no cross-namespace @relation).
+//   - One table per schema (not a polymorphic config table) — different update
+//     cadences + consumer access patterns.
+//   - Json column for the blob — schema evolves without a DB migration on change.
+//   - @unique(workspaceId) — one active record per workspace per config type.
+// ============================================================================
+
+/// WorkspaceTheme — per-workspace ThemeSchema blob (#3641)
+model WorkspaceTheme {
+  id          String   @id @default(dbgenerated("('theme_'::text || (uuidv7())::text)")) @db.Text
+  workspaceId String   @unique @map("workspace_id")
+  data        Json
+  createdAt   DateTime @default(now()) @map("created_at") @db.Timestamptz
+  updatedAt   DateTime @updatedAt @map("updated_at") @db.Timestamptz
+
+  @@map("workspace_themes")
+}
+
+/// WorkspaceSiteIdentity — per-workspace SiteIdentitySchema blob (#3641)
+model WorkspaceSiteIdentity {
+  id          String   @id @default(dbgenerated("('siteid_'::text || (uuidv7())::text)")) @db.Text
+  workspaceId String   @unique @map("workspace_id")
+  data        Json
+  createdAt   DateTime @default(now()) @map("created_at") @db.Timestamptz
+  updatedAt   DateTime @updatedAt @map("updated_at") @db.Timestamptz
+
+  @@map("workspace_site_identities")
+}
+
+/// WorkspaceSEO — per-workspace SEOSchema blob (#3641)
+model WorkspaceSEO {
+  id          String   @id @default(dbgenerated("('seo_'::text || (uuidv7())::text)")) @db.Text
+  workspaceId String   @unique @map("workspace_id")
+  data        Json
+  createdAt   DateTime @default(now()) @map("created_at") @db.Timestamptz
+  updatedAt   DateTime @updatedAt @map("updated_at") @db.Timestamptz
+
+  @@map("workspace_seos")
+}
+
+/// SiteListingConfig — per-SITE project-listings config blob (#5033).
+///
+/// The fourth site-config model, and the one keyed on `siteId` rather than
+/// `workspaceId`. `ProjectListing` is scoped by `siteId`, and its create path
+/// is anonymous (a public application form, no session) — at the moment a
+/// listing is created there is no workspace to resolve, so a tenant-guarded
+/// workspace config would be unreadable from the one place these values are
+/// needed. Otherwise identical to its three siblings above: `@unique` key,
+/// one Zod-validated JSON blob (`siteListingConfigSchema` in
+/// @working-theory/validation), validation at the API layer.
+///
+/// Carries the listing-window bounds and the featured switch — a site's own
+/// commercial terms, which is why they are here and not a constant in the
+/// published package. Never written from a request body; read server-side by
+/// the anonymous create handler.
+model SiteListingConfig {
+  id     String @id @default(dbgenerated("('sltcfg_'::text || (uuidv7())::text)")) @db.Text
+  siteId String @unique @map("site_id")
+
+  /// The site's PUBLIC site key (#5048 D2) — the addressing token an anonymous
+  /// application carries in place of a siteId, so the server resolves the site
+  /// rather than trusting a request body. Public by design: it ships in browser
+  /// JavaScript and in an agent's request, and grants nothing on its own.
+  ///
+  /// Nullable and @unique: a site that has not minted one is unreachable by key
+  /// and falls back to the single-tenant env path (AILK_LISTING_PUBLIC_KEY, see
+  /// apps/api/src/services/listing-config.ts), which is how the default
+  /// create-ailk scaffold works with no config row at all.
+  publicKey String? @unique @map("public_key")
+
+  data      Json
+  createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz
+  updatedAt DateTime @updatedAt @map("updated_at") @db.Timestamptz
+
+  @@map("site_listing_configs")
+}
+
+// ============================================================================
+// Usage-billing pricing/markup/model config (FEAT-047 P1.S2, #3710 — Epic
+// #3704). Per ADR 0009 D2 (roadmap §4), pricing/markup/model config lives in
+// `config`; balances/subscription/plan live in `auth` (see
+// database/auth/schema.prisma). organizationId is a plain String stable-id —
+// no @relation (ADR 0009 invariant 1). LlmModel.tier references ModelTier,
+// defined in database/content/schema.prisma (FEAT-047 P1.S1, #3709, spec
+// OQ-1) — an enum reference through the merged prismaSchemaFolder needs no
+// @relation, so this is not a cross-namespace FK; ModelTier is NOT
+// redefined here. Field roster ported from
+// docs/research/wt-billing-capture/schema.md.
+// ============================================================================
+
+/// BillingMode — org- vs individual-billed. Ported from the capture (schema.md
+/// § balance counters) for forward compatibility; no P1.S2 field consumes it
+/// yet (Organization's billing-mode projection is out of this spec's field
+/// roster — spec §2.1 item 1). Captured now so the enum name is stable when a
+/// later phase wires it.
+enum BillingMode {
+  INDIVIDUAL
+  ORGANIZATION
+}
+
+/// SubscriptionPaymentMode — how a Subscription is paid. Self-serve
+/// subscriptions default to CARD; Subscription.paymentMode is nullable
+/// (enterprise-only field, spec §5.3 — no business default invented).
+enum SubscriptionPaymentMode {
+  CARD
+  INVOICE
+}
+
+/// BillingCycle — MONTHLY vs YEARLY. Ported from the capture for forward
+/// compatibility; no P1.S2 field consumes it yet (Plan's Stripe price id is
+/// singular in this spec's field roster — a monthly/yearly price-id split is
+/// a future additive column, not invented here).
+enum BillingCycle {
+  MONTHLY
+  YEARLY
+}
+
+/// ContractType — how a Subscription's deal was made. Subscription.contractType
+/// is nullable (enterprise-only field — self-serve subscriptions leave it
+/// unset).
+enum ContractType {
+  SELF_SERVE
+  SALES_ASSISTED
+  ENTERPRISE
+}
+
+/// AiMarkupConfig — hierarchical per-org markup config: null provider+model =
+/// org default; null model = provider-wide; both set = model-specific
+/// (spec §2.1 item 5).
+model AiMarkupConfig {
+  id             String @id @default(dbgenerated("('markup_'::text || (uuidv7())::text)")) @db.Text
+  organizationId String @map("organization_id")
+  provider       String?
+  model          String?
+
+  markupPercent Decimal @map("markup_percent") @db.Decimal(5, 2)
+
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+
+  @@unique([organizationId, provider, model])
+  @@map("ai_markup_configs")
+}
+
+/// LlmModelPricing — per-token provider rates, time-versioned by
+/// effectiveFrom/effectiveTo (spec §2.1 item 6).
+model LlmModelPricing {
+  id       String @id @default(dbgenerated("('llmprc_'::text || (uuidv7())::text)")) @db.Text
+  provider String
+  model    String
+
+  inputPricePerMillion       Decimal  @map("input_price_per_million") @db.Decimal(10, 4)
+  outputPricePerMillion      Decimal  @map("output_price_per_million") @db.Decimal(10, 4)
+  cachedInputPricePerMillion Decimal? @map("cached_input_price_per_million") @db.Decimal(10, 4)
+
+  effectiveFrom DateTime  @map("effective_from")
+  effectiveTo   DateTime? @map("effective_to")
+
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+
+  @@unique([provider, model, effectiveFrom])
+  @@map("llm_model_pricing")
+}
+
+/// LlmModel — the active model catalog: tier, consumption weighting, context
+/// window (spec §2.1 item 7). provider+model is the natural key (not
+/// time-versioned, unlike LlmModelPricing — this is the current-state
+/// catalog row per model).
+model LlmModel {
+  id       String @id @default(dbgenerated("('llmmdl_'::text || (uuidv7())::text)")) @db.Text
+  provider String
+  model    String
+
+  tier                      ModelTier
+  consumptionMultiplier     Decimal   @default(1.0) @map("consumption_multiplier") @db.Decimal(5, 2)
+  chargeExtendedContextAt2x Boolean   @map("charge_extended_context_at_2x")
+  isAutoModel               Boolean   @map("is_auto_model")
+  defaultContext            Int       @map("default_context")
+  maxContext                Int       @map("max_context")
+
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @updatedAt @map("updated_at")
+
+  @@unique([provider, model])
+  @@map("llm_models")
+}
+
+/// HobbyResetTracker — drives the 90-day Hobby-tier reset (P4, spec §2.1
+/// item 8).
+model HobbyResetTracker {
+  id             String   @id @default(dbgenerated("('hbyrst_'::text || (uuidv7())::text)")) @db.Text
+  organizationId String   @unique @map("organization_id")
+  lastResetAt    DateTime @map("last_reset_at")
+  nextResetAt    DateTime @map("next_reset_at")
+
+  createdAt DateTime @default(now()) @map("created_at")
+
+  @@map("hobby_reset_trackers")
+}

package/templates/database/content/schema.prisma

@@ -0,0 +1,263 @@
+// content namespace — chat + artifact substrate (AgentSession, ConversationEvent,
+// SessionReadReceipt, Artifact, ArtifactVersion)
+//
+// Backs the event-sourced conversation transport + artifact persistence in
+// docs/research/ploy-capture/BACKEND-REQUIREMENTS.md (§1 transport R-T1..R-T7,
+// §2 event envelope, §3 endpoints). Workspaces own all domain content, so every
+// table here carries a non-null `workspaceId` tenant scope.
+//
+// Per ADR 0009 invariant 1: workspaceId / userId are plain String stable IDs —
+// NO @relation into the auth namespace (Workspace/User live in database/auth/).
+// Relations WITHIN this namespace (event → session, version → artifact) are
+// real FKs. Cross-namespace assembly (e.g. tenant guard resolving a session's
+// workspace) routes through apps/api/src/services/ (invariant 4).
+//
+// Generator + datasource blocks live in database/schema.prisma (the root schema
+// file). This file holds only model definitions for the content namespace.
+
+/// AgentSession — one agent conversation ("session"/captured "ploy") within a
+/// workspace. lastSeq is the append watermark for the event log (R-T1).
+model AgentSession {
+  id            String    @id @default(dbgenerated("('agsess_'::text || (uuidv7())::text)")) @db.Text
+  workspaceId   String    @map("workspace_id")
+  title         String?
+  status        String    @default("idle")
+  lastSeq       Int       @default(0) @map("last_seq")
+  lastMessageAt DateTime? @map("last_message_at")
+  draftMessage  String?   @map("draft_message")
+  createdAt     DateTime  @default(now()) @map("created_at")
+  updatedAt     DateTime  @updatedAt @map("updated_at")
+
+  events       ConversationEvent[]
+  artifacts    Artifact[]
+  readReceipts SessionReadReceipt[]
+
+  @@index([workspaceId, lastMessageAt(sort: Desc)])
+  @@map("agent_sessions")
+}
+
+/// ConversationEvent — append-only, seq-ordered event log entry (R-T1/R-T4).
+/// Envelope: { agentId, seq, type, turnId, payload, createdAt } (§2).
+/// workspaceId is denormalized so the scope layer filters events without a
+/// join through agent_sessions.
+model ConversationEvent {
+  id          String   @id @default(dbgenerated("('convev_'::text || (uuidv7())::text)")) @db.Text
+  sessionId   String   @map("session_id")
+  workspaceId String   @map("workspace_id")
+  agentId     String   @map("agent_id")
+  seq         Int
+  type        String
+  turnId      String?  @map("turn_id")
+  payload     Json
+  createdAt   DateTime @default(now()) @map("created_at")
+
+  session AgentSession @relation(fields: [sessionId], references: [id], onDelete: Cascade)
+
+  @@unique([sessionId, seq])
+  @@index([workspaceId])
+  @@map("conversation_events")
+}
+
+/// SessionReadReceipt — per-user read position for a session (R-T7 mark-read;
+/// drives unread badges). userId is a stable auth-namespace ID — no FK.
+model SessionReadReceipt {
+  id          String   @id @default(dbgenerated("('receipt_'::text || (uuidv7())::text)")) @db.Text
+  sessionId   String   @map("session_id")
+  workspaceId String   @map("workspace_id")
+  userId      String   @map("user_id")
+  lastReadSeq Int      @default(0) @map("last_read_seq")
+  updatedAt   DateTime @updatedAt @map("updated_at")
+
+  session AgentSession @relation(fields: [sessionId], references: [id], onDelete: Cascade)
+
+  @@unique([sessionId, userId])
+  @@index([workspaceId])
+  @@map("session_read_receipts")
+}
+
+/// Artifact — a session's produced output (first type: text/document, #3846).
+model Artifact {
+  id          String   @id @default(dbgenerated("('artif_'::text || (uuidv7())::text)")) @db.Text
+  sessionId   String   @map("session_id")
+  workspaceId String   @map("workspace_id")
+  type        String   @default("text/document")
+  title       String
+  createdAt   DateTime @default(now()) @map("created_at")
+  updatedAt   DateTime @updatedAt @map("updated_at")
+
+  session  AgentSession      @relation(fields: [sessionId], references: [id], onDelete: Cascade)
+  versions ArtifactVersion[]
+
+  @@index([sessionId])
+  @@index([workspaceId])
+  @@map("artifacts")
+}
+
+/// ArtifactVersion — auto-saved version history; exactly one isCurrent per
+/// artifact (enforced at the service layer on save/restore).
+model ArtifactVersion {
+  id          String   @id @default(dbgenerated("('artiv_'::text || (uuidv7())::text)")) @db.Text
+  artifactId  String   @map("artifact_id")
+  workspaceId String   @map("workspace_id")
+  content     Json
+  isCurrent   Boolean  @default(true) @map("is_current")
+  savedAt     DateTime @default(now()) @map("saved_at")
+
+  artifact Artifact @relation(fields: [artifactId], references: [id], onDelete: Cascade)
+
+  @@index([artifactId, savedAt(sort: Desc)])
+  @@index([workspaceId])
+  @@map("artifact_versions")
+}
+
+// ============================================================================
+// Usage-billing metering (FEAT-047 P1.S1, #3709 — Epic #3704)
+//
+// The metering event + its org-level aggregates. Per ADR 0009 D2 (roadmap §4),
+// the metering event + UsagePeriod + UsageBillingReport live in `content`;
+// balances/plans (S2) live in auth/config. organizationId/workspaceId/userId
+// are plain String stable-ids — no @relation into auth (ADR 0009 invariant 1).
+// Field roster ported from docs/research/wt-billing-capture/schema.md, modeled
+// on WT's TraceLog billing columns (spec D1), with workspaceId/userId added to
+// the event grain (spec D2). Cross-namespace assembly (e.g. resolving an
+// event's owning Workspace) routes through apps/api/src/services/.
+// ============================================================================
+
+/// ModelTier — the pricing tier at event time. BASE is unlimited/free-ish;
+/// PREMIUM/FRONTIER consume credits. Defined here (S1, the dependency root)
+/// per spec OQ-1 — S2's LlmModel references the same enum through the merged
+/// prismaSchemaFolder (one logical schema; an enum reference needs no
+/// @relation, so this is not a cross-namespace FK).
+enum ModelTier {
+  BASE
+  PREMIUM
+  FRONTIER
+}
+
+/// UsageBillingStatus — UsageBillingReport lifecycle: PENDING → REPORTED →
+/// INVOICED → PAID, or FAILED.
+enum UsageBillingStatus {
+  PENDING
+  REPORTED
+  INVOICED
+  PAID
+  FAILED
+}
+
+/// UsageEvent — one row per billable AI call (the metering event; modeled on
+/// WT's TraceLog billing columns, spec D1). org+workspace+user grain (spec
+/// D2); all three scope ids are plain String stable-ids — no cross-namespace
+/// @relation (ADR 0009 invariant 1, spec D3). The three attribution portion
+/// columns are the load-bearing billing split; only onDemandPortionCents is
+/// ever reported to Stripe (P4, spec D4). completionStatus 'success' rows
+/// drive billing — aggregation (P2) filters on it.
+model UsageEvent {
+  id             String @id @default(dbgenerated("('usagev_'::text || (uuidv7())::text)")) @db.Text
+  organizationId String @map("organization_id")
+  workspaceId    String @map("workspace_id")
+  userId         String @map("user_id")
+
+  provider String
+  model    String
+
+  // Cache-aware token breakdown.
+  inputTokensCacheWrite   Int @map("input_tokens_cache_write")
+  inputTokensNoCacheWrite Int @map("input_tokens_no_cache_write")
+  cacheReadTokens         Int @map("cache_read_tokens")
+  outputTokens            Int @map("output_tokens")
+  thinkingTokens          Int @map("thinking_tokens")
+  totalTokens             Int @map("total_tokens")
+
+  providerCostUsd Decimal @map("provider_cost_usd") @db.Decimal(10, 6)
+  billedCostUsd   Decimal @map("billed_cost_usd") @db.Decimal(10, 6)
+  markupPercent   Decimal @map("markup_percent") @db.Decimal(5, 2)
+
+  modelTier    ModelTier @default(BASE) @map("model_tier")
+  wasAutoModel Boolean   @map("was_auto_model")
+
+  // Attribution split — billedCostUsd apportioned across the three buckets;
+  // only onDemandPortionCents is ever Stripe-metered (P4, spec D4).
+  includedPortionCents      Int @default(0) @map("included_portion_cents")
+  creditBalancePortionCents Int @default(0) @map("credit_balance_portion_cents")
+  onDemandPortionCents      Int @default(0) @map("on_demand_portion_cents")
+
+  completionStatus String   @map("completion_status")
+  createdAt        DateTime @default(now()) @map("created_at")
+
+  @@index([organizationId, createdAt])
+  @@index([workspaceId, createdAt])
+  @@index([userId, createdAt])
+  @@index([provider, model])
+  @@index([modelTier, wasAutoModel])
+  @@map("usage_events")
+}
+
+/// UsagePeriod — one row per (organizationId, periodStart); the org-scoped
+/// spend/tier rollup the P2 write path upserts as UsageEvent rows land.
+/// Carries the event-grain roll-up support for the Org → Workspace → User
+/// aggregation (spec D2) — whether this model itself gains per-workspace
+/// sub-rows is a P2 decision, not a P1 schema requirement (spec OQ-2).
+model UsagePeriod {
+  id             String @id @default(dbgenerated("('usagper_'::text || (uuidv7())::text)")) @db.Text
+  organizationId String @map("organization_id")
+
+  periodStart DateTime @map("period_start")
+  periodEnd   DateTime @map("period_end")
+
+  tokensConsumed         BigInt @default(0) @map("tokens_consumed")
+  baseTokensConsumed     BigInt @default(0) @map("base_tokens_consumed")
+  premiumTokensConsumed  BigInt @default(0) @map("premium_tokens_consumed")
+  frontierTokensConsumed BigInt @default(0) @map("frontier_tokens_consumed")
+
+  usageSpendCents Int @default(0) @map("usage_spend_cents")
+
+  @@unique([organizationId, periodStart])
+  @@index([baseTokensConsumed, premiumTokensConsumed, frontierTokensConsumed], map: "usage_periods_tier_tracking_idx")
+  @@map("usage_periods")
+}
+
+/// UsageBillingReport — one per (organizationId, periodStart, periodEnd); the
+/// Stripe-reporting unit rolled up from UsageEvent by P2 aggregation. Only
+/// onDemandCents is ever reported to Stripe (P4, spec D4) — includedCents/
+/// creditBalanceCents are informational attribution, never metered.
+model UsageBillingReport {
+  id             String @id @default(dbgenerated("('usagrept_'::text || (uuidv7())::text)")) @db.Text
+  organizationId String @map("organization_id")
+
+  periodStart DateTime @map("period_start")
+  periodEnd   DateTime @map("period_end")
+
+  // AGGREGATE precision (#3738 H2) — these hold a MONTH of events, not one
+  // event, so they must NOT reuse UsageEvent's per-event widths. At the
+  // original Decimal(10,6)/Int, an org whose month crossed $9,999.999999 (or
+  // 2.15B tokens) overflowed the column, the upsert threw, and the report was
+  // never written on ANY subsequent run — silently stalling revenue for the
+  // largest customers, worsening monotonically. Decimal(20,6) ≈ $1e14 and int8
+  // give headroom far above the service's own MAX_TOTAL_USD / token caps, so
+  // the service's loud `aggregate_overflow` assertion is always the gate and a
+  // silent DB overflow is unreachable. See usage-aggregation.ts § Bounds.
+  totalProviderCost Decimal @map("total_provider_cost") @db.Decimal(20, 6)
+  totalMarkupAmount Decimal @map("total_markup_amount") @db.Decimal(20, 6)
+  totalBilledAmount Decimal @map("total_billed_amount") @db.Decimal(20, 6)
+
+  totalTokens BigInt @map("total_tokens")
+  eventCount  Int    @map("event_count")
+
+  // Attribution split — only onDemandCents is ever Stripe-metered (P4, spec D4).
+  includedCents      Int @default(0) @map("included_cents")
+  creditBalanceCents Int @default(0) @map("credit_balance_cents")
+  onDemandCents      Int @default(0) @map("on_demand_cents")
+
+  stripeUsageRecordId String?   @map("stripe_usage_record_id")
+  reportedToStripeAt  DateTime? @map("reported_to_stripe_at")
+  stripeInvoiceId     String?   @map("stripe_invoice_id")
+
+  status       UsageBillingStatus @default(PENDING)
+  errorMessage String?            @map("error_message")
+
+  @@unique([organizationId, periodStart, periodEnd], map: "usage_billing_reports_period_key")
+  @@index([organizationId, status])
+  @@index([status])
+  @@index([periodStart])
+  @@map("usage_billing_reports")
+}

package/templates/database/flows/listing-diagnostic.ts

@@ -0,0 +1,182 @@
+/**
+ * @file listing-diagnostic.ts
+ * @description The ONE scoring RULE every project-listing diagnostic shares
+ * (#5001, reworked by #5036 D4) — the template's Q3–Q6 resolved by option
+ * VALUE, never by option position.
+ *
+ * The mechanism (#5036 D4, "scoring by value, not position"): the generated
+ * flow emits each scored option under the FOUNDER'S OWN `option.value`, and
+ * the register's `optionWeights` map is keyed on those same values. Q3/Q4 are
+ * founder-authored, so their weights map is built PER LISTING from that
+ * listing's own options — the WEIGHT still comes from the founder's declared
+ * order via `listingOptionPoints(index, arity)`, but it is stored against the
+ * value rather than an index. Q5/Q6 carry fixed values
+ * (`projectListingQuestionsSchema`, #4998), so their weights are declared once
+ * here, shared by every listing.
+ *
+ * What that buys, and why the old `q{n}:{i}of{k}` encoding had to go: meaning
+ * now travels with the value. A register may reorder or insert options and an
+ * already-stored answer keeps scoring what it always meant, so the subset a
+ * surface renders no longer has to be a prefix of the register's list — which
+ * is what unblocks the shared team-composition value set (#5036 D3). It also
+ * dissolves the "shared register needs a shared value universe" problem
+ * (docs/lessons/2026-09-07-…): the generated experiment's `questionSet` now
+ * declares the listing's OWN options, so
+ * `waitlistExperimentConfigSchema`'s "every weights key must be a declared
+ * option" cross-validation is satisfied by construction rather than by
+ * declaring a finite universe of positional tokens.
+ *
+ * What is shared is therefore the RULE and the shape — same point names, same
+ * `total` sum, same tier floors, same 0–12 range — not a single frozen
+ * constant. Two listings' registers differ only in the Q3/Q4 KEYS, which are
+ * the founders' own option values.
+ *
+ * Q5 runs STRONGEST-FIRST, deliberately. `projectListingQuestionsSchema` pins
+ * Q5's values as `urgent | planning | exploring`, which is urgency descending,
+ * while the positional rule scores index 0 lowest — so the old positional
+ * encoding scored `urgent` 0 and `exploring` 3, backwards, a standing defect
+ * recorded in docs/lessons/2026-09-07-q5-fixed-order-is-strongest-first.md.
+ * Scoring by value is exactly the mechanism that resolves it: the weights
+ * below name `urgent` 3 and `exploring` 0 explicitly, with no reordering of
+ * the founder's rendered options and no per-question special case hidden
+ * inside a positional formula. That lesson's open question is closed here.
+ * Q6 (`low → critical`) is genuinely weakest-first and keeps 0 → 3.
+ *
+ * Q1 (contact), Q2 (segment), Q7 (free text) and the extras carry no points —
+ * they are absent from `points` entirely, so they contribute 0 by
+ * construction rather than by a zero weight that could drift.
+ *
+ * This module is data + the pure functions that generate it — it imports only
+ * TYPES from `@working-theory/validation` and introduces no dependency from
+ * `database/` toward `apps/*` (architecture.yaml's import boundary), exactly
+ * like `presets.ts` beside it. The rule lives here and only here; the
+ * projection (`apps/api/src/services/project-listing-flow.ts`) calls
+ * `buildListingDiagnosticScoring` rather than re-deriving weights, so the
+ * register and the flow can never disagree about what an answer is worth.
+ */
+
+import type {
+  ProjectListingQuestions,
+  WaitlistScoring,
+} from "@working-theory/validation";
+
+/** The four scored template questions, in template order. */
+export const LISTING_DIAGNOSTIC_SCORED_QUESTIONS = ["q3", "q4", "q5", "q6"] as const;
+export type ListingDiagnosticScoredQuestion =
+  (typeof LISTING_DIAGNOSTIC_SCORED_QUESTIONS)[number];
+
+/** The highest score any one question can contribute. */
+export const LISTING_DIAGNOSTIC_MAX_QUESTION_POINTS = 3;
+
+/**
+ * The weight of option `index` (zero-based) of `arity` options —
+ * `round(3·i/(k−1))`, so the founder's first option always scores 0 and their
+ * last always scores 3, whatever the arity. This is still how a
+ * founder-authored question's weights are DERIVED (the founder orders their
+ * options weakest→strongest); what changed in #5036 D4 is where the result is
+ * STORED — against the option's value, not its index.
+ *
+ * A single-option question (`arity <= 1`) has no spread to score and yields 0;
+ * the template never produces one, and this guard exists so the expression can
+ * never divide by zero.
+ */
+export function listingOptionPoints(index: number, arity: number): number {
+  if (arity <= 1) return 0;
+  return Math.round((LISTING_DIAGNOSTIC_MAX_QUESTION_POINTS * index) / (arity - 1));
+}
+
+/**
+ * `optionWeights` for one founder-authored question (Q3/Q4), keyed by the
+ * founder's own option values and weighted by their declared order.
+ */
+export function listingDiagnosticOptionWeights(
+  options: readonly { value: string }[],
+): Record<string, number> {
+  const weights: Record<string, number> = {};
+  options.forEach((option, index) => {
+    weights[option.value] = listingOptionPoints(index, options.length);
+  });
+  return weights;
+}
+
+/**
+ * Q5's fixed urgency weights — STRONGEST FIRST, against the positional rule
+ * and deliberately so (see the file header). `urgent` is the strongest buying
+ * signal the question can carry and scores 3; `exploring` is the weakest and
+ * scores 0. The three weights are the same multiset a 3-option positional
+ * question produces (`{0, 2, 3}`), so the 0–12 total range is unchanged.
+ */
+export const LISTING_DIAGNOSTIC_Q5_WEIGHTS: Readonly<Record<string, number>> = {
+  urgent: 3,
+  planning: 2,
+  exploring: 0,
+};
+
+/**
+ * Q6's fixed band weights — weakest first, matching the schema's own
+ * `low → critical` low→high ordering, so these are exactly what the positional
+ * rule produced for a 4-option question.
+ */
+export const LISTING_DIAGNOSTIC_Q6_WEIGHTS: Readonly<Record<string, number>> = {
+  low: 0,
+  medium: 1,
+  high: 2,
+  critical: 3,
+};
+
+/** The four tier keys, strongest first — the order `tiers` is evaluated in. */
+export const LISTING_DIAGNOSTIC_TIERS = ["now", "soon", "later", "curious"] as const;
+
+/**
+ * The inclusive lower bound of each tier over the 0–12 total (4 questions ×
+ * 3 points): `now` 10–12, `soon` 7–9, `later` 4–6, `curious` 0–3. Ordered
+ * strongest-first because `evaluateWaitlistScoring` takes the FIRST matching
+ * tier, so a `gte` ladder read top-down is total and unambiguous.
+ */
+const TIER_FLOORS: Readonly<Record<(typeof LISTING_DIAGNOSTIC_TIERS)[number], number>> = {
+  now: 10,
+  soon: 7,
+  later: 4,
+  curious: 0,
+};
+
+/**
+ * Build one listing's register from its own `questions` block. Embedded
+ * verbatim into that listing's generated `WaitlistExperiment.config` —
+ * `waitlistExperimentConfigSchema` carries the scoring block by value and
+ * offers no by-reference slot.
+ *
+ * Every listing gets the same point names, the same `total` sum, the same
+ * tier ladder and the same 0–12 range; only the Q3/Q4 weight KEYS differ,
+ * because those keys are the founder's own option values (#5036 D4).
+ */
+export function buildListingDiagnosticScoring(
+  questions: ProjectListingQuestions,
+): WaitlistScoring {
+  const weights: Record<ListingDiagnosticScoredQuestion, Record<string, number>> = {
+    q3: listingDiagnosticOptionWeights(questions.q3.options),
+    q4: listingDiagnosticOptionWeights(questions.q4.options),
+    q5: { ...LISTING_DIAGNOSTIC_Q5_WEIGHTS },
+    q6: { ...LISTING_DIAGNOSTIC_Q6_WEIGHTS },
+  };
+
+  return {
+    version: 1,
+    points: LISTING_DIAGNOSTIC_SCORED_QUESTIONS.map((question) => ({
+      name: `${question}_points`,
+      question,
+      kind: "optionWeights" as const,
+      weights: weights[question],
+    })),
+    scores: {
+      total: {
+        sum: LISTING_DIAGNOSTIC_SCORED_QUESTIONS.map((q) => `${q}_points`),
+      },
+    },
+    tiers: LISTING_DIAGNOSTIC_TIERS.map((key) => ({
+      key,
+      when: { score: "total", gte: TIER_FLOORS[key] },
+    })),
+    default: "curious",
+  };
+}