@company-semantics/contracts 9.0.0 → 9.2.0

package/src/security/org-secrets.ts

@@ -12,13 +12,17 @@
  * Server is expected to wrap incoming `plaintext` in `Secret<T>` (see
  * `./secret.ts`) before storage / encryption.
  */
-import { z } from 'zod';
+import { z } from "zod";
 
 /**
  * Usage class of an org secret. Drives which resolver layer is allowed to read
  * the value (AI provider keys, webhook signing secrets, generic credentials).
  */
-export const UsageClassSchema = z.enum(['AI_PROVIDER', 'WEBHOOK_SIGNING', 'GENERIC']);
+export const UsageClassSchema = z.enum([
+  "AI_PROVIDER",
+  "WEBHOOK_SIGNING",
+  "GENERIC",
+]);
 export type UsageClass = z.infer<typeof UsageClassSchema>;
 
 /**
@@ -27,13 +31,13 @@ export type UsageClass = z.infer<typeof UsageClassSchema>;
  * signals (`access_denied`, `explicit_export`, `unusual_access`).
  */
 export const OrgSecretsActionSchema = z.enum([
-  'created',
-  'rotated',
-  'disabled',
-  'enabled',
-  'access_denied',
-  'explicit_export',
-  'unusual_access',
+  "created",
+  "rotated",
+  "disabled",
+  "enabled",
+  "access_denied",
+  "explicit_export",
+  "unusual_access",
 ]);
 export type OrgSecretsAction = z.infer<typeof OrgSecretsActionSchema>;
 

package/src/security/secret.ts

@@ -24,15 +24,15 @@ class SecretValue<T> {
   }
 
   toString(): string {
-    return '[REDACTED]';
+    return "[REDACTED]";
   }
 
   toJSON(): string {
-    return '[REDACTED]';
+    return "[REDACTED]";
   }
 
   [Symbol.toPrimitive](): string {
-    return '[REDACTED]';
+    return "[REDACTED]";
   }
 }
 

package/src/sse.ts

@@ -23,7 +23,9 @@ export type LongLivedRouteOptions = { longLived: true };
  * FastifyPluginAsync signature.
  */
 declare const LongLivedBrand: unique symbol;
-export type LongLivedPlugin<Plugin> = Plugin & { readonly [LongLivedBrand]: true };
+export type LongLivedPlugin<Plugin> = Plugin & {
+  readonly [LongLivedBrand]: true;
+};
 
 /**
  * Brand a Fastify plugin as long-lived (SSE-capable).

package/src/system/README.md

@@ -6,6 +6,7 @@ TypeScript types for the Living ASCII System Diagram feature.
 Defines the semantic contract between backend (producer) and site (renderer).
 
 **Key architecture:**
+
 - Backend owns MEANING (produces `DiagramSpec` with nodes/edges)
 - Client owns RENDERING (ASCII, SVG, canvas, etc.)
 - No diagram artifacts committed — runtime rendering only
@@ -20,12 +21,14 @@ Defines the semantic contract between backend (producer) and site (renderer).
 ## Public API
 
 ### Source model (layer-based)
+
 - `FeatureStatus` — 'prod' | 'experimental' | 'disabled'
 - `SystemCapability` — individual feature definition
 - `SystemLayer` — logical layer grouping
 - `SystemCapabilityManifest` — full manifest structure (YAML representation)
 
 ### Diagram graph
+
 - `DiagramNodeKind` — 'layer' | 'feature' | 'artifact'
 - `DiagramEdgeRelation` — 'contains' | 'flows_to' | 'depends_on'
 - `DiagramNode` — semantic node with optional layer grouping

package/src/system/capabilities.ts

@@ -15,7 +15,7 @@
  * @see ADR-CONTRACTS-NNN in DECISIONS.md
  */
 
-import type { DiagramNode, FlowStage } from './index'
+import type { DiagramNode, FlowStage } from "./index";
 
 // =============================================================================
 // Types
