@clossys/architect 0.1.2

package/src/ontology/validate.ts

@@ -0,0 +1,208 @@
+import { PRIMITIVE_VALUE_TYPES, RELATION_CARDINALITIES } from "./types.js";
+import type { DomainModelFinding, FieldDefinition } from "./types.js";
+
+type RecordValue = Record<string, unknown>;
+
+function isRecord(value: unknown): value is RecordValue {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function finding(rule: string, message: string, path: string): DomainModelFinding {
+  return { rule, severity: "error", message, path };
+}
+
+function arrayAt(record: RecordValue, key: string, findings: DomainModelFinding[], path: string): unknown[] {
+  const value = record[key];
+  if (value === undefined) return [];
+  if (Array.isArray(value)) return value;
+  findings.push(finding("collection-shape", `${key} must be an array when provided.`, path));
+  return [];
+}
+
+function stringAt(record: RecordValue, key: string, findings: DomainModelFinding[], path: string): string | undefined {
+  const value = record[key];
+  if (typeof value === "string" && value.length > 0) return value;
+  findings.push(finding("required-string", `${key} must be a non-empty string.`, path));
+  return undefined;
+}
+
+function optionalLabel(record: RecordValue, findings: DomainModelFinding[], path: string): void {
+  if (record.label !== undefined && typeof record.label !== "string") {
+    findings.push(finding("label-shape", "label must be a string when provided.", path));
+  }
+}
+
+function isPrimitive(value: unknown): boolean {
+  return typeof value === "string" && (PRIMITIVE_VALUE_TYPES as readonly string[]).includes(value);
+}
+
+function isCardinality(value: unknown): boolean {
+  return typeof value === "string" && (RELATION_CARDINALITIES as readonly string[]).includes(value);
+}
+
+function hasNamespace(id: string, modelId: string): boolean {
+  return id.startsWith(`${modelId}.`) && id.length > modelId.length + 1;
+}
+
+function isStableId(id: string): boolean {
+  return /^[a-z][a-z0-9-]*(?:\.[A-Za-z][A-Za-z0-9_-]*)+$/.test(id);
+}
+
+function validateStableId(
+  id: string | undefined,
+  modelId: string | undefined,
+  findings: DomainModelFinding[],
+  path: string,
+  expectedPrefix?: string,
+): void {
+  if (id === undefined) return;
+  if (!isStableId(id)) {
+    findings.push(finding("stable-id-shape", "id must be a dotted, namespaced identifier.", path));
+  }
+  if (modelId !== undefined && !hasNamespace(id, modelId)) {
+    findings.push(finding("stable-id-namespace", `id must begin with "${modelId}.".`, path));
+  }
+  if (expectedPrefix !== undefined && !id.startsWith(`${expectedPrefix}.`)) {
+    findings.push(finding("field-parent", `id must begin with "${expectedPrefix}.".`, path));
+  }
+}
+
+function validateFields(
+  fields: unknown[],
+  fieldName: "fields" | "properties",
+  ownerId: string | undefined,
+  modelId: string | undefined,
+  knownValueIds: Set<string>,
+  findings: DomainModelFinding[],
+  path: string,
+): void {
+  const ids = new Set<string>();
+  fields.forEach((candidate, index) => {
+    const fieldPath = `${path}.${fieldName}[${index}]`;
+    if (!isRecord(candidate)) {
+      findings.push(finding("field-shape", "A field must be an object.", fieldPath));
+      return;
+    }
+    const id = stringAt(candidate, "id", findings, `${fieldPath}.id`);
+    validateStableId(id, modelId, findings, `${fieldPath}.id`, ownerId);
+    if (id !== undefined) {
+      if (ids.has(id)) findings.push(finding("duplicate-field-id", `Duplicate field id "${id}".`, `${fieldPath}.id`));
+      ids.add(id);
+    }
+    const valueType = stringAt(candidate, "valueType", findings, `${fieldPath}.valueType`);
+    if (valueType !== undefined && !isPrimitive(valueType) && !knownValueIds.has(valueType)) {
+      findings.push(finding("unknown-value-type", `valueType "${valueType}" does not reference a primitive, value type, or vocabulary.`, `${fieldPath}.valueType`));
+    }
+    if (candidate.required !== undefined && typeof candidate.required !== "boolean") {
+      findings.push(finding("required-shape", "required must be a boolean when provided.", `${fieldPath}.required`));
+    }
+    optionalLabel(candidate, findings, `${fieldPath}.label`);
+  });
+}
+
+/**
+ * Validates real definitions rather than a consumer-provided success flag.
+ * It never throws for malformed input and reports every independently
+ * checkable structural and referential finding.
+ */
+export function validateDomainModel(value: unknown): DomainModelFinding[] {
+  const findings: DomainModelFinding[] = [];
+  if (!isRecord(value)) return [finding("model-shape", "A domain model must be an object.", "$")];
+
+  const modelId = stringAt(value, "id", findings, "id");
+  if (modelId !== undefined && !/^[a-z][a-z0-9-]*$/.test(modelId)) {
+    findings.push(finding("model-id-shape", "id must be a lowercase namespace token.", "id"));
+  }
+  stringAt(value, "schemaVersion", findings, "schemaVersion");
+
+  const valueTypes = arrayAt(value, "valueTypes", findings, "valueTypes");
+  const vocabularies = arrayAt(value, "vocabularies", findings, "vocabularies");
+  const types = arrayAt(value, "types", findings, "types");
+  const relations = arrayAt(value, "relations", findings, "relations");
+
+  const knownValueIds = new Set<string>();
+  const allNamedIds = new Set<string>();
+  const recordNamed = (id: string | undefined, kind: string, path: string, isValueReference = false): void => {
+    if (id === undefined) return;
+    if (allNamedIds.has(id)) findings.push(finding("duplicate-id", `Duplicate ${kind} id "${id}".`, path));
+    allNamedIds.add(id);
+    if (isValueReference) knownValueIds.add(id);
+  };
+
+  valueTypes.forEach((candidate, index) => {
+    const path = `valueTypes[${index}]`;
+    if (!isRecord(candidate)) {
+      findings.push(finding("value-type-shape", "A value type must be an object.", path));
+      return;
+    }
+    const id = stringAt(candidate, "id", findings, `${path}.id`);
+    validateStableId(id, modelId, findings, `${path}.id`);
+    recordNamed(id, "value type", `${path}.id`, true);
+    if (!isPrimitive(candidate.primitive)) findings.push(finding("primitive-known", "primitive must be a known primitive value type.", `${path}.primitive`));
+    optionalLabel(candidate, findings, `${path}.label`);
+  });
+
+  vocabularies.forEach((candidate, index) => {
+    const path = `vocabularies[${index}]`;
+    if (!isRecord(candidate)) {
+      findings.push(finding("vocabulary-shape", "A vocabulary must be an object.", path));
+      return;
+    }
+    const id = stringAt(candidate, "id", findings, `${path}.id`);
+    validateStableId(id, modelId, findings, `${path}.id`);
+    recordNamed(id, "vocabulary", `${path}.id`, true);
+    const values = arrayAt(candidate, "values", findings, `${path}.values`);
+    const seen = new Set<string>();
+    values.forEach((entry, valueIndex) => {
+      if (typeof entry !== "string" || entry.length === 0) {
+        findings.push(finding("vocabulary-value-shape", "Vocabulary values must be non-empty strings.", `${path}.values[${valueIndex}]`));
+      } else if (seen.has(entry)) {
+        findings.push(finding("duplicate-vocabulary-value", `Duplicate vocabulary value "${entry}".`, `${path}.values[${valueIndex}]`));
+      } else seen.add(entry);
+    });
+    optionalLabel(candidate, findings, `${path}.label`);
+  });
+
+  const typeIds = new Set<string>();
+  types.forEach((candidate, index) => {
+    const path = `types[${index}]`;
+    if (!isRecord(candidate)) {
+      findings.push(finding("type-shape", "A domain type must be an object.", path));
+      return;
+    }
+    const id = stringAt(candidate, "id", findings, `${path}.id`);
+    validateStableId(id, modelId, findings, `${path}.id`);
+    if (id !== undefined) {
+      if (typeIds.has(id)) findings.push(finding("duplicate-type-id", `Duplicate type id "${id}".`, `${path}.id`));
+      typeIds.add(id);
+    }
+    recordNamed(id, "type", `${path}.id`);
+    validateFields(arrayAt(candidate, "fields", findings, `${path}.fields`), "fields", id, modelId, knownValueIds, findings, path);
+    optionalLabel(candidate, findings, `${path}.label`);
+  });
+
+  const relationIds = new Set<string>();
+  relations.forEach((candidate, index) => {
+    const path = `relations[${index}]`;
+    if (!isRecord(candidate)) {
+      findings.push(finding("relation-shape", "A relation must be an object.", path));
+      return;
+    }
+    const id = stringAt(candidate, "id", findings, `${path}.id`);
+    validateStableId(id, modelId, findings, `${path}.id`);
+    if (id !== undefined) {
+      if (relationIds.has(id)) findings.push(finding("duplicate-relation-id", `Duplicate relation id "${id}".`, `${path}.id`));
+      relationIds.add(id);
+    }
+    recordNamed(id, "relation", `${path}.id`);
+    const from = stringAt(candidate, "from", findings, `${path}.from`);
+    const to = stringAt(candidate, "to", findings, `${path}.to`);
+    if (from !== undefined && !typeIds.has(from)) findings.push(finding("relation-from-known", `from endpoint "${from}" does not reference a type.`, `${path}.from`));
+    if (to !== undefined && !typeIds.has(to)) findings.push(finding("relation-to-known", `to endpoint "${to}" does not reference a type.`, `${path}.to`));
+    if (!isCardinality(candidate.cardinality)) findings.push(finding("relation-cardinality-known", "cardinality must be a supported relation cardinality.", `${path}.cardinality`));
+    validateFields(arrayAt(candidate, "properties", findings, `${path}.properties`), "properties", id, modelId, knownValueIds, findings, path);
+    optionalLabel(candidate, findings, `${path}.label`);
+  });
+
+  return findings;
+}

package/src/topology.ts

@@ -0,0 +1,211 @@
+import {
+  OPERATING_RESPONSIBILITIES,
+  OPERATING_SCOPE_KINDS,
+  OPERATING_SYSTEM_KINDS,
+  type ArchitectureFinding,
+  type AuthorityDefinition,
+  type OperatingInterfaceDefinition,
+  type OperatingSystemDefinition,
+  type OperatingTopology,
+  type OperatingTopologyCompatibilityReport,
+  type OperatingTopologyDefinition,
+  type OperatingTopologyChange,
+} from "./types.js";
+
+type UnknownRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is UnknownRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function finding(rule: string, message: string, path: string): ArchitectureFinding {
+  return { rule, severity: "error", message, path };
+}
+
+function requiredString(value: unknown, key: string, path: string, findings: ArchitectureFinding[]): string | undefined {
+  if (!isRecord(value) || typeof value[key] !== "string" || value[key].length === 0) {
+    findings.push(finding("required-string", `${key} must be a non-empty string.`, path));
+    return undefined;
+  }
+  return value[key] as string;
+}
+
+function arrayAt(value: UnknownRecord, key: string, path: string, findings: ArchitectureFinding[]): unknown[] {
+  if (value[key] === undefined) return [];
+  if (Array.isArray(value[key])) return value[key] as unknown[];
+  findings.push(finding("collection-shape", `${key} must be an array when provided.`, path));
+  return [];
+}
+
+function uniqueStrings(value: unknown, path: string, findings: ArchitectureFinding[]): string[] {
+  if (!Array.isArray(value) || value.length === 0) {
+    findings.push(finding("responsibilities-shape", "responsibilities must be a non-empty array.", path));
+    return [];
+  }
+  const result: string[] = [];
+  for (const [index, item] of value.entries()) {
+    if (typeof item !== "string" || !(OPERATING_RESPONSIBILITIES as readonly string[]).includes(item)) {
+      findings.push(finding("responsibility-known", "responsibility must be a supported value.", `${path}[${index}]`));
+    } else if (result.includes(item)) {
+      findings.push(finding("duplicate-responsibility", `Duplicate responsibility "${item}".`, `${path}[${index}]`));
+    } else result.push(item);
+  }
+  return result;
+}
+
+/** Creates a detached topology definition without asserting that it is valid. */
+export function defineOperatingTopology(definition: OperatingTopologyDefinition): OperatingTopology {
+  return {
+    id: definition.id,
+    schemaVersion: definition.schemaVersion,
+    scope: { ...definition.scope },
+    systems: (definition.systems ?? []).map((system) => ({ ...system, responsibilities: [...system.responsibilities] })),
+    authorities: (definition.authorities ?? []).map((authority) => ({ ...authority })),
+    interfaces: (definition.interfaces ?? []).map((entry) => ({ ...entry, responsibilities: [...entry.responsibilities] })),
+  };
+}
+
+/** Validates shape, identities, references, ownership and declared interfaces without I/O. */
+export function validateOperatingTopology(value: unknown): ArchitectureFinding[] {
+  const findings: ArchitectureFinding[] = [];
+  if (!isRecord(value)) return [finding("topology-shape", "An operating topology must be an object.", "$")];
+  const topologyId = requiredString(value, "id", "id", findings);
+  if (topologyId !== undefined && !/^[a-z][a-z0-9-]*$/.test(topologyId)) findings.push(finding("topology-id-shape", "id must be a lowercase namespace token.", "id"));
+  requiredString(value, "schemaVersion", "schemaVersion", findings);
+
+  const scope = value.scope;
+  if (!isRecord(scope)) findings.push(finding("scope-shape", "scope must be an object.", "scope"));
+  else {
+    requiredString(scope, "id", "scope.id", findings);
+    const kind = requiredString(scope, "kind", "scope.kind", findings);
+    if (kind !== undefined && !(OPERATING_SCOPE_KINDS as readonly string[]).includes(kind)) findings.push(finding("scope-kind-known", "scope.kind must be portfolio or business.", "scope.kind"));
+  }
+
+  const systems = arrayAt(value, "systems", "systems", findings);
+  const systemIds = new Set<string>();
+  const systemResponsibilities = new Map<string, ReadonlySet<string>>();
+  const responsibilityCoverage = new Set<string>();
+  for (const [index, candidate] of systems.entries()) {
+    const path = `systems[${index}]`;
+    if (!isRecord(candidate)) { findings.push(finding("system-shape", "A system must be an object.", path)); continue; }
+    const id = requiredString(candidate, "id", `${path}.id`, findings);
+    if (id !== undefined) {
+      if (systemIds.has(id)) findings.push(finding("duplicate-system-id", `Duplicate system id "${id}".`, `${path}.id`));
+      systemIds.add(id);
+    }
+    const kind = requiredString(candidate, "kind", `${path}.kind`, findings);
+    if (kind !== undefined && !(OPERATING_SYSTEM_KINDS as readonly string[]).includes(kind)) findings.push(finding("system-kind-known", "kind must be a supported system kind.", `${path}.kind`));
+    const responsibilities = uniqueStrings(candidate.responsibilities, `${path}.responsibilities`, findings);
+    for (const responsibility of responsibilities) responsibilityCoverage.add(responsibility);
+    if (id !== undefined && !systemResponsibilities.has(id)) systemResponsibilities.set(id, new Set(responsibilities));
+    for (const optional of ["provider", "locator"] as const) if (candidate[optional] !== undefined && typeof candidate[optional] !== "string") findings.push(finding(`${optional}-shape`, `${optional} must be a string when provided.`, `${path}.${optional}`));
+    if (candidate.visibility !== undefined && !["public", "private", "restricted"].includes(candidate.visibility as string)) findings.push(finding("visibility-known", "visibility must be public, private, or restricted.", `${path}.visibility`));
+  }
+  if (systems.length === 0) findings.push(finding("systems-required", "At least one system is required.", "systems"));
+  if (!responsibilityCoverage.has("control-plane")) findings.push(finding("control-plane-required", "At least one system must implement the control-plane responsibility.", "systems"));
+
+  const authorities = arrayAt(value, "authorities", "authorities", findings);
+  if (authorities.length === 0) findings.push(finding("authorities-required", "At least one authority is required.", "authorities"));
+  const authorityResponsibilities = new Set<string>();
+  for (const [index, candidate] of authorities.entries()) {
+    const path = `authorities[${index}]`;
+    if (!isRecord(candidate)) { findings.push(finding("authority-shape", "An authority must be an object.", path)); continue; }
+    const responsibility = requiredString(candidate, "responsibility", `${path}.responsibility`, findings);
+    if (responsibility !== undefined) {
+      if (!(OPERATING_RESPONSIBILITIES as readonly string[]).includes(responsibility)) findings.push(finding("responsibility-known", "responsibility must be a supported value.", `${path}.responsibility`));
+      if (!responsibilityCoverage.has(responsibility)) findings.push(finding("responsibility-unimplemented", `No system implements responsibility "${responsibility}".`, `${path}.responsibility`));
+      if (authorityResponsibilities.has(responsibility)) findings.push(finding("duplicate-authority", `Responsibility "${responsibility}" has more than one authority.`, `${path}.responsibility`));
+      authorityResponsibilities.add(responsibility);
+    }
+    requiredString(candidate, "owner", `${path}.owner`, findings);
+    const record = requiredString(candidate, "systemOfRecord", `${path}.systemOfRecord`, findings);
+    if (record !== undefined && !systemIds.has(record)) findings.push(finding("system-of-record-known", `systemOfRecord "${record}" is not a declared system.`, `${path}.systemOfRecord`));
+    else if (record !== undefined && responsibility !== undefined && (OPERATING_RESPONSIBILITIES as readonly string[]).includes(responsibility) && !systemResponsibilities.get(record)?.has(responsibility)) {
+      findings.push(finding("system-of-record-responsibility", `systemOfRecord "${record}" does not implement responsibility "${responsibility}".`, `${path}.systemOfRecord`));
+    }
+  }
+  for (const responsibility of responsibilityCoverage) if (!authorityResponsibilities.has(responsibility)) findings.push(finding("authority-required", `Responsibility "${responsibility}" needs exactly one authority.`, "authorities"));
+
+  const interfaces = arrayAt(value, "interfaces", "interfaces", findings);
+  const interfaceIds = new Set<string>();
+  for (const [index, candidate] of interfaces.entries()) {
+    const path = `interfaces[${index}]`;
+    if (!isRecord(candidate)) { findings.push(finding("interface-shape", "An interface must be an object.", path)); continue; }
+    const id = requiredString(candidate, "id", `${path}.id`, findings);
+    if (id !== undefined) {
+      if (interfaceIds.has(id)) findings.push(finding("duplicate-interface-id", `Duplicate interface id "${id}".`, `${path}.id`));
+      interfaceIds.add(id);
+    }
+    for (const endpoint of ["from", "to"] as const) {
+      const system = requiredString(candidate, endpoint, `${path}.${endpoint}`, findings);
+      if (system !== undefined && !systemIds.has(system)) findings.push(finding("interface-system-known", `${endpoint} system "${system}" is not declared.`, `${path}.${endpoint}`));
+    }
+    if (candidate.from !== undefined && candidate.from === candidate.to) findings.push(finding("interface-boundary", "An interface must cross two different systems.", path));
+    const responsibilities = uniqueStrings(candidate.responsibilities, `${path}.responsibilities`, findings);
+    for (const responsibility of responsibilities) {
+      if (!responsibilityCoverage.has(responsibility)) findings.push(finding("interface-responsibility-unimplemented", `No system implements interface responsibility "${responsibility}".`, `${path}.responsibilities`));
+    }
+    if (candidate.description !== undefined && typeof candidate.description !== "string") findings.push(finding("description-shape", "description must be a string when provided.", `${path}.description`));
+  }
+  return findings;
+}
+
+function byId<T extends { id: string }>(left: T, right: T): number { return left.id.localeCompare(right.id); }
+
+/** Returns one canonical property layout and ordering. */
+export function normalizeOperatingTopology(definition: OperatingTopologyDefinition): OperatingTopology {
+  const value = defineOperatingTopology(definition);
+  const systems: OperatingSystemDefinition[] = value.systems.map((system) => {
+    const next: OperatingSystemDefinition = { id: system.id, kind: system.kind, responsibilities: [...system.responsibilities].sort() };
+    if (system.provider !== undefined) next.provider = system.provider;
+    if (system.locator !== undefined) next.locator = system.locator;
+    if (system.visibility !== undefined) next.visibility = system.visibility;
+    return next;
+  });
+  const authorities: AuthorityDefinition[] = value.authorities.map((entry) => ({ responsibility: entry.responsibility, owner: entry.owner, systemOfRecord: entry.systemOfRecord }));
+  const interfaces: OperatingInterfaceDefinition[] = value.interfaces.map((entry) => {
+    const next: OperatingInterfaceDefinition = { id: entry.id, from: entry.from, to: entry.to, responsibilities: [...entry.responsibilities].sort() };
+    if (entry.description !== undefined) next.description = entry.description;
+    return next;
+  });
+  return { id: value.id, schemaVersion: value.schemaVersion, scope: { id: value.scope.id, kind: value.scope.kind }, systems: systems.sort(byId), authorities: authorities.sort((a, b) => a.responsibility.localeCompare(b.responsibility)), interfaces: interfaces.sort(byId) };
+}
+
+export function serializeOperatingTopology(definition: OperatingTopologyDefinition): string {
+  return `${JSON.stringify(normalizeOperatingTopology(definition), null, 2)}\n`;
+}
+
+function mapById<T extends { id: string }>(values: readonly T[]): Map<string, T> { return new Map(values.map((value) => [value.id, value])); }
+
+/** Compares stable architectural contracts. Description and schemaVersion are not compatibility surface. */
+export function compareOperatingTopologies(previous: OperatingTopologyDefinition, next: OperatingTopologyDefinition): OperatingTopologyCompatibilityReport {
+  const previousFindings = validateOperatingTopology(previous);
+  const nextFindings = validateOperatingTopology(next);
+  if (previousFindings.some((entry) => entry.severity === "error") || nextFindings.some((entry) => entry.severity === "error")) return { compatible: false, changes: [], previousFindings, nextFindings };
+  const before = normalizeOperatingTopology(previous);
+  const after = normalizeOperatingTopology(next);
+  const changes: OperatingTopologyChange[] = [];
+  if (before.id !== after.id) changes.push({ kind: "breaking", subject: "topology", id: after.id, message: `Topology id changed from "${before.id}" to "${after.id}".` });
+  if (JSON.stringify(before.scope) !== JSON.stringify(after.scope)) changes.push({ kind: "breaking", subject: "scope", id: after.scope.id, message: "Operating scope changed." });
+  const compareCollection = <T extends { id: string }>(subject: "system" | "interface", left: readonly T[], right: readonly T[], contract: (value: T) => unknown): void => {
+    const oldValues = mapById(left); const newValues = mapById(right);
+    for (const [id, value] of oldValues) {
+      const replacement = newValues.get(id);
+      if (replacement === undefined) changes.push({ kind: "breaking", subject, id, message: `${subject} "${id}" was removed.` });
+      else if (JSON.stringify(contract(value)) !== JSON.stringify(contract(replacement))) changes.push({ kind: "breaking", subject, id, message: `${subject} "${id}" changed contract.` });
+    }
+    for (const [id] of newValues) if (!oldValues.has(id)) changes.push({ kind: "additive", subject, id, message: `${subject} "${id}" was added.` });
+  };
+  compareCollection("system", before.systems, after.systems, (entry) => entry);
+  compareCollection("interface", before.interfaces, after.interfaces, (entry) => ({ id: entry.id, from: entry.from, to: entry.to, responsibilities: entry.responsibilities }));
+  const oldAuthorities = new Map(before.authorities.map((entry) => [entry.responsibility, entry]));
+  const newAuthorities = new Map(after.authorities.map((entry) => [entry.responsibility, entry]));
+  for (const [id, value] of oldAuthorities) {
+    const replacement = newAuthorities.get(id);
+    if (replacement === undefined) changes.push({ kind: "breaking", subject: "authority", id, message: `authority "${id}" was removed.` });
+    else if (JSON.stringify(value) !== JSON.stringify(replacement)) changes.push({ kind: "breaking", subject: "authority", id, message: `authority "${id}" changed contract.` });
+  }
+  for (const [id] of newAuthorities) if (!oldAuthorities.has(id)) changes.push({ kind: "additive", subject: "authority", id, message: `authority "${id}" was added.` });
+  changes.sort((a, b) => `${a.subject}:${a.id}:${a.kind}`.localeCompare(`${b.subject}:${b.id}:${b.kind}`));
+  return { compatible: changes.every((entry) => entry.kind !== "breaking"), changes, previousFindings, nextFindings };
+}

package/src/types.ts

@@ -0,0 +1,142 @@
+/** The business boundary whose operating architecture is being described. */
+export type OperatingScopeKind = "portfolio" | "business";
+
+/** A provider-neutral kind of system in an operating topology. */
+export type OperatingSystemKind = "workspace" | "repository" | "service" | "data-store" | "external-system";
+
+/** Stable responsibilities that systems can perform without prescribing repository names. */
+export type OperatingResponsibility =
+  | "control-plane"
+  | "product"
+  | "commercial"
+  | "delivery"
+  | "knowledge"
+  | "platform";
+
+export interface OperatingScopeDefinition {
+  id: string;
+  kind: OperatingScopeKind;
+}
+
+/** One addressable system. Provider locators are descriptive, never credentials. */
+export interface OperatingSystemDefinition {
+  id: string;
+  kind: OperatingSystemKind;
+  responsibilities: readonly OperatingResponsibility[];
+  provider?: string;
+  locator?: string;
+  visibility?: "public" | "private" | "restricted";
+}
+
+/** One consumer-owned declaration of authority and its authoritative record. */
+export interface AuthorityDefinition {
+  responsibility: OperatingResponsibility;
+  owner: string;
+  systemOfRecord: string;
+}
+
+/** An allowed directional crossing between two declared systems. */
+export interface OperatingInterfaceDefinition {
+  id: string;
+  from: string;
+  to: string;
+  responsibilities: readonly OperatingResponsibility[];
+  description?: string;
+}
+
+/** Provider-neutral desired operating architecture. */
+export interface OperatingTopologyDefinition {
+  id: string;
+  schemaVersion: string;
+  scope: OperatingScopeDefinition;
+  systems?: readonly OperatingSystemDefinition[];
+  authorities?: readonly AuthorityDefinition[];
+  interfaces?: readonly OperatingInterfaceDefinition[];
+}
+
+export interface OperatingTopology extends OperatingTopologyDefinition {
+  systems: readonly OperatingSystemDefinition[];
+  authorities: readonly AuthorityDefinition[];
+  interfaces: readonly OperatingInterfaceDefinition[];
+}
+
+export type ArchitectureFindingSeverity = "error" | "warning";
+
+export interface ArchitectureFinding {
+  rule: string;
+  severity: ArchitectureFindingSeverity;
+  message: string;
+  path?: string;
+}
+
+export interface OperatingTopologyChange {
+  kind: "additive" | "breaking";
+  subject: "topology" | "scope" | "system" | "authority" | "interface";
+  id: string;
+  message: string;
+}
+
+export interface OperatingTopologyCompatibilityReport {
+  compatible: boolean;
+  changes: readonly OperatingTopologyChange[];
+  previousFindings: readonly ArchitectureFinding[];
+  nextFindings: readonly ArchitectureFinding[];
+}
+
+/** One actual system-to-system crossing observed during a change. */
+export interface BoundaryCrossingObservation {
+  from: string;
+  to: string;
+  responsibility: OperatingResponsibility;
+  interface?: string;
+}
+
+/** Evidence about one actual change. Non-material changes do not enter the metric. */
+export interface ArchitectureChangeObservation {
+  id: string;
+  observedAt: string;
+  material: boolean;
+  crossings: readonly BoundaryCrossingObservation[];
+}
+
+export interface ArchitectureAssessmentOptions {
+  /** Inclusive setpoint in [0, 1]. */
+  maximumExceptionRate: number;
+}
+
+export type ArchitectureAssessmentState = "satisfied" | "violated" | "indeterminate";
+
+export interface AssessedBoundaryCrossing extends BoundaryCrossingObservation {
+  declared: boolean;
+}
+
+export interface AssessedArchitectureChange {
+  id: string;
+  observedAt: string;
+  material: boolean;
+  crossings: readonly AssessedBoundaryCrossing[];
+  hasException: boolean;
+}
+
+/** Pure assessment result. `exceptionRate` is null whenever evidence is indeterminate. */
+export interface ArchitectureExceptionAssessment {
+  state: ArchitectureAssessmentState;
+  exceptionRate: number | null;
+  maximumExceptionRate: number;
+  observedChanges: number;
+  observedMaterialChanges: number;
+  materialChangesWithExceptions: number;
+  changes: readonly AssessedArchitectureChange[];
+  findings: readonly ArchitectureFinding[];
+}
+
+export const OPERATING_SCOPE_KINDS: readonly OperatingScopeKind[] = ["portfolio", "business"];
+export const OPERATING_SYSTEM_KINDS: readonly OperatingSystemKind[] = ["workspace", "repository", "service", "data-store", "external-system"];
+export const OPERATING_RESPONSIBILITIES: readonly OperatingResponsibility[] = [
+  "control-plane",
+  "product",
+  "commercial",
+  "delivery",
+  "knowledge",
+  "platform",
+];