167 lines
5.0 KiB
Markdown
167 lines
5.0 KiB
Markdown
# OpenSpec Change: enterprise-wip
|
|
|
|
- **Change ID**: enterprise-wip
|
|
- **Package**: `@suaveplan/wip`
|
|
- **Category**: universal/dev
|
|
- **Target path**: `universal/dev/wip`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/wip.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/wip` on the genesis branch from scratch at enterprise quality. The package provides a work-in-progress experiments sandbox: a structured home for exploratory code, feature-flag-gated experiments, and proof-of-concept implementations that are not yet ready for a dedicated package. Genesis adds structured errors via `@suaveplan/error`, Zod schemas for experiment metadata, OTel instrumentation, `AbortSignal` on async experiments, and an `ExperimentRegistry` for tracking active experiments with lifecycle management (draft, active, graduated, abandoned).
|
|
|
|
---
|
|
|
|
## Current-state audit (genesis)
|
|
|
|
The package does not exist on genesis yet — this is a fresh build.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/error` (`workspace:^`) | Base class for `WipError`; stable error codes |
|
|
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock`, `EventBusLike` |
|
|
| `@suaveplan/events` (`workspace:^`) | Event bus for experiment lifecycle events |
|
|
| `@suaveplan/feature-flags` (`workspace:^`) | Feature-flag gating for experiments |
|
|
| `@suaveplan/logger` (`workspace:^`) | Structured logging |
|
|
| `zod` (`catalog:forms`) | Zod schemas for experiment metadata |
|
|
| `@opentelemetry/api` (`catalog:observability`) | Spans on experiment execution |
|
|
| `tslib` (`catalog:build`) | Runtime helpers |
|
|
|
|
Dev deps: `vitest`, `@vitest/coverage-istanbul` (all `catalog:testing`).
|
|
|
|
---
|
|
|
|
## Public API surface
|
|
|
|
### Core
|
|
|
|
```ts
|
|
function createExperimentRegistry(options?: ExperimentRegistryOptions): ExperimentRegistry
|
|
|
|
interface ExperimentRegistry {
|
|
register(experiment: ExperimentDefinition): void
|
|
get(id: string): ExperimentDefinition | null
|
|
list(status?: ExperimentStatus): ReadonlyArray<ExperimentDefinition>
|
|
run<T>(id: string, fn: ExperimentFn<T>, signal?: AbortSignal): Promise<ExperimentRun<T>>
|
|
graduate(id: string, targetPackage: string): void
|
|
abandon(id: string, reason: string): void
|
|
}
|
|
```
|
|
|
|
### Experiment definition
|
|
|
|
```ts
|
|
interface ExperimentDefinition {
|
|
id: string
|
|
name: string
|
|
description: string
|
|
author?: string
|
|
createdAt?: number
|
|
status: ExperimentStatus
|
|
targetPackage?: string // where this will graduate to
|
|
flagId?: string // optional feature flag gate
|
|
tags?: string[]
|
|
}
|
|
|
|
type ExperimentStatus = 'draft' | 'active' | 'graduated' | 'abandoned'
|
|
|
|
type ExperimentFn<T> = (signal?: AbortSignal) => Promise<T>
|
|
|
|
interface ExperimentRun<T> {
|
|
readonly experimentId: string
|
|
readonly result: T
|
|
readonly durationMs: number
|
|
readonly timestamp: number
|
|
}
|
|
|
|
interface ExperimentRegistryOptions {
|
|
logger?: LoggerLike
|
|
clock?: Clock
|
|
eventBus?: EventBusLike
|
|
flagManager?: unknown // FlagManager from @suaveplan/feature-flags
|
|
}
|
|
```
|
|
|
|
### Utilities
|
|
|
|
```ts
|
|
function wip<T>(description: string, fn: () => T): T
|
|
function wipAsync<T>(description: string, fn: (signal?: AbortSignal) => Promise<T>, signal?: AbortSignal): Promise<T>
|
|
function todo(message?: string): never
|
|
function notImplemented(feature: string): never
|
|
```
|
|
|
|
### Error codes
|
|
|
|
```ts
|
|
type WipErrorCode =
|
|
| 'WIP_EXPERIMENT_NOT_FOUND'
|
|
| 'WIP_EXPERIMENT_NOT_ACTIVE'
|
|
| 'WIP_FLAG_DISABLED'
|
|
| 'WIP_NOT_IMPLEMENTED'
|
|
| 'WIP_ABORT'
|
|
|
|
function registerWipErrorCodes(): void
|
|
```
|
|
|
|
---
|
|
|
|
## Genesis additions
|
|
|
|
1. **Structured `WipError`** extending `SuaveplanError` with stable `WIP.*` codes
|
|
2. **`ExperimentRegistry`** — lifecycle management for WIP experiments
|
|
3. **`wip()` / `wipAsync()` wrappers** — log a structured trace entry when entering WIP code; throw in production builds when `NODE_ENV === 'production'`
|
|
4. **`todo()` / `notImplemented()` helpers** — throw `WipError(WIP_NOT_IMPLEMENTED)` with descriptive message, never silent
|
|
5. **Feature-flag gating** — experiments can require a flag to be enabled before running
|
|
6. **Injectable `Clock`** for experiment timestamps
|
|
7. **OTel instrumentation** — span `wip.experiment.run`, counter `wip.experiments_run_total`
|
|
8. **Zod schemas** for `ExperimentDefinition`, `ExperimentRegistryOptions`
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
universal/dev/wip/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
error-codes.ts
|
|
constants/
|
|
index.ts
|
|
types/
|
|
common.ts
|
|
common.md
|
|
core/
|
|
registry/
|
|
registry.ts
|
|
registry.md
|
|
registry.types.ts
|
|
registry.test.ts
|
|
index.ts
|
|
utils/
|
|
helpers.ts
|
|
helpers.md
|
|
helpers.test.ts
|
|
tests/
|
|
integration.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
**Downstream packages**: Developer tooling only. Should never be imported from production packages — the `wip()` helper throws in production builds as a safety guard.
|
|
|
|
**Workspace dep prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/feature-flags`, `@suaveplan/logger` must be published.
|