@@ -26,13 +26,13 @@ import type { DiagramNode, FlowStage } from './index'
  * Add new repos here as the system grows.
  */
 export type RepoId =
-  | 'backend'
-  | 'edge'
-  | 'app'
-  | 'site'
-  | 'ci'
-  | 'contracts'
-  | 'control'
+  | "backend"
+  | "edge"
+  | "app"
+  | "site"
+  | "ci"
+  | "contracts"
+  | "control";
 
 /**
  * Semantic invariants for a capability.
@@ -40,13 +40,13 @@ export type RepoId =
  */
 export interface CapabilityInvariants {
   /** Does this capability invoke LLM/AI APIs? */
-  llmCalls: boolean
+  llmCalls: boolean;
 
   /** Is this an authority boundary (trust/gateway)? */
-  authority: boolean
+  authority: boolean;
 
   /** Can this capability write to strategy/goals? */
-  writesStrategy: boolean
+  writesStrategy: boolean;
 }
 
 /**
@@ -63,21 +63,21 @@ export interface RepoCapability extends DiagramNode {
    * Which repository owns this capability.
    * Used for aggregation grouping and validation.
    */
-  repo: RepoId
+  repo: RepoId;
 
   /**
    * Whether this capability should appear in public diagrams.
    * - true: visible on marketing site, docs
    * - false: internal only, visible in app
    */
-  public: boolean
+  public: boolean;
 
   /**
    * Architecture layer for horizontal organization.
    * Required for repo-level nodes. The primary organizing axis.
    * Children inherit unless explicitly overridden.
    */
-  flowStage?: FlowStage
+  flowStage?: FlowStage;
 
   /**
    * Stage-level edges for flow projection.
@@ -85,20 +85,20 @@ export interface RepoCapability extends DiagramNode {
    *
    * Example: ['backend:semantic:processing', 'backend:graph:storage']
    */
-  flowsTo?: string[]
+  flowsTo?: string[];
 
   /**
    * Whether this capability is exported at the architecture level.
    * Exported capabilities represent repo boundaries and API surfaces.
    * Visible in 'architecture' mode.
    */
-  exported?: boolean
+  exported?: boolean;
 
   /**
    * Semantic invariants for CI validation.
    * Optional - defaults applied per-repo during aggregation.
    */
-  invariants?: Partial<CapabilityInvariants>
+  invariants?: Partial<CapabilityInvariants>;
 }
 
 /**
@@ -111,10 +111,10 @@ export interface RepoCapability extends DiagramNode {
  */
 export interface CapabilityManifest {
   /** Which repository this manifest is from */
-  repo: RepoId
+  repo: RepoId;
 
   /** All capabilities declared by this repo */
-  capabilities: RepoCapability[]
+  capabilities: RepoCapability[];
 }
 
 /**
@@ -123,12 +123,11 @@ export interface CapabilityManifest {
  */
 export interface AggregatedCapabilities {
   /** All capabilities from all repos, validated */
-  capabilities: RepoCapability[]
+  capabilities: RepoCapability[];
 
   /** Which repos contributed to this aggregation */
-  repos: RepoId[]
+  repos: RepoId[];
 
   /** ISO timestamp of aggregation */
-  aggregatedAt: string
+  aggregatedAt: string;
 }
-

package/src/system/diagram.ts

@@ -38,13 +38,13 @@
  * - Added DiagramSnapshot for cross-repo distribution
  */
 
-import type { FeatureStatus } from './index'
+import type { FeatureStatus } from "./index";
 
 /**
  * The semantic role of a node in the diagram.
  * v0.18.0: Added 'repo' for repository-level containment
  */
-export type DiagramNodeKind = 'repo' | 'group' | 'feature' | 'artifact'
+export type DiagramNodeKind = "repo" | "group" | "feature" | "artifact";
 
 /**
  * The semantic relationship between nodes.
@@ -59,12 +59,12 @@ export type DiagramNodeKind = 'repo' | 'group' | 'feature' | 'artifact'
  * - feedback: Bidirectional loop
  */
 export type DiagramEdgeRelation =
