@elevasis/core 0.5.0 → 0.6.0

package/src/reference/_generated/contracts.md

@@ -1,4 +1,4 @@
-<!-- Auto-generated on 2026-04-19T04:30:03.546Z by scripts/monorepo/generate-scaffold-contracts.js -->
+<!-- Auto-generated on 2026-04-20T23:27:16.482Z by scripts/monorepo/generate-scaffold-contracts.js -->
 ---
 title: Reference Contracts
 description: Auto-generated TypeScript contracts for SDK consumers. Do not edit manually.
@@ -20,22 +20,22 @@ export type OrganizationModel = z.infer<typeof OrganizationModelSchema>
 export type OrganizationModelBranding = z.infer<typeof OrganizationModelBrandingSchema>
 ```
 
-### `OrganizationModelCrm`
+### `OrganizationModelSales`
 
 ```typescript
-export type OrganizationModelCrm = z.infer<typeof OrganizationModelCrmSchema>
+export type OrganizationModelSales = z.infer<typeof OrganizationModelSalesSchema>
 ```
 
-### `OrganizationModelLeadGen`
+### `OrganizationModelProspecting`
 
 ```typescript
-export type OrganizationModelLeadGen = z.infer<typeof OrganizationModelLeadGenSchema>
+export type OrganizationModelProspecting = z.infer<typeof OrganizationModelProspectingSchema>
 ```
 
-### `OrganizationModelDelivery`
+### `OrganizationModelProjects`
 
 ```typescript
-export type OrganizationModelDelivery = z.infer<typeof OrganizationModelDeliverySchema>
+export type OrganizationModelProjects = z.infer<typeof OrganizationModelProjectsSchema>
 ```
 
 ### `OrganizationModelFeature`
@@ -62,6 +62,114 @@ export type OrganizationModelSurface = z.infer<typeof SurfaceDefinitionSchema>
 export type OrganizationModelResourceMapping = z.infer<typeof ResourceMappingSchema>
 ```
 
+### `OrganizationModelTechStackEntry`
+
+```typescript
+export type OrganizationModelTechStackEntry = z.infer<typeof TechStackEntrySchema>
+```
+
+### `OrganizationModelStatuses`
+
+```typescript
+export type OrganizationModelStatuses = z.infer<typeof StatusesDomainSchema>
+```
+
+### `OrganizationModelStatusEntry`
+
+```typescript
+export type OrganizationModelStatusEntry = z.infer<typeof StatusEntrySchema>
+```
+
+### `OrganizationModelStatusSemanticClass`
+
+```typescript
+export type OrganizationModelStatusSemanticClass = z.infer<typeof StatusSemanticClassSchema>
+```
+
+### `OrganizationModelOperations`
+
+```typescript
+export type OrganizationModelOperations = z.infer<typeof OperationsDomainSchema>
+```
+
+### `OrganizationModelOperationEntry`
+
+```typescript
+export type OrganizationModelOperationEntry = z.infer<typeof OperationEntrySchema>
+```
+
+### `OrganizationModelOperationSemanticClass`
+
+```typescript
+export type OrganizationModelOperationSemanticClass = z.infer<typeof OperationSemanticClassSchema>
+```
+
+### `OrganizationModelCustomers`
+
+```typescript
+export type OrganizationModelCustomers = z.infer<typeof CustomersDomainSchema>
+```
+
+### `OrganizationModelCustomerSegment`
+
+```typescript
+export type OrganizationModelCustomerSegment = z.infer<typeof CustomerSegmentSchema>
+```
+
+### `OrganizationModelCustomerFirmographics`
+
+```typescript
+export type OrganizationModelCustomerFirmographics = z.infer<typeof FirmographicsSchema>
+```
+
+### `OrganizationModelOfferings`
+
+```typescript
+export type OrganizationModelOfferings = z.infer<typeof OfferingsDomainSchema>
+```
+
+### `OrganizationModelProduct`
+
+```typescript
+export type OrganizationModelProduct = z.infer<typeof ProductSchema>
+```
+
+### `OrganizationModelPricingModel`
+
+```typescript
+export type OrganizationModelPricingModel = z.infer<typeof PricingModelSchema>
+```
+
+### `OrganizationModelRoles`
+
+```typescript
+export type OrganizationModelRoles = z.infer<typeof RolesDomainSchema>
+```
+
+### `OrganizationModelRole`
+
+```typescript
+export type OrganizationModelRole = z.infer<typeof RoleSchema>
+```
+
+### `OrganizationModelGoals`
+
+```typescript
+export type OrganizationModelGoals = z.infer<typeof GoalsDomainSchema>
+```
+
+### `OrganizationModelObjective`
+
+```typescript
+export type OrganizationModelObjective = z.infer<typeof ObjectiveSchema>
+```
+
+### `OrganizationModelKeyResult`
+
+```typescript
+export type OrganizationModelKeyResult = z.infer<typeof KeyResultSchema>
+```
+
 ### `DeepPartial`
 
 ```typescript
@@ -479,7 +587,7 @@ export interface ResourceList {
 
 ```typescript
 /** Webhook provider identifiers */
