@company-semantics/contracts 0.142.0 → 0.143.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.142.0",
+  "version": "0.143.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/autotune.ts

@@ -0,0 +1,90 @@
+/**
+ * Damped auto-tuning controller vocabulary (PRD-00500 a1).
+ *
+ * Replaces PRD-00496 rule 9's reactive feedback loop with a damped controller
+ * primitive that avoids oscillation. Shared by client-concurrency (app),
+ * SSE-poll-rate (app), and early-shed-threshold (backend) controllers.
+ *
+ * Bounded<Min, Max> brands a numeric range at the type level — the only way
+ * to construct one is via `bounded(min, max, v)`, which throws at runtime if
+ * `v` is outside [min, max]. Consumers use the branded type in their public
+ * surface so a controller cannot emit an out-of-range value without a
+ * compile error at the call site.
+ *
+ * The `ci:autotune-bounds` guard (PRD-00500 a6) additionally enforces that
+ * each `ControllerConfig.min`/`max` is a numeric literal, not an identifier
+ * reference, preventing drift between the declared branded range and the
+ * runtime bounds check.
+ */
+
+declare const BoundedBrand: unique symbol;
+
+/**
+ * A numeric value proven at the type level to lie within [Min, Max].
+ *
+ * Constructed only via `bounded(min, max, v)`. Direct casts are intentionally
+ * impossible from outside this module because the brand symbol is not
+ * exported.
+ */
+export type Bounded<Min extends number, Max extends number> = number & {
+  readonly [BoundedBrand]: [Min, Max];
+};
+
+/**
+ * Construct a Bounded<Min, Max> or throw RangeError at the boundary.
+ *
+ * Callers should pass `min` and `max` as literal types (`as const`) so the
+ * returned value's brand captures the compile-time range, not `number`.
+ */
+export function bounded<Min extends number, Max extends number>(
+  min: Min,
+  max: Max,
+  v: number,
+): Bounded<Min, Max> {
+  if (v < min || v > max) {
+    throw new RangeError(`value ${v} out of bounds [${min}, ${max}]`);
+  }
+  return v as Bounded<Min, Max>;
+}
+
+/**
+ * Static configuration for a damped controller instance. `min`/`max` are
+ * literal-typed so the compile-time bounds match the runtime brand.
+ */
+export type ControllerConfig<Min extends number, Max extends number> = {
+  readonly name: string;
+  readonly min: Min;
+  readonly max: Max;
+  readonly deadband: number;
+  readonly smoothingAlpha: number;
+  readonly changeCap: number;
+  readonly adjustmentWindowMs: number;
+  readonly setpoint: number;
+};
+
+/**
+ * Single controller reading: the raw measurement and the timestamp it was
+ * sampled at. Timestamps drive windowing and settling logic, so they must
+ * come from a single monotonic clock per controller instance.
+ */
+export type ControllerInput = {
+  readonly measurement: number;
+  readonly timestamp: number;
+};
+
+/**
+ * Controller step result. `value` is branded with the configured range so
+ * downstream consumers (scheduler, SSE cadence, load-shed threshold) cannot
+ * accept an unbounded number by mistake.
+ *
+ * `reason` explains why the controller produced this value:
+ * - `deadband-hold`: input is inside the deadband, no adjustment needed
+ * - `window-hold`: last adjustment was within the adjustment window
+ * - `adjusted`: a normal damped adjustment occurred
+ * - `bounded-clamp`: the desired value was clamped to [min, max]
+ */
+export type ControllerOutput<Min extends number, Max extends number> = {
+  readonly value: Bounded<Min, Max>;
+  readonly reason: 'deadband-hold' | 'window-hold' | 'adjusted' | 'bounded-clamp';
+  readonly adjustmentWindowId: string;
+};

package/src/index.ts

@@ -621,7 +621,12 @@ export { REQUEST_ID_HEADER } from './observability'
 export type { Labels, MetricEnvelope, SchedulerMetricName } from './observability'
 
 // Long-lived route vocabulary (PRD-00485 SSE / event-stream isolation)