-  | 'invokes'
-  | 'emits'
-  | 'authorizes'
-  | 'reads'
-  | 'depends_on'
-  | 'feedback'
+  | "invokes"
+  | "emits"
+  | "authorizes"
+  | "reads"
+  | "depends_on"
+  | "feedback";
 
 /**
  * Edge direction semantics.
@@ -72,7 +72,7 @@ export type DiagramEdgeRelation =
  *
  * v0.18.0: New type for explicit directionality
  */
-export type EdgeDirection = 'forward' | 'backward' | 'bidirectional'
+export type EdgeDirection = "forward" | "backward" | "bidirectional";
 
 /**
  * Architecture layers for horizontal organization.
@@ -81,12 +81,12 @@ export type EdgeDirection = 'forward' | 'backward' | 'bidirectional'
  * v0.18.0: Renamed from processing-pipeline to architecture-layer semantics
  */
 export type FlowStage =
-  | 'clients'     // CLIENTS (ALL MCP CONSUMERS)
-  | 'authority'   // MCP AUTHORITY & TOOL GATEWAY
-  | 'truth'       // SEMANTIC TRUTH, STRATEGY, & EVIDENCE (AWS)
-  | 'edge'        // EDGE INGESTION & MCP ADAPTERS
-  | 'evaluation'  // EVALUATION, GUIDANCE, & AGENTS (MCP)
-  | 'governance'  // CI / GOVERNANCE
+  | "clients" // CLIENTS (ALL MCP CONSUMERS)
+  | "authority" // MCP AUTHORITY & TOOL GATEWAY
+  | "truth" // SEMANTIC TRUTH, STRATEGY, & EVIDENCE (AWS)
+  | "edge" // EDGE INGESTION & MCP ADAPTERS
+  | "evaluation" // EVALUATION, GUIDANCE, & AGENTS (MCP)
+  | "governance"; // CI / GOVERNANCE
 
 /**
  * Data lifecycle phase for coloring/filtering.
@@ -95,12 +95,12 @@ export type FlowStage =
  * v0.19.0: New type for pipeline visualization
  */
 export type PipelinePhase =
-  | 'source'     // External data origin
-  | 'ingest'     // Data collection and intake
-  | 'normalize'  // Schema alignment and transformation
-  | 'evaluate'   // Analysis and decision-making
-  | 'store'      // Persistence and retrieval
-  | 'surface'    // Presentation and delivery
+  | "source" // External data origin
+  | "ingest" // Data collection and intake
+  | "normalize" // Schema alignment and transformation
+  | "evaluate" // Analysis and decision-making
+  | "store" // Persistence and retrieval
+  | "surface"; // Presentation and delivery
 
 /**
  * Diagram projection modes.
@@ -109,10 +109,10 @@ export type PipelinePhase =
  * v0.18.0: New type for multi-view diagrams
  */
 export type DiagramMode =
