Separate public machine contracts (#78)

Author: SandroMaglione

.changeset/clear-machines-separate.md

@@ -0,0 +1,5 @@
+---
+"@typeonce/effect-machine": patch
+---
+
+Separate the public Machine, MachineTest, AtomMachine, and ClusterMachine contracts from their internal implementations. Enforce designated implementation seams and explicit public function signatures through the architecture check without changing the package API.

scripts/check-architecture.mjs

@@ -4,14 +4,16 @@ import ts from "typescript"
 
 const ruleDescriptions = {
   ARCH001: "Public entrypoints may only expose public modules",
+  ARCH002: "Public modules may only reach internals through their designated implementation seam",
   ARCH003: "Core internals may only refer back to Machine through type-only imports",
   ARCH004: "The planner may not depend on process or runtime execution",
   ARCH006: "The runtime may not depend on machine semantics or process orchestration",
   ARCH007: "Production modules may not depend on testing internals",
   ARCH008: "Black-box tests may not depend on implementation internals",
   ARCH009: "Production runtime imports must be acyclic",
   ARCH011: "Internal directories may not use barrel modules",
-  ARCH012: "Internal filenames must describe their responsibility without a machine prefix"
+  ARCH012: "Internal filenames must describe their responsibility without a machine prefix",
+  ARCH013: "Public implementation bindings must declare their API signature"
 }
 
 const normalizePath = (path) => path.split(sep).join("/")
@@ -211,6 +213,12 @@ export const checkArchitecture = ({
     "src/unstable/cluster/index.ts",
     "src/unstable/reactivity/index.ts"
   ])
+  const implementationSeams = new Map([
+    ["src/Machine.ts", "src/internal/machine/machine.ts"],
+    ["src/testing/MachineTest.ts", "src/internal/testing/machine/verification.ts"],
+    ["src/unstable/reactivity/AtomMachine.ts", "src/internal/machine/atom.ts"],
+    ["src/unstable/cluster/ClusterMachine.ts", "src/internal/machine/cluster.ts"]
+  ])
 
   for (const edge of edges) {
     if (entrypoints.has(edge.source) && edge.target.includes("/internal/")) {
@@ -222,6 +230,21 @@ export const checkArchitecture = ({
         `Public entrypoint imports internal module ${edge.target}`
       ))
     }
+    const implementationSeam = implementationSeams.get(edge.source)
+    if (
+      implementationSeam !== undefined &&
+      !edge.typeOnly &&
+      edge.target.includes("/internal/") &&
+      edge.target !== implementationSeam
+    ) {
+      diagnostics.push(diagnostic(
+        "ARCH002",
+        edge.sourceFile,
+        edge.node,
+        edge.source,
+        `Public module bypasses its implementation seam through ${edge.target}`
+      ))
+    }
     if (
       edge.source.startsWith("src/internal/machine/") &&
       edge.target === "src/Machine.ts" &&
@@ -295,6 +318,61 @@ export const checkArchitecture = ({
 
   for (const sourceFile of program.getSourceFiles()) {
     const path = projectPath(root, sourceFile.fileName)
+    const implementationSeam = implementationSeams.get(path)
+    if (implementationSeam !== undefined) {
+      const implementationNamespaces = new Set()
+      const implementationValues = new Set()
+      for (const statement of sourceFile.statements) {
+        if (
+          !ts.isImportDeclaration(statement) ||
+          statement.importClause === undefined ||
+          statement.importClause.isTypeOnly ||
+          !ts.isStringLiteral(statement.moduleSpecifier) ||
+          resolveProjectModule(
+              statement.moduleSpecifier.text,
+              sourceFile,
+              program.getCompilerOptions(),
+              root
+            ) !== implementationSeam
+        ) continue
+        if (statement.importClause.name !== undefined) {
+          implementationValues.add(statement.importClause.name.text)
+        }
+        const bindings = statement.importClause.namedBindings
+        if (bindings === undefined) continue
+        if (ts.isNamespaceImport(bindings)) {
+          implementationNamespaces.add(bindings.name.text)
+        } else {
+          for (const element of bindings.elements) {
+            if (!element.isTypeOnly) implementationValues.add(element.name.text)
+          }
+        }
+      }
+      for (const statement of sourceFile.statements) {
+        if (
+          !ts.isVariableStatement(statement) ||
+          !statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)
+        ) continue
+        for (const declaration of statement.declarationList.declarations) {
+          if (declaration.initializer === undefined) continue
+          const bindsImplementation =
+            (ts.isPropertyAccessExpression(declaration.initializer) &&
+              ts.isIdentifier(declaration.initializer.expression) &&
+              implementationNamespaces.has(declaration.initializer.expression.text)) ||
+            (ts.isIdentifier(declaration.initializer) && implementationValues.has(declaration.initializer.text))
+          if (!bindsImplementation) continue
+          if (declaration.type === undefined) {
+            diagnostics.push(diagnostic(
+              "ARCH013",
+              sourceFile,
+              declaration,
+              path,
+              "Public implementation binding relies on an inferred internal signature"
+            ))
+          }
+        }
+      }
+    }
     if (!path.startsWith("src/internal/")) continue
     if (basename(path) === "index.ts") {
       diagnostics.push({

scripts/check-architecture.test.mjs

@@ -43,14 +43,24 @@ const rules = (root) => checkArchitecture({ rootDirectory: root }).map((diagnost
 test("accepts Effect-shaped modules and ignores type-only back-edges", () => {
   const root = makeProject({
     "src/index.ts": 'export * as Machine from "./Machine.js"',
-    "src/Machine.ts": 'import * as Model from "./internal/machine/model.js"\nexport interface Machine {}\nexport const model = Model.value',
+    "src/Machine.ts": 'import * as internal from "./internal/machine/machine.js"\nimport type * as Model from "./internal/machine/model.js"\nexport interface Machine { readonly model: typeof Model.value }\nexport const make: () => Machine = internal.make',
+    "src/internal/machine/machine.ts": 'import type { Machine } from "../../Machine.js"\nexport const make = (): Machine => ({ model: 1 })',
     "src/internal/machine/model.ts": 'import type { Machine } from "../../Machine.js"\nexport const value = 1',
     "test/machine/Machine.test.ts": 'import { Machine } from "../../src/index.js"\nvoid Machine',
     "test/internal/machine/model.test.ts": 'import { value } from "../../../src/internal/machine/model.js"\nvoid value'
   })
   assert.deepEqual(rules(root), [])
 })
 
+test("rejects public implementation bypasses and inferred internal signatures", () => {
+  const root = makeProject({
+    "src/Machine.ts": 'import * as internal from "./internal/machine/machine.js"\nimport { value } from "./internal/machine/model.js"\nexport const make = internal.make\nexport const model = value',
+    "src/internal/machine/machine.ts": "export const make = () => 1",
+    "src/internal/machine/model.ts": "export const value = 1"
+  })
+  assert.deepEqual(rules(root), ["ARCH002", "ARCH013"])
+})
+
 test("rejects entrypoint leaks, black-box internal imports, barrels, and legacy filenames", () => {
   const root = makeProject({
     "src/index.ts": 'export { value } from "./internal/machine/model.js"',