@company-semantics/contracts 0.140.0 → 0.142.0

package/package.json

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

package/src/index.ts

@@ -619,3 +619,21 @@ export type { MutationPolicy } from './mutations'
 // Observability envelope types (shared metric shape)
 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'
+
+// Query intent vocabulary (PRD-00486 per-tier DB query timeouts + circuit breaker)
+export type { QueryIntent } from './queryIntent'
+
+// System pressure vocabulary (PRD-00489 load-shed + progressive degradation)
+export {
+  SYSTEM_PRESSURE_HEADER,
+  HEAP_SHED_PCT,
+  HEAP_CLEAR_PCT,
+  CLEAR_HOLDDOWN_MS,
+} from './pressure'
+export type { SystemPressureValue, ShedResponse } from './pressure'
+
+// Timeout ladder (PRD-00491 end-to-end timing budgets)
+export { TIMEOUT_LADDER_MS, getTimeoutForTier } from './timeouts'

package/src/pressure.ts

@@ -0,0 +1,57 @@
+/**
+ * System pressure vocabulary (PRD-00489 load-shed + progressive degradation).
+ *
+ * Canonical contract shared between backend and frontend for signalling
+ * resource pressure. The backend sets the `X-System-Pressure` response header
+ * (normal|degraded) whenever a load-shed window is active; the frontend
+ * observes the header in its fetch layer and routes the signal to a single
+ * SystemPressureProvider. Threshold constants are shared so both sides reason
+ * about the same hysteresis window.
+ *
+ * Per feedback_tenant_induced_not_503: tenant-visible shedding returns 429
+ * with the `tenant_quota_shed` body shape. Per feedback_derive_dont_duplicate
+ * the constants below are the single source of truth — do not duplicate
+ * these literals in backend or app code.
+ */
+
+/**
+ * Canonical response header used to signal system pressure to clients.
+ * Frontend imports this to avoid stringly-typed header lookups.
+ */
+export const SYSTEM_PRESSURE_HEADER = 'X-System-Pressure';
+
+/**
+ * Values carried on the `X-System-Pressure` header. `degraded` indicates the
+ * backend is actively shedding P3 traffic; `normal` indicates the controller
+ * is quiescent.
+ */
+export type SystemPressureValue = 'normal' | 'degraded';
+
+/**
+ * Heap-utilisation ratio above which the load-shed controller begins
+ * shedding new P3 traffic.
+ */
+export const HEAP_SHED_PCT = 0.75;
+
+/**
+ * Heap-utilisation ratio at or below which the controller becomes eligible
+ * to clear the shed window (paired with CLEAR_HOLDDOWN_MS).
+ */
+export const HEAP_CLEAR_PCT = 0.6;
+
+/**
+ * Hysteresis: heap pressure must remain below HEAP_CLEAR_PCT for at least
+ * this many milliseconds before the shed window clears. Prevents oscillation
+ * when heap hovers around the threshold.
+ */
+export const CLEAR_HOLDDOWN_MS = 30_000;
+
+/**
+ * Response body returned with HTTP 429 when a P3 request is shed at ingress.
+ * `retryAfter` mirrors the `Retry-After` header value (seconds).
+ */
+export type ShedResponse = {
+  error: 'tenant_quota_shed';
+  retryAfter: number;
+  reason: 'heap_pressure' | 'queue_depth';
+};

package/src/queryIntent.ts

@@ -0,0 +1,42 @@
+/**
+ * Query intent vocabulary (PRD-00486).
+ *
+ * A string-literal union naming the hot-path database reads/writes the
+ * backend currently serves. The backend's `tenantDb.query(intent, fn, opts)`
+ * wrapper uses this union to:
+ *
+ *  1. look up a per-intent budget via `budgetMsOf()` (derived from tier),
+ *  2. key the per-intent circuit breaker in
+ *     `src/server/plugins/circuit-breaker.ts`, and
+ *  3. label observability counters (`query_timeout_total{intent,tier,orgId}`,
+ *     `query_duration_ms{intent,tier}`).
+ *
+ * The tier vocabulary (P0/P1/P2/P3) is shared with PRD-00484's request
+ * scheduler (see `./requests#Tier`). Per feedback_derive_dont_duplicate the
+ * budget ceilings live in a single table in
+ * `company-semantics-backend/src/db/query-intent.ts` and are derived from
+ * tier; there is no parallel registry here. This file is the type-only
+ * authority for the intent set itself.
+ */
+export type QueryIntent =
+  | 'me.read'
+  | 'workspace.read'
+  | 'workspace.write'
+  | 'company-md.tree.read'
+  | 'company-md.doc.read'
+  | 'company-md.doc.write'
+  | 'company-md.settings.read'
+  | 'company-md.settings.write'
+  | 'chats.events'
+  | 'chats.write'
+  | 'billing.read'
+  | 'ai-usage.read'
+  | 'audit.read'
+  | 'invites.read'
+  | 'invites.write'
+  | 'integrations.status.read'
+  | 'org.transfer.status.read'
+  | 'org.deletion.eligibility.read'
+  | 'user.preferences.read'
+  | 'user.preferences.write'
+  | 'admin.impersonate.events';

package/src/sse.ts

@@ -0,0 +1,10 @@
+/**
+ * Long-lived route vocabulary (e.g. SSE / text/event-stream).
+ *
+ * Paired with the runtime decorator `longLived()` and reader `isLongLived(req)`
+ * in company-semantics-backend/src/server/plugins/long-lived.ts. Structurally
+ * disjoint from the PRD-00484 `Tier` vocabulary: a route may carry both a
+ * transactional `tier` and a `longLived` flag, but the flag selects the SSE
+ * pool (PRD-00485) instead of the transactional semaphore.
+ */
+export type LongLivedRouteOptions = { longLived: true };

package/src/timeouts.ts

@@ -0,0 +1,27 @@
+/**
+ * Timeout ladder (PRD-00491).
+ *
+ * Per-tier hard timeout ceilings shared by every enforcement layer:
+ * client fetch, scheduler, backend handler, DB query. Backend and app
+ * import from here so the ladder cannot drift between layers.
+ *
+ * Extends PRD-00486 (backend query timeouts) and PRD-00487 (client fetch
+ * timeouts) into a single coherent ladder. Per-intent DB budgets in
+ * `company-semantics-backend/src/db/query-intent.ts` are derived from
+ * these ceilings (feedback_derive_dont_duplicate).
+ *
+ * Tiers: P0 = user-blocking, P1 = interactive, P2 = background,
+ * P3 = bulk. See `./requests#Tier` for the canonical tier definition.
+ */
+import type { Tier } from './requests';
+
+export const TIMEOUT_LADDER_MS: Record<Tier, number> = {
+  P0: 2_000,
+  P1: 5_000,
+  P2: 8_000,
+  P3: 15_000,
+};
+
+export function getTimeoutForTier(tier: Tier): number {
+  return TIMEOUT_LADDER_MS[tier];
+}