-  | 'file'         // Future: file-level (not implemented)
-  | 'capability'   // All capabilities visible
-  | 'repo'         // Repo containers + direct children only
-  | 'architecture' // Repo + exported capabilities only
+  | "file" // Future: file-level (not implemented)
+  | "capability" // All capabilities visible
+  | "repo" // Repo containers + direct children only
+  | "architecture"; // Repo + exported capabilities only
 
 /**
  * A node in the diagram graph.
@@ -120,21 +120,21 @@ export type DiagramMode =
  */
 export interface DiagramNode {
   /** Unique identifier */
-  id: string
+  id: string;
   /** Human-readable label */
-  label: string
+  label: string;
   /** Semantic role */
-  kind: DiagramNodeKind
+  kind: DiagramNodeKind;
   /** Parent node ID for tree hierarchy (replaces layer field) */
-  parentId?: string
+  parentId?: string;
   /** Order within parent for pipeline semantics */
-  order?: number
+  order?: number;
   /** Whether this node can receive focus in interactive renderers */
-  focusable?: boolean
+  focusable?: boolean;
   /** Feature maturity status (only for 'feature' nodes) */
-  status?: FeatureStatus
+  status?: FeatureStatus;
   /** Opaque metadata — engine interprets, contracts stay neutral */
-  meta?: Record<string, unknown>
+  meta?: Record<string, unknown>;
 }
 
 /**
@@ -145,11 +145,11 @@ export interface DiagramNode {
  */
 export interface DiagramEdge {
   /** Source node ID */
-  from: string
+  from: string;
   /** Target node ID */
-  to: string
+  to: string;
   /** Type of relationship */
-  relation: DiagramEdgeRelation
+  relation: DiagramEdgeRelation;
   /**
    * Direction semantics for authority.
    * - forward: Can only be updated from source (most common)
@@ -158,7 +158,7 @@ export interface DiagramEdge {
    *
    * Defaults to 'forward' if not specified.
    */
-  direction?: EdgeDirection
+  direction?: EdgeDirection;
 }
 
 /**
@@ -171,9 +171,9 @@ export interface DiagramEdge {
  */
 export interface DiagramSpec {
   /** All nodes in the diagram */
-  nodes: DiagramNode[]
+  nodes: DiagramNode[];
   /** All edges connecting nodes */
-  edges: DiagramEdge[]
+  edges: DiagramEdge[];
 }
 
 /**
@@ -186,15 +186,15 @@ export interface DiagramSpec {
  */
 export interface DiagramSnapshot {
   /** Semantic nodes for interactive features */
-  nodes: DiagramNode[]
+  nodes: DiagramNode[];
   /** ISO timestamp when snapshot was generated */
-  generatedAt: string
+  generatedAt: string;
   /** Version of the source manifest (stringified for stability) */
-  manifestVersion: string
+  manifestVersion: string;
   /** Schema version for forward compatibility */
-  specVersion: 'v1'
+  specVersion: "v1";
   /** Files this snapshot will write (manifest-driven automation) */
-  generatedFiles: string[]
+  generatedFiles: string[];
   /** Generator identity for provenance and per-generator policy (v0.6.0) */
-  generatorId?: string
+  generatorId?: string;
 }

package/src/system/index.ts

@@ -24,20 +24,20 @@
 /**
  * Feature maturity status.
  */
-export type FeatureStatus = 'prod' | 'experimental' | 'disabled'
+export type FeatureStatus = "prod" | "experimental" | "disabled";
 
 /**
  * A single capability within a system layer.
  */
 export interface SystemCapability {
   /** Unique identifier (e.g., 'entity_extraction') */
-  id: string
+  id: string;
   /** Human-readable label (e.g., 'Entity Extraction') */
-  label: string
+  label: string;
   /** Current maturity status */
-  status: FeatureStatus
+  status: FeatureStatus;
   /** Display order within layer (lower = higher) */
-  order: number
+  order: number;
 }
 
 /**
@@ -45,13 +45,13 @@ export interface SystemCapability {
  */
 export interface SystemLayer {
   /** Unique identifier (e.g., 'semantics') */
-  id: string
+  id: string;
   /** Display label (e.g., 'SEMANTIC PROCESSING') */
-  label: string
+  label: string;
   /** Whether this layer is active */
-  enabled: boolean
+  enabled: boolean;
   /** Capabilities within this layer */
-  features: SystemCapability[]
+  features: SystemCapability[];
 }
 
 /**
@@ -60,11 +60,11 @@ export interface SystemLayer {
  */
 export interface SystemCapabilityManifest {
   /** Manifest format version */
-  version: number
+  version: number;
   /** Schema version string (e.g., '1.0') */
-  schema_version: string
+  schema_version: string;
   /** Ordered list of system layers */
-  layers: SystemLayer[]
+  layers: SystemLayer[];
 }
 
 // Graph-based diagram types