-export type WebhookProviderType = 'cal-com' | 'stripe' | 'signature-api' | 'instantly' | 'apify'
+export type WebhookProviderType = 'cal-com' | 'stripe' | 'signature-api' | 'instantly' | 'apify' | 'test'
 
 /** Webhook trigger configuration */
 ```

package/src/reference/glossary.md

@@ -17,12 +17,16 @@ This condensed version covers every ambiguity-prone term a template consumer or
 
 **AdminGuard** -- route-level admin wrapper from `@elevasis/ui/features/auth`. Wraps routes restricted to admin members. Must nest inside `ProtectedRoute`. Does not replace `requiresAdmin` on nav entries -- use both when both route access and nav visibility need admin enforcement.
 
+**`/configure`** -- the recurring organization model editor for external projects. A slash skill (not a command) at `.claude/skills/configure/SKILL.md`. Runs a layered QA flow across `identity`, `customers`, `offerings`, `roles`, `goals`, `techStack`, `features`, and `labels`. Can be invoked without an argument (full layered flow) or with a domain argument (`/configure identity`, `/configure customers`, etc.) for targeted edits. Every write is gated through `resolveOrganizationModel()` + `OrganizationModelSchema.parse()` with a TypeScript type-check fallback. The ambient vibe layer delegates Codify and Toggle intents to `/configure` rather than writing directly. Distinct from `/setup` (first-time bootstrap) and `/org-os manage` (monorepo-only feature gating). `/configure` is available in external projects only.
+
 **Contract** -- the publishable I/O boundary: Zod schemas in `foundations/types/index.ts` for workflow inputs/outputs, or the `FeatureModule` TypeScript shape for shell features. Distinct from "manifest": a contract is the structural definition; a manifest is a specific feature instance conforming to that shape.
 
 **DeploymentSpec** -- the complete resource collection for one organization (`workflows`, `agents`, `triggers`, `integrations`, `relationships`, `externalResources`, `humanCheckpoints`). Defined in `@repo/core`. The `operations/src/index.ts` file in each external project exports one `DeploymentSpec`.
 
 **Domain** -- removed concept. What was previously a `SemanticDomain` entry in `OrganizationModel.domains` is now expressed directly as a **Feature** in the `features` array. The `domains` field no longer exists on `OrganizationModel`. Semantic grouping (entity IDs, surface IDs, resource IDs, capability IDs) now lives on each `OrganizationModelFeature` object.
 
+**Domain rename wave (2026-04-20)** -- three legacy top-level domain field names on `OrganizationModel` were renamed to align with user-visible labels: `crm` → `sales`, `leadGen` → `prospecting`, `delivery` → `projects`. Feature ID constants (`CRM_FEATURE_ID`, `LEAD_GEN_FEATURE_ID`) and consumer-facing feature IDs (`'crm'`, `'lead-gen'`) are unchanged. Only the Zod schema field names, domain files, surface IDs, and imports were updated.
+
 **Feature** -- the unified concept replacing the former three-layer system (feature keys, semantic domains, feature modules). Always qualify which layer is in scope:
 
 - **Platform capability** -- a product area (Execution Engine, Workflows, Agents, etc.). Not one-to-one with shell features.
@@ -37,25 +41,39 @@ This condensed version covers every ambiguity-prone term a template consumer or
 
 **Foundations** -- the adapter layer in `foundations/` (two modules: `config/organization-model.ts` and `types/index.ts`). Source package with no build step. Depends only on `@elevasis/core` (npm) and `zod`. Never import `@repo/core` from foundations -- that would break standalone deployment.
 
+**Identity domain** -- legal identity, distinct from `branding` (display identity). Lives at `OrganizationModel.identity`. Fields: `mission`, `vision`, `legalName`, `entityType`, `jurisdiction`, `industryCategory`, `geographicFocus`, `timeZone`, `businessHours`. Agents use identity fields for compliance, localization, and context. Edit via `/configure identity`.
+
+**Customers domain** -- customer segments with jobs-to-be-done, pains, gains, firmographics, and value propositions. Lives at `OrganizationModel.customers`. Each `CustomerSegment` has `id`, `name`, `description`, `jobsToBeDone`, `pains`, `gains`, `valueProp`, and optional `firmographics`. Agents use segments for outreach targeting and sales automation. Edit via `/configure customers`.
+
+**Goals domain** -- organizational goals with period bounds and measurable outcomes. Lives at `OrganizationModel.goals`. User-facing text uses "goals" and "measurable outcomes"; the schema field name `keyResults` is retained for OKR tooling compatibility but is never surfaced to users as "OKR" or "key results". Edit via `/configure goals`.
+
 **Manifest** -- a `FeatureModule` instance that declares what one shell feature contributes at runtime (nav, sidebar, subshell routes, access key, semantic references). The provider registers an array of manifests at startup and validates them against the resolved org model.
 
 **MembershipFeatureConfig** -- per-member-per-org feature overrides stored in `org_memberships.config`. The `features` field is now `Record<string, boolean>` -- any feature ID can be overridden per member. Previously hardcoded to five keys (`operations`, `monitoring`, `acquisition`, `delivery`, `seo`); now open to any feature ID in the org model.
 
-**OrganizationModel** -- the top-level semantic contract for an organization. Published from `@elevasis/core/organization-model`. In the template, authored in `foundations/config/organization-model.ts` and exported as `canonicalOrganizationModel` (passed to `ElevasisFeaturesProvider`) and `organizationModel` (enriched shape for app-local use).
+**Offerings domain** -- products and services with pricing model, price, currency, target segment references, and optional delivery-feature references. Lives at `OrganizationModel.offerings`. Each `Product` has `id`, `name`, `description`, `pricingModel` (`one-time | subscription | usage-based | custom`), optional `price` and `currency`, `targetSegmentIds` (cross-ref validated against `customers.segments`), and optional `deliveryFeatureId` (cross-ref validated against `features`). Edit via `/configure offerings`.
 
-**OrganizationModelFeature** -- the TypeScript type (`z.infer<typeof FeatureSchema>`) for a single entry in `OrganizationModel.features`. Replaces the former `OrganizationModelFeatureKey` (closed enum) and `OrganizationModelSemanticDomain`. Each feature has `id`, `label`, `enabled`, and semantic grouping arrays (`entityIds`, `surfaceIds`, `resourceIds`, `capabilityIds`). Exported from `@elevasis/core/organization-model`.
+**Operations domain** -- catalog of stateful runtime entities. Lives at `OrganizationModel.operations`. Each `OperationEntry` has `id`, `label`, `semanticClass` (one of `queue | executions | sessions | notifications | schedules`), optional `featureId`, and optional `supportedStatusSemanticClass` array. Used by the ambient vibe layer to narrate runtime entity state. Default entries cover HITL queue, executions, sessions, notifications, and schedules.
+
+**OrganizationModel** -- the top-level semantic contract for an organization. Published from `@elevasis/core/organization-model`. In the template, authored in `foundations/config/organization-model.ts` and exported as `canonicalOrganizationModel` (passed to `ElevasisFeaturesProvider`) and `organizationModel` (enriched shape for app-local use). As of the 2026-04-20 expansion, the model contains 14 top-level domains: `features`, `branding`, `navigation`, `sales` (formerly `crm`), `prospecting` (formerly `leadGen`), `projects` (formerly `delivery`), `identity`, `customers`, `offerings`, `roles`, `goals`, `statuses`, `operations`, and `resourceMappings` (with optional `techStack` per entry). Use `/configure` as the entry point for editing reality domains in external projects.
+
+**OrganizationModelFeature** -- the TypeScript type (`z.infer<typeof FeatureSchema>`) for a single entry in `OrganizationModel.features`. Replaces the former `OrganizationModelFeatureKey` (closed enum) and `OrganizationModelSemanticDomain`. Each feature has `id`, `label`, `enabled`, and semantic grouping arrays (`entityIds`, `surfaceIds`, `resourceIds`, `capabilityIds`). Exported from `@elevasis/core/organization-model`. Default feature IDs: `crm`, `lead-gen`, `projects`, `operations`, `monitoring`, `settings`, `submitted-requests`, `seo`. Note: feature IDs `crm` and `lead-gen` are unchanged by the domain rename wave; only the domain field names on `OrganizationModel` were renamed (`crm` → `sales`, `leadGen` → `prospecting`).
 
 **Provider / ElevasisFeaturesProvider** -- the runtime that registers manifests, resolves feature access against the org model, dispatches subshell routing via `FeatureShell`, and exposes resolved state through `useElevasisFeatures()`. Mounted in `__root.tsx`. Accepts `features`, optional `organizationModel`, and optional `appShellOverrides`.
 
 **Resolved types (ResolvedFeatureModule, ResolvedShellNavItem)** -- provider output. `ResolvedFeatureModule` extends `FeatureModule` with `access` (enabled state and `featureId`) and `semantics` (merged capability and surface IDs). `ResolvedShellNavItem` extends `FeatureNavEntry` with `placement`, `source`, and `featureId`. Both from `@elevasis/ui`.
 
-**Resource** -- an entry in `OrganizationModel.resourceMappings` linking a deployable automation resource into the semantic model. At the registry layer, resources are `WorkflowDefinition` or `AgentDefinition` instances in a `DeploymentSpec`.
+**Resource** -- an entry in `OrganizationModel.resourceMappings` linking a deployable automation resource into the semantic model. At the registry layer, resources are `WorkflowDefinition` or `AgentDefinition` instances in a `DeploymentSpec`. Each resource mapping may carry an optional `techStack` extension with `platform`, `purpose`, `credentialStatus`, and `isSystemOfRecord` fields.
+
+**Roles domain** -- role chart with responsibilities, reporting lines, and role holders. Lives at `OrganizationModel.roles`. Each `Role` has `id`, `title`, `responsibilities` (string array), optional `reportsToId` (cross-ref validated within the same collection), and optional `heldBy` (name or email). All field names are plain-language; no EOS jargon (`seats`, `accountabilities`) is used. Edit via `/configure roles`.
+
+**Statuses domain** -- flat registry of all status entries across delivery, queue, execution, schedule, and request semantic classes. Lives at `OrganizationModel.statuses`. Each `StatusEntry` has `id`, `label`, `semanticClass` (closed enum), and optional `category`. Labels are the canonical plain-language strings the ambient vibe layer reads when narrating status -- never hardcoded strings. `QueueTaskStatus` in the queue domain routes through this registry.
 
 **Settings asymmetry** -- `settings` is a valid feature ID (org-level, present in `OrganizationModel.features` with `enabled: true` by default). `MembershipFeatureConfig.features` is now `Record<string, boolean>`, so `settings` can technically be overridden per member, but the convention is still to gate settings visibility via `requiresAdmin` on the nav entry and `AdminGuard` on routes rather than per-member feature overrides.
 
 **Subshell / Sidebar** -- the feature-scoped UI region rendered when the current route matches a manifest's `subshellRoutes`. Each `FeatureModule.sidebar` is a `ComponentType`. Consumers customize by composing the feature's published sidebar primitives (`CrmSidebar`, `CrmSidebarMiddle`, etc.) and assigning their component to `manifest.sidebar`.
 
-**Surface** -- a navigable view in `OrganizationModel.navigation.surfaces`. Identified by a dotted `id` (e.g., `crm.pipeline`). Has `path`, `surfaceType`, optional `featureId` gate (replaces the former `featureKey` field), and cross-reference arrays (`featureIds`, `entityIds`, `resourceIds`, `capabilityIds`). Distinct from "page": a surface is the org-model declaration; a page is the React component rendered at the route.
+**Surface** -- a navigable view in `OrganizationModel.navigation.surfaces`. Identified by a dotted `id` (e.g., `sales.pipeline`). Has `path`, `surfaceType`, optional `featureId` gate (replaces the former `featureKey` field), and cross-reference arrays (`featureIds`, `entityIds`, `resourceIds`, `capabilityIds`). Distinct from "page": a surface is the org-model declaration; a page is the React component rendered at the route.
 
 **Topology** -- resource relationships (`triggers`, `uses`, `approval`) declared in `DeploymentSpec.relationships` and `HumanCheckpointDefinition.routesTo`. Used for Command View graph edges.
 
@@ -66,6 +84,9 @@ This condensed version covers every ambiguity-prone term a template consumer or
 **`@elevasis/core`** (published npm)
 
 - `OrganizationModel`, `OrganizationModelFeature`, `OrganizationModelSurface`, `OrganizationModelResourceMapping`
+- `OrganizationModelIdentity`, `OrganizationModelCustomers`, `OrganizationModelOfferings`, `OrganizationModelRoles`, `OrganizationModelGoals`
+- `OrganizationModelStatuses`, `OrganizationModelOperations`
+- `TechStackEntrySchema`, `OrganizationModelTechStackEntry`
 - `resolveOrganizationModel`, `defineOrganizationModel`, `DEFAULT_ORGANIZATION_MODEL`
 - `MembershipFeatureConfig`
 

package/src/requests/__tests__/api-schemas.test.ts

@@ -0,0 +1,277 @@
+import { describe, it, expect } from 'vitest'
+import {
+  CreateRequestInputSchema,
+  ListRequestsQuerySchema,
+  RequestSeverityEnum,
+  RequestCategoryEnum,
+  RequestStatusEnum,
+  RequestSourceEnum,
+  RequestTypeEnum
+} from '../api-schemas'
+
+const validInput = {
+  type: 'bug' as const,
+  title: 'Login button not responding',
+  description: 'The login button does nothing when clicked on Safari.',
+  severity: 'warning' as const,
+  category: 'ui_bug' as const
+}
+
+describe('CreateRequestInputSchema', () => {
+  it('accepts a minimal valid payload', () => {
+    const result = CreateRequestInputSchema.safeParse(validInput)
+    expect(result.success).toBe(true)
+  })
+
+  it('accepts a fully-populated payload', () => {
+    const result = CreateRequestInputSchema.safeParse({
+      ...validInput,
+      affected_page: '/projects/abc',
+      evidence: { stack: 'TypeError: x is undefined' },
+      context: { recent_messages: [], identified_source: 'ui/src/routes/login.tsx' },
+      project_id: '123e4567-e89b-12d3-a456-426614174000',
+      task_id: '123e4567-e89b-12d3-a456-426614174001'
+    })
+    expect(result.success).toBe(true)
+  })
+
+  it('accepts null for optional nullish fields', () => {
+    const result = CreateRequestInputSchema.safeParse({
+      ...validInput,
+      affected_page: null,
+      evidence: null,
+      context: null,
+      project_id: null,
+      task_id: null
+    })
+    expect(result.success).toBe(true)
+  })
+
+  it('accepts feature type', () => {
+    const result = CreateRequestInputSchema.safeParse({ ...validInput, type: 'feature' })
+    expect(result.success).toBe(true)
+  })
+
+  it('accepts question type', () => {
+    const result = CreateRequestInputSchema.safeParse({ ...validInput, type: 'question' })
+    expect(result.success).toBe(true)
+  })
+
+  it('accepts other type', () => {
+    const result = CreateRequestInputSchema.safeParse({ ...validInput, type: 'other' })
+    expect(result.success).toBe(true)
+  })
+
+  it('rejects missing type (required, no default)', () => {
+    const { type: _type, ...withoutType } = validInput
+    const result = CreateRequestInputSchema.safeParse(withoutType)
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects invalid type value', () => {
+    const result = CreateRequestInputSchema.safeParse({ ...validInput, type: 'enhancement' })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects empty title', () => {
+    const result = CreateRequestInputSchema.safeParse({ ...validInput, title: '' })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects empty description', () => {
+    const result = CreateRequestInputSchema.safeParse({ ...validInput, description: '' })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects invalid severity', () => {
+    const result = CreateRequestInputSchema.safeParse({ ...validInput, severity: 'urgent' })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects invalid category', () => {
+    const result = CreateRequestInputSchema.safeParse({ ...validInput, category: 'typo' })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects invalid project_id UUID', () => {
+    const result = CreateRequestInputSchema.safeParse({ ...validInput, project_id: 'not-a-uuid' })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects invalid task_id UUID', () => {
+    const result = CreateRequestInputSchema.safeParse({ ...validInput, task_id: 'not-a-uuid' })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects client-supplied source (strict mode — mass assignment prevention)', () => {
+    const result = CreateRequestInputSchema.safeParse({ ...validInput, source: 'external' })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects client-supplied organization_id (strict mode)', () => {
+    const result = CreateRequestInputSchema.safeParse({
+      ...validInput,
+      organization_id: '123e4567-e89b-12d3-a456-426614174000'
+    })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects client-supplied reporter_id (strict mode)', () => {
+    const result = CreateRequestInputSchema.safeParse({
+      ...validInput,
+      reporter_id: '123e4567-e89b-12d3-a456-426614174000'
+    })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects client-supplied status (strict mode)', () => {
+    const result = CreateRequestInputSchema.safeParse({ ...validInput, status: 'resolved' })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects arbitrary unknown field (strict mode)', () => {
+    const result = CreateRequestInputSchema.safeParse({ ...validInput, foo: 'bar' })
+    expect(result.success).toBe(false)
+  })
+})
+
+describe('ListRequestsQuerySchema', () => {
+  it('applies default limit of 50', () => {
+    const result = ListRequestsQuerySchema.safeParse({})
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.limit).toBe(50)
+    }
+  })
+
+  it('coerces string limit to number', () => {
+    const result = ListRequestsQuerySchema.safeParse({ limit: '25' })
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.limit).toBe(25)
+    }
+  })
+
+  it('rejects limit < 1', () => {
+    const result = ListRequestsQuerySchema.safeParse({ limit: '0' })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects limit > 200', () => {
+    const result = ListRequestsQuerySchema.safeParse({ limit: '201' })
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects non-numeric limit', () => {
+    const result = ListRequestsQuerySchema.safeParse({ limit: 'abc' })
+    expect(result.success).toBe(false)
+  })
+
+  it('accepts valid status filter', () => {
+    const result = ListRequestsQuerySchema.safeParse({ status: 'open' })
+    expect(result.success).toBe(true)
+  })
+
+  it('rejects invalid status filter', () => {
+    const result = ListRequestsQuerySchema.safeParse({ status: 'archived' })
+    expect(result.success).toBe(false)
+  })
+
+  it('accepts valid severity filter', () => {
+    const result = ListRequestsQuerySchema.safeParse({ severity: 'critical' })
+    expect(result.success).toBe(true)
+  })
+
+  it('rejects invalid severity filter', () => {
+    const result = ListRequestsQuerySchema.safeParse({ severity: 'urgent' })
+    expect(result.success).toBe(false)
+  })
+
+  it('accepts valid project_id UUID filter', () => {
+    const result = ListRequestsQuerySchema.safeParse({
+      project_id: '123e4567-e89b-12d3-a456-426614174000'
+    })
+    expect(result.success).toBe(true)
+  })
+
+  it('rejects invalid project_id UUID', () => {
+    const result = ListRequestsQuerySchema.safeParse({ project_id: 'not-a-uuid' })
+    expect(result.success).toBe(false)
+  })
+})
+
+describe('RequestSeverityEnum', () => {
+  it('accepts all valid severities', () => {
+    const severities = ['critical', 'warning', 'info']
+    severities.forEach((s) => {
+      expect(RequestSeverityEnum.safeParse(s).success).toBe(true)
+    })
+  })
+
+  it('rejects invalid severity', () => {
+    expect(RequestSeverityEnum.safeParse('urgent').success).toBe(false)
+  })
+})
+
+describe('RequestCategoryEnum', () => {
+  it('accepts all valid categories (must match DB CHECK constraint)', () => {
+    const categories = [
+      'ui_bug',
+      'data_inconsistency',
+      'performance',
+      'error_pattern',
+      'configuration',
+      'feature_request',
+      'api_design',
+      'documentation',
+      'integration_request',
+      'other'
+    ]
+    categories.forEach((c) => {
+      expect(RequestCategoryEnum.safeParse(c).success).toBe(true)
+    })
+  })
+
+  it('rejects invalid category', () => {
+    expect(RequestCategoryEnum.safeParse('typo').success).toBe(false)
+  })
+})
+
+describe('RequestStatusEnum', () => {
+  it('accepts all valid statuses (must match DB CHECK constraint)', () => {
+    const statuses = ['open', 'investigating', 'resolved', 'wont_fix']
+    statuses.forEach((s) => {
+      expect(RequestStatusEnum.safeParse(s).success).toBe(true)
+    })
+  })
+
+  it('rejects invalid status', () => {
+    expect(RequestStatusEnum.safeParse('archived').success).toBe(false)
+  })
+})
+
+describe('RequestSourceEnum', () => {
+  it('accepts all valid sources (must match DB CHECK constraint)', () => {
+    const sources = ['agent', 'cli', 'api', 'webhook', 'user', 'external']
+    sources.forEach((s) => {
+      expect(RequestSourceEnum.safeParse(s).success).toBe(true)
+    })
+  })
+
+  it('rejects invalid source', () => {
+    expect(RequestSourceEnum.safeParse('bot').success).toBe(false)
+  })
+})
+
+describe('RequestTypeEnum', () => {
+  it('accepts all valid types', () => {
+    const types = ['bug', 'feature', 'question', 'other']
+    types.forEach((t) => {
+      expect(RequestTypeEnum.safeParse(t).success).toBe(true)
+    })
+  })
+
+  it('rejects invalid type', () => {
+    expect(RequestTypeEnum.safeParse('enhancement').success).toBe(false)
+  })
+})

package/src/requests/api-schemas.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod'
+
+/**
+ * Request Reporting API Schemas
+ *
+ * Request/response validation for /api/requests and /api/external/requests surfaces.
+ * Used by both the API (routes.ts, external-routes.ts) and the CLI.
+ *
+ * Table mapping:
+ *   reported_requests -> RequestSchemas
+ */
+
+// ---------------------------------------------------------------------------
+// Enum literals (must match DB CHECK constraints exactly)
+// ---------------------------------------------------------------------------
+
+export const RequestSeverityEnum = z.enum(['critical', 'warning', 'info'])
+export const RequestCategoryEnum = z.enum([
+  'ui_bug',
+  'data_inconsistency',
+  'performance',
+  'error_pattern',
+  'configuration',
+  'feature_request',
+  'api_design',
+  'documentation',
+  'integration_request',
+  'other'
+])
+export const RequestStatusEnum = z.enum(['open', 'investigating', 'resolved', 'wont_fix'])
+export const RequestSourceEnum = z.enum(['agent', 'cli', 'api', 'webhook', 'user', 'external'])
+export const RequestTypeEnum = z.enum(['bug', 'feature', 'question', 'other'])
+
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+
+/**
+ * Body for POST /api/requests and POST /api/external/requests.
+ * `source` and `organization_id` are server-set — never accepted from the client.
+ */
+export const CreateRequestInputSchema = z
+  .object({
+    type: RequestTypeEnum,
+    title: z.string().min(1),
+    description: z.string().min(1),
+    severity: RequestSeverityEnum,
+    category: RequestCategoryEnum,
+    affected_page: z.string().nullish(),
+    evidence: z.record(z.string(), z.unknown()).nullish(),
+    context: z.record(z.string(), z.unknown()).nullish(),
+    project_id: z.string().uuid().nullish(),
+    task_id: z.string().uuid().nullish()
+  })
+  .strict()
+
+export const ListRequestsQuerySchema = z.object({
+  status: RequestStatusEnum.optional(),
+  severity: RequestSeverityEnum.optional(),
+  project_id: z.string().uuid().optional(),
+  limit: z.coerce.number().int().min(1).max(200).default(50)
+})
+
+// ---------------------------------------------------------------------------
+// Bundled export (mirrors ProjectSchemas pattern)
+// ---------------------------------------------------------------------------
+
+export const RequestSchemas = {
+  CreateRequestInput: CreateRequestInputSchema,
+  ListRequestsQuery: ListRequestsQuerySchema
+}
+
+// ---------------------------------------------------------------------------
+// Inferred types
+// ---------------------------------------------------------------------------
+
+export type RequestSeverity = z.infer<typeof RequestSeverityEnum>
+export type RequestCategory = z.infer<typeof RequestCategoryEnum>
+export type RequestStatus = z.infer<typeof RequestStatusEnum>
+export type RequestSource = z.infer<typeof RequestSourceEnum>
+export type RequestType = z.infer<typeof RequestTypeEnum>
+export type CreateRequestInput = z.infer<typeof CreateRequestInputSchema>
+export type ListRequestsQuery = z.infer<typeof ListRequestsQuerySchema>

package/src/requests/index.ts

@@ -0,0 +1 @@
+export * from './api-schemas.js'