@company-semantics/contracts 0.0.9 → 0.2.0

package/index.ts

@@ -20,3 +20,23 @@ export type InsightConfidence = 'low' | 'medium' | 'high'
 
 // Invariant enforcement phases (4.0 Observe → 4.1 Stabilize → 4.2 Enforce)
 export type InvariantPhase = 'observe' | 'stabilize' | 'enforce'
+
+// System diagram types (Living ASCII Diagram)
+// @see docs/LIVING_ASCII_DIAGRAM_SPEC.md
+export type {
+  // Layer-based manifest (source of truth)
+  FeatureStatus,
+  SystemCapability,
+  SystemLayer,
+  SystemCapabilityManifest,
+  // Snapshot metadata
+  SystemSnapshotMeta,
+  /** @deprecated Use DiagramSpec instead */
+  SystemSnapshot,
+  // Graph-based diagram spec (new architecture)
+  DiagramNodeKind,
+  DiagramEdgeRelation,
+  DiagramNode,
+  DiagramEdge,
+  DiagramSpec,
+} from './system/index.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "0.0.9",
+  "version": "0.2.0",
   "private": false,
   "repository": {
     "type": "git",
@@ -15,6 +15,7 @@
   "types": "./index.ts",
   "files": [
     "index.ts",
+    "system/",
     "README.md"
   ],
   "publishConfig": {

package/system/README.md

@@ -0,0 +1,46 @@
+# system/
+
+## Purpose
+
+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
+
+## Invariants
+
+- Types only — no runtime code
+- Schema changes require coordinated releases across repos
+- No render hints in contracts — renderers decide presentation independently
+- `layer` metadata is semantic grouping, not layout instruction
+
+## 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 (new architecture)
+- `DiagramNodeKind` — 'layer' | 'feature' | 'artifact'
+- `DiagramEdgeRelation` — 'contains' | 'flows_to' | 'depends_on'
+- `DiagramNode` — semantic node with optional layer grouping
+- `DiagramEdge` — semantic relationship between nodes
+- `DiagramSpec` — complete graph that crosses system boundaries
+
+### Metadata (retained for compatibility)
+- `SystemSnapshotMeta` — generation metadata
+- `SystemSnapshot` — **deprecated**, use DiagramSpec instead
+
+## Dependencies
+
+**Imports from:** (none — leaf module)
+**Imported by:** company-semantics (backend), company-semantics-site
+
+## Specification
+
+See [LIVING_ASCII_DIAGRAM_SPEC.md](../docs/LIVING_ASCII_DIAGRAM_SPEC.md) for the canonical system definition.

package/system/diagram.ts

@@ -0,0 +1,72 @@
+/**
+ * Diagram Specification Types
+ *
+ * Graph-based semantic model for system diagrams.
+ * These types define MEANING, not presentation.
+ *
+ * Key invariants:
+ * - No render hints — renderers decide presentation independently
+ * - layer metadata is semantic grouping, not layout instruction
+ * - Graphs can be rendered as ASCII, SVG, canvas, or any future format
+ *
+ * @see ../docs/LIVING_ASCII_DIAGRAM_SPEC.md
+ */
+
+import type { FeatureStatus } from './index.js'
+
+/**
+ * The semantic role of a node in the diagram.
+ */
+export type DiagramNodeKind = 'layer' | 'feature' | 'artifact'
+
+/**
+ * The semantic relationship between nodes.
+ */
+export type DiagramEdgeRelation = 'contains' | 'flows_to' | 'depends_on'
+
+/**
+ * A node in the diagram graph.
+ * Represents a semantic entity, not a visual element.
+ */
+export interface DiagramNode {
+  /** Unique identifier */
+  id: string
+  /** Human-readable label */
+  label: string
+  /** Semantic role */
+  kind: DiagramNodeKind
+  /** Feature maturity status (only for 'feature' nodes) */
+  status?: FeatureStatus
+  /** Semantic grouping (not layout instruction) */
+  layer?: string
+  /** Order within layer for pipeline semantics */
+  orderInLayer?: number
+}
+
+/**
+ * An edge connecting two nodes.
+ * Represents a semantic relationship, not a visual connector.
+ */
+export interface DiagramEdge {
+  /** Source node ID */
+  from: string
+  /** Target node ID */
+  to: string
+  /** Type of relationship */
+  relation: DiagramEdgeRelation
+}
+
+/**
+ * Complete diagram specification.
+ *
+ * This is the contract that crosses system boundaries.
+ * Backend produces it, clients consume it, renderers interpret it.
+ *
+ * IMPORTANT: No render hints. Renderers decide presentation.
+ */
+export interface DiagramSpec {
+  /** All nodes in the diagram */
+  nodes: DiagramNode[]
+  /** All edges connecting nodes */
+  edges: DiagramEdge[]
+}

package/system/index.ts

@@ -0,0 +1,106 @@
+/**
+ * System Diagram Types
+ *
+ * Schema for the Living ASCII System Diagram feature.
+ * These types define the contract between:
+ *   - company-semantics (produces semantic DiagramSpec)
+ *   - company-semantics-site (renders diagrams client-side)
+ *
+ * Architecture:
+ *   - Backend owns MEANING (DiagramSpec with nodes/edges)
+ *   - Client owns RENDERING (ASCII, SVG, etc.)
+ *   - No diagram artifacts are committed — runtime rendering only
+ *
+ * @see docs/LIVING_ASCII_DIAGRAM_SPEC.md
+ */
+
+/**
+ * Feature maturity status.
+ * Displayed as markers in the ASCII diagram:
+ *   [*] 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
+  /** Human-readable label (e.g., 'Entity Extraction') */
+  label: string
+  /** Current maturity status */
+  status: FeatureStatus
+  /** Display order within layer (lower = higher) */
+  order: number
+}
+
+/**
+ * A logical layer in the system architecture.
+ */
+export interface SystemLayer {
+  /** Unique identifier (e.g., 'semantics') */
+  id: string
+  /** Display label (e.g., 'SEMANTIC PROCESSING') */
+  label: string
+  /** Whether this layer is active */
+  enabled: boolean
+  /** Capabilities within this layer */
+  features: SystemCapability[]
+}
+
+/**
+ * Full system capability manifest.
+ * This is the TypeScript representation of capabilities.yaml
+ */
+export interface SystemCapabilityManifest {
+  /** Manifest format version */
+  version: number
+  /** Schema version string (e.g., '1.0') */
+  schema_version: string
+  /** Ordered list of system layers */
+  layers: SystemLayer[]
+}
+
+/**
+ * Metadata accompanying a generated snapshot.
+ */
+export interface SystemSnapshotMeta {
+  /** Metadata format version */
+  version: number
+  /** ISO 8601 timestamp of generation */
+  snapshotDate: string
+  /** Git commit SHA of source */
+  commitSha: string
+  /** Schema version used for generation */
+  schemaVersion: string
+  /** Visibility level (always 'public' for now) */
+  visibility: 'public'
+  /** SHA256 checksum of the ASCII content */
+  checksum?: string
+}
+
+/**
+ * Complete snapshot bundle (ASCII + metadata).
+ * @deprecated Use DiagramSpec instead. This type will be removed in a future version.
+ * ASCII rendering now happens client-side from DiagramSpec.
+ */
+export interface SystemSnapshot {
+  /** Raw ASCII diagram content */
+  ascii: string
+  /** Snapshot metadata */
+  meta: SystemSnapshotMeta
+  /** Optional explanation markdown */
+  explanation?: string
+}
+
+// Graph-based diagram types (new architecture)
+export type {
+  DiagramNodeKind,
+  DiagramEdgeRelation,
+  DiagramNode,
+  DiagramEdge,
+  DiagramSpec,
+} from './diagram.js'