@@ -79,7 +79,7 @@ export type {
   DiagramEdge,
   DiagramSpec,
   DiagramSnapshot,
-} from './diagram'
+} from "./diagram";
 
 // Repository capability types
 export type {
@@ -88,4 +88,4 @@ export type {
   RepoCapability,
   CapabilityManifest,
   AggregatedCapabilities,
-} from './capabilities'
+} from "./capabilities";

package/src/tiers.ts

@@ -1 +1 @@
-export type { Tier } from './requests';
+export type { Tier } from "./requests";

package/src/timeouts.ts

@@ -13,7 +13,7 @@
  * Tiers: P0 = user-blocking, P1 = interactive, P2 = background,
  * P3 = bulk. See `./requests#Tier` for the canonical tier definition.
  */
-import type { Tier } from './requests';
+import type { Tier } from "./requests";
 
 export const TIMEOUT_LADDER_MS: Record<Tier, number> = {
   P0: 2_000,

package/src/tracing.ts

@@ -21,31 +21,31 @@
  * 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'
+  | "intent"
+  | "scheduler"
+  | "mutation-layer"
+  | "dedupe"
+  | "concurrency-gate"
+  | "retry"
+  | "backend-backpressure"
+  | "versioning"
+  | "cache-apply"
+  | "render";
 
-declare const TraceIdBrand: unique symbol
-declare const RequestIdBrand: unique symbol
+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 }
+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 }
+export type RequestId = string & { readonly [RequestIdBrand]: true };
 
 /**
  * Tracing metadata carried through every phase boundary. `phase` must match
@@ -53,25 +53,25 @@ export type RequestId = string & { readonly [RequestIdBrand]: true }
  * (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
-}
+  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',
-]
+  "intent",
+  "scheduler",
+  "mutation-layer",
+  "dedupe",
+  "concurrency-gate",
+  "retry",
+  "backend-backpressure",
+  "versioning",
+  "cache-apply",
+  "render",
+];

package/src/types/analytics.ts

@@ -4,7 +4,7 @@
  *
  * See ADR-CTRL-053 for the full analytics separation decision framework.
  */
-export type AnalyticsBackend = 'clickhouse';
+export type AnalyticsBackend = "clickhouse";
 
 /**
  * Metadata included in every analytics-backed API response.
@@ -16,7 +16,7 @@ export interface AnalyticsResponseMeta {
   /** Replication lag from OLTP in milliseconds. 0 when source is 'oltp'. */
   readonly dataFreshnessMs: number;
   /** Which backend served this response. */
-  readonly source: 'oltp' | 'olap';
+  readonly source: "oltp" | "olap";
   /** ISO 8601 timestamp: when the data was current as of. */
   readonly timestamp: string;
 }

package/src/usage/README.md

@@ -16,16 +16,19 @@ Defines shared types for two usage tracking layers: (1) low-level AI usage event
 ## Public API
 
 **AI Usage Types (`types.ts`):**
+
 - `AiFeature` — Feature categories: `chat`, `chat_title`, `ingest_summarize`, `ingest_embedding`, `goal_extraction`
 - `UsageSummary`, `DailyUsage`, `UsageByModel`, `UsageByFeature`, `UsageByUser` — Aggregation response shapes
 - `UnifiedUsageResponse` and related interfaces — Combined usage dashboard response
 
 **Execution Telemetry (`execution-types.ts`):**
+
 - `RuntimeExecutionTelemetry` — Per-execution record (tokens, cost, duration, profile, success)
 - `ExecutionFailureReason` — Failure categories: `tool_error`, `timeout`, `model_error`, `budget_exceeded`, `client_disconnect`, `unknown`
 - `OrgExecutionSummary`, `DailyExecutionStats`, `ExecutionByUser`, `ExecutionDetail`, `ProfileStats` — Aggregation shapes
 
 **Budget Governance (`execution-types.ts`):**
+
 - `BudgetCheck` — Pre-execution budget gate result
 - `OrgBudgetSettings` — Org budget configuration shape