-export type { LongLivedRouteOptions } from './sse'
+export type { LongLivedRouteOptions, LongLivedPlugin } from './sse'
+export { longLivedPlugin } from './sse'
+
+// Route builder (PRD-00499 h5): required tier + resourceKey at the type level
+export type { HttpMethod, RouteDefinition } from './route-builder'
+export { routeBuilder } from './route-builder'
 
 // Query intent vocabulary (PRD-00486 per-tier DB query timeouts + circuit breaker)
 export type { QueryIntent } from './queryIntent'
@@ -635,5 +640,22 @@ export {
 } from './pressure'
 export type { SystemPressureValue, ShedResponse } from './pressure'
 
+// Safe-mode vocabulary (PRD-00495 global freeze / circuit breaker)
+export { SYSTEM_SAFE_MODE_HEADER } from './safe-mode'
+export type { SafeModeValue, SafeModeState } from './safe-mode'
+
 // Timeout ladder (PRD-00491 end-to-end timing budgets)
 export { TIMEOUT_LADDER_MS, getTimeoutForTier } from './timeouts'
+
+// Tracing vocabulary (PRD-00497 canonical request lifecycle)
+export { LIFECYCLE_PHASES } from './tracing'
+export type { LifecyclePhase, TraceId, RequestId, TraceMetadata } from './tracing'
+
+// Damped auto-tuning controller vocabulary (PRD-00500 a1)
+export { bounded } from './autotune'
+export type {
+  Bounded,
+  ControllerConfig,
+  ControllerInput,
+  ControllerOutput,
+} from './autotune'

package/src/org/company-md.ts

@@ -53,6 +53,12 @@ export interface CompanyMdTreeNode extends CompanyMdNodeIdentity {
   readonly description?: string;
   /** Department IDs this node is associated with (for cross-team projections). */
   readonly departmentIds?: readonly string[];
+  /**
+   * Fractional-index key for stable ordering. Present on ordered entity
+   * wrappers (departments, teams, context docs); absent on wrappers for
+   * unordered types.
+   */
+  readonly orderKey?: string;
 }
 
 export interface CompanyMdDocCore extends CompanyMdNodeIdentity {

package/src/org/departments.ts

@@ -22,6 +22,7 @@ export interface Department {
   readonly slug: string;
   readonly description: string | null;
   readonly memberCount: number;
+  readonly orderKey: string;
 }
 
 /**

package/src/org/teams.ts

@@ -31,6 +31,7 @@ export interface Team {
   readonly scope: import('./departments').TeamScope;
   readonly department: { readonly id: string; readonly name: string; readonly slug: string } | null;
   readonly homeDepartment: { readonly id: string; readonly name: string; readonly slug: string } | null;
+  readonly orderKey: string;
 }
 
 /**

package/src/resource-registry.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import type { Tier } from './requests';
+
+declare const ResourceKeyBrand: unique symbol;
+declare const SectionKeyBrand: unique symbol;
+declare const DurationBrand: unique symbol;
+
+export type ResourceKey = string & { readonly [ResourceKeyBrand]: true };
+export type SectionKey = string & { readonly [SectionKeyBrand]: true };
+export type Duration = number & { readonly [DurationBrand]: true };
+
+const TIERS = ['P0', 'P1', 'P2', 'P3'] as const satisfies readonly Tier[];
+
+export const ResourceEntrySchema = z
+  .object({
+    resource: z.string().transform((s) => s as ResourceKey),
+    priority: z.enum(TIERS),
+    hydrationPhase: z.enum(['critical', 'interactive', 'background']),
+    hydrationDepends: z.array(z.string().transform((s) => s as ResourceKey)),
+    mutationBehavior: z.enum(['collapse', 'queue', 'serial']),
+    staleTimeMs: z
+      .number()
+      .int()
+      .nonnegative()
+      .transform((n) => n as Duration),
+    degradationSection: z.string().transform((s) => s as SectionKey),
+    queryBudgetMs: z
+      .number()
+      .int()
+      .positive()
+      .transform((n) => n as Duration),
+    resourceFairnessCap: z.number().int().positive(),
+  })
+  .strict();
+
+export type ResourceEntry = z.infer<typeof ResourceEntrySchema>;
+export type ResourceRegistry = ReadonlyMap<ResourceKey, ResourceEntry>;

package/src/route-builder.ts

@@ -0,0 +1,38 @@
+/**
+ * Route builder vocabulary (PRD-00499 h5).
+ *
+ * `RouteDefinition` requires `tier` and `resourceKey` at the type level —
+ * a route declaration that omits either field is a compile error, not a
+ * CI-scan warning. This replaces the PRD-00484 route-tier CI scan with a
+ * type-level constraint the compiler enforces.
+ *
+ * Fastify-agnostic on purpose (same as `sse.ts`): contracts does not
+ * depend on `fastify`. The `Handler` type parameter is bound at the
+ * backend call site to the appropriate FastifyRequest/FastifyReply
+ * signature.
+ */
+import type { Tier } from './requests';
+import type { ResourceKey } from './resource-keys';
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+export type RouteDefinition<Handler = unknown> = {
+  readonly tier: Tier;
+  readonly resourceKey: ResourceKey;
+  readonly method: HttpMethod;
+  readonly path: string;
+  readonly handler: Handler;
+};
+
+/**
+ * Identity wrapper that preserves the inferred RouteDefinition shape.
+ *
+ * The value is returned unchanged at runtime; the value exists purely to
+ * anchor type inference so that `tier` and `resourceKey` are required at
+ * every call site.
+ */
+export function routeBuilder<Handler>(
+  def: RouteDefinition<Handler>,
+): RouteDefinition<Handler> {
+  return def;
+}

package/src/safe-mode.ts

@@ -0,0 +1,48 @@
+/**
+ * Safe-mode vocabulary (PRD-00495 global freeze / circuit breaker).
+ *
+ * Canonical contract shared between backend (source of truth) and the app
+ * (frontend consumer). The backend flips a single global flag on severe
+ * anomaly (invalidation storm, retry loop, heap critical, or manual admin
+ * action) and surfaces it through the `X-System-Safe-Mode` response header
+ * on every response. The app observes the header in its fetch layer and
+ * routes the signal to a single SafeModeProvider.
+ *
+ * Per feedback_env_var_bypasses_are_backdoors: the flag is never settable
+ * via environment variable — only via authenticated admin route.
+ *
+ * Per feedback_single_instrumentation_layer: the state is read through a
+ * single module (backend) and a single context (app). Do not duplicate.
+ */
+
+/**
+ * Canonical response header signalling safe-mode state to clients.
+ * Frontend imports this to avoid stringly-typed header lookups.
+ */
+export const SYSTEM_SAFE_MODE_HEADER = 'X-System-Safe-Mode';
+
+/**
+ * Values carried on the `X-System-Safe-Mode` header.
+ * `on` indicates the backend has entered safe-mode and is rejecting all
+ * non-P0 traffic with 503. `off` is the normal quiescent state.
+ */
+export type SafeModeValue = 'on' | 'off';
+
+/**
+ * Observable safe-mode state. Shared verbatim between backend (source of
+ * truth, in-memory) and frontend (consumed via admin endpoint).
+ *
+ * - `active`: whether safe-mode is currently engaged
+ * - `reason`: human-readable reason for the current state, or null when
+ *   inactive. Surfaced on the banner.
+ * - `since`: epoch ms when the current active period began, or null when
+ *   inactive.
+ * - `autoTriggered`: true if the current active period was engaged by the
+ *   error-rate threshold watcher; false if engaged by a human admin.
+ */
+export type SafeModeState = {
+  active: boolean;
+  reason: string | null;
+  since: number | null;
+  autoTriggered: boolean;
+};

package/src/sse.ts

@@ -8,3 +8,31 @@
  * pool (PRD-00485) instead of the transactional semaphore.
  */
 export type LongLivedRouteOptions = { longLived: true };
+
+/**
+ * LongLivedPlugin brand (PRD-00499 h4).
+ *
+ * A branded type that can only be produced by `longLivedPlugin(fn)`. The SSE
+ * plugin registration surface in company-semantics-backend accepts only
+ * `LongLivedPlugin<T>` — passing an unbranded Fastify plugin is a compile
+ * error. This replaces the scan-based @longLived CI check with a type-level
+ * constraint the compiler enforces.
+ *
+ * Fastify-agnostic on purpose: contracts does not depend on `fastify`. The
+ * `Plugin` type parameter is bound at the backend call site to the appropriate
+ * FastifyPluginAsync signature.
+ */
+declare const LongLivedBrand: unique symbol;
+export type LongLivedPlugin<Plugin> = Plugin & { readonly [LongLivedBrand]: true };
+
+/**
+ * Brand a Fastify plugin as long-lived (SSE-capable).
+ *
+ * The backing symbol is compile-time only; runtime behavior is identity.
+ * A function that opts into long-lived registration must funnel through this
+ * helper — producing a `LongLivedPlugin<T>` directly requires access to the
+ * brand symbol, which is declared-only.
+ */
+export function longLivedPlugin<Plugin>(fn: Plugin): LongLivedPlugin<Plugin> {
+  return fn as LongLivedPlugin<Plugin>;
+}

package/src/tracing.ts

@@ -0,0 +1,77 @@
+/**
+ * Tracing vocabulary (PRD-00497 canonical request lifecycle).
+ *
+ * Structural types that make the runtime phase-boundary assertion possible.
+ * Every phase chokepoint in the app (see ADR-CTRL-064) accepts `TraceMetadata`
+ * whose `phase` field equals the expected phase for that chokepoint. The 10
+ * phases in `LIFECYCLE_PHASES` are the single source of truth — do not
+ * redefine this list elsewhere (per memory feedback_derive_dont_duplicate).
+ *
+ * `TraceId` and `RequestId` are branded strings: at runtime they are plain
+ * strings, but the type system prevents accidental swapping or construction
+ * from unbranded literals.
+ *
+ * @see decisions/ADR-CTRL-NNN-request-lifecycle.md in company-semantics-control
+ * @see src/lib/tracing/assert-phase-metadata.ts in company-semantics-app
+ */
+
+/**
+ * Canonical request lifecycle phases, in order. Every request flows through
+ * these phases from intent capture to UI render. Each phase has exactly one
+ * chokepoint file in the app that asserts `TraceMetadata.phase` matches.
+ */
+export type LifecyclePhase =
+  | 'intent'
+  | 'scheduler'
+  | 'mutation-layer'
+  | 'dedupe'
+  | 'concurrency-gate'
+  | 'retry'
+  | 'backend-backpressure'
+  | 'versioning'
+  | 'cache-apply'
+  | 'render'
+
+declare const TraceIdBrand: unique symbol
+declare const RequestIdBrand: unique symbol
+
+/**
+ * Branded trace identifier. Stable across all phases of a single user-visible
+ * interaction (may span multiple requests on retry).
+ */
+export type TraceId = string & { readonly [TraceIdBrand]: true }
+
+/**
+ * Branded request identifier. Unique per outgoing request; does NOT rotate
+ * across retries of the same logical intent.
+ */
+export type RequestId = string & { readonly [RequestIdBrand]: true }
+
+/**
+ * Tracing metadata carried through every phase boundary. `phase` must match
+ * the expected phase for the chokepoint receiving this metadata; `parentPhase`
+ * (if present) must be an earlier phase in `LIFECYCLE_PHASES`.
+ */
+export type TraceMetadata = {
+  readonly traceId: TraceId
+  readonly requestId: RequestId
+  readonly phase: LifecyclePhase
+  readonly parentPhase?: LifecyclePhase
+}
+
+/**
+ * Ordered list of the 10 canonical lifecycle phases. Consumers may derive a
+ * phase-index map from this array; do not maintain a parallel list.
+ */
+export const LIFECYCLE_PHASES: readonly LifecyclePhase[] = [
+  'intent',
+  'scheduler',
+  'mutation-layer',
+  'dedupe',
+  'concurrency-gate',
+  'retry',
+  'backend-backpressure',
+  'versioning',
+  'cache-apply',
+  'render',
+]