@tsplc/compiler 0.0.0-stage → 0.2.0

package/src/frontend/typescript.ts

@@ -0,0 +1,2442 @@
+import { runtimeSources } from "./module-graph.ts";
+import ts from "typescript";
+import { createRequire } from "node:module";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import {
+  instancedBlock,
+  error,
+  hasErrors,
+  parseInteger,
+  fold,
+  canAssign,
+  aggregate,
+  expressionIssue,
+  defaultValue,
+  placeType,
+  durationLiteral,
+  calendarLiteral,
+  loopIterations,
+  loopBounds,
+  narrowRanges,
+  interval,
+  valueRange,
+  integerRange,
+  comparisonOperators,
+  type BinaryOperator,
+  type IntegerInterval,
+  type Constant,
+  type Diagnostic,
+  type Expression,
+  type PlcFunction,
+  type MethodOwner,
+  type PlcModule,
+  type PlcProgram,
+  type SourceSpan,
+  type Statement,
+  type Variable,
+  type Place,
+} from "@tsplc/compiler/ir";
+
+import { lowerExposure } from "./exposure.ts";
+import { lowerServices, serviceRecords, type ServiceOptions } from "./services.ts";
+import { lowerPromises } from "./promises.ts";
+import { lowerAsync } from "./async.ts";
+import { lowerConstFunctions } from "./const-functions.ts";
+import { lowerElaboration } from "./elaborate/index.ts";
+import { lowerEnvironment } from "./configuration.ts";
+import { BlockResolver, storageInitializer, type BlockSource } from "./blocks.ts";
+import { numericLiteralType } from "./types.ts";
+import {
+  TypeResolver,
+  calleeName,
+  type Fail,
+  type TypeEnvironment,
+  type ResolvedType,
+} from "./types.ts";
+
+export interface FrontendOptions {
+  sourceScope?: "project" | "entry";
+  services?: ServiceOptions;
+  tsconfig: string;
+  programs: Readonly<Record<string, { module: string; export: string }>>;
+}
+
+export interface FrontendResult {
+  module?: PlcModule;
+  diagnostics: readonly Diagnostic[];
+}
+
+// TIME constructor scales in nanoseconds, and calendar constructor result types.
+const durationScales: Readonly<Record<string, bigint>> = {
+  ms: 1_000_000n,
+  seconds: 1_000_000_000n,
+  minutes: 60_000_000_000n,
+};
+const calendarTypes: Readonly<Record<string, string>> = {
+  date: "DATE",
+  timeOfDay: "TIME_OF_DAY",
+  dateAndTime: "DATE_AND_TIME",
+};
+const conversions: Readonly<Record<string, "exact" | "wrap" | "saturate">> = {
+  exact: "exact",
+  wrap: "wrap",
+  saturate: "saturate",
+};
+const arithmetic: Readonly<
+  Record<
+    string,
+    { operator: "add" | "subtract" | "multiply" | "divide"; policy?: "wrap" | "saturate" }
+  >
+> = {
+  div: { operator: "divide" },
+  wrapAdd: { operator: "add", policy: "wrap" },
+  wrapSubtract: { operator: "subtract", policy: "wrap" },
+  wrapMultiply: { operator: "multiply", policy: "wrap" },
+  saturatingAdd: { operator: "add", policy: "saturate" },
+  saturatingSubtract: { operator: "subtract", policy: "saturate" },
+  saturatingMultiply: { operator: "multiply", policy: "saturate" },
+};
+const operators = new Map<ts.SyntaxKind, BinaryOperator>([
+  [ts.SyntaxKind.AmpersandAmpersandToken, "and"],
+  [ts.SyntaxKind.BarBarToken, "or"],
+  [ts.SyntaxKind.EqualsEqualsEqualsToken, "equal"],
+  [ts.SyntaxKind.ExclamationEqualsEqualsToken, "notEqual"],
+  [ts.SyntaxKind.LessThanToken, "less"],
+  [ts.SyntaxKind.LessThanEqualsToken, "lessEqual"],
+  [ts.SyntaxKind.GreaterThanToken, "greater"],
+  [ts.SyntaxKind.GreaterThanEqualsToken, "greaterEqual"],
+  [ts.SyntaxKind.PlusToken, "add"],
+  [ts.SyntaxKind.MinusToken, "subtract"],
+  [ts.SyntaxKind.AsteriskToken, "multiply"],
+  [ts.SyntaxKind.SlashToken, "divide"],
+  [ts.SyntaxKind.PercentToken, "remainder"],
+  [ts.SyntaxKind.AmpersandToken, "bitAnd"],
+  [ts.SyntaxKind.BarToken, "bitOr"],
+  [ts.SyntaxKind.CaretToken, "bitXor"],
+  [ts.SyntaxKind.LessThanLessThanToken, "shiftLeft"],
+  [ts.SyntaxKind.GreaterThanGreaterThanToken, "shiftRight"],
+]);
+
+class SemanticError extends Error {
+  constructor(readonly diagnostic: Diagnostic) {
+    super(diagnostic.message);
+  }
+}
+
+function sourceSpan(source: ts.SourceFile, start: number, end: number): SourceSpan {
+  const position = source.getLineAndCharacterOfPosition(start);
+  return {
+    file: source.fileName,
+    start,
+    end,
+    line: position.line + 1,
+    column: position.character + 1,
+  };
+}
+
+function span(node: ts.Node): SourceSpan {
+  const source = node.getSourceFile();
+  return sourceSpan(source, node.getStart(source), node.getEnd());
+}
+
+function tsDiagnostic(diagnostic: ts.Diagnostic): Diagnostic {
+  const result: Diagnostic = {
+    origin: "typescript",
+    code: `TS${diagnostic.code}`,
+    severity: diagnostic.category === ts.DiagnosticCategory.Error ? "error" : "warning",
+    message: ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"),
+  };
+  if (diagnostic.file && diagnostic.start !== undefined)
+    result.span = sourceSpan(
+      diagnostic.file,
+      diagnostic.start,
+      diagnostic.start + (diagnostic.length ?? 1),
+    );
+  return result;
+}
+
+const suppressionDiagnostics = (source: ts.SourceFile): Diagnostic[] => {
+  const diagnostics: Diagnostic[] = [];
+  const scanner = ts.createScanner(
+    ts.ScriptTarget.Latest,
+    false,
+    ts.LanguageVariant.Standard,
+    source.text,
+  );
+  for (let token = scanner.scan(); token !== ts.SyntaxKind.EndOfFileToken; token = scanner.scan()) {
+    if (
+      token !== ts.SyntaxKind.SingleLineCommentTrivia &&
+      token !== ts.SyntaxKind.MultiLineCommentTrivia
+    )
+      continue;
+    const comment = scanner.getTokenText();
+    const match = /(?:^|\n)\s*(?:\/\/+|\/\*+|\*)\s*(@ts-(?:nocheck|ignore|expect-error))\b/.exec(
+      comment,
+    );
+    if (!match) continue;
+    const start = scanner.getTokenPos() + comment.indexOf(match[1] ?? "@ts-");
+    diagnostics.push(
+      error(
+        "PLC1009",
+        "TypeScript diagnostic suppression is not allowed in PLC source.",
+        sourceSpan(source, start, start + (match[1]?.length ?? 4)),
+      ),
+    );
+  }
+  return diagnostics;
+};
+
+/**
+ * Type checks a subset of a tsconfig's files without emitting. A project-reference
+ * tsconfig's composite and declaration settings would demand every file be listed
+ * (TS6307) or conflict with noEmit, so these replace them.
+ */
+export const typeCheckOnly: ts.CompilerOptions = {
+  composite: false,
+  declaration: false,
+  declarationMap: false,
+  emitDeclarationOnly: false,
+  incremental: false,
+  noEmit: true,
+  tsBuildInfoFile: undefined,
+};
+
+export function analyze(options: FrontendOptions): FrontendResult {
+  const filename = resolve(options.tsconfig);
+  const config = ts.readConfigFile(filename, ts.sys.readFile);
+  if (config.error) return { diagnostics: [tsDiagnostic(config.error)] };
+  const parsed = ts.parseJsonConfigFileContent(
+    config.config,
+    ts.sys,
+    dirname(filename),
+    undefined,
+    filename,
+  );
+  if (parsed.errors.length) return { diagnostics: parsed.errors.map(tsDiagnostic) };
+  // TypeScript stores SourceFile paths with forward slashes on every host.
+  // Normalize require.resolve once so canonical SDK identity also works on Windows.
+  const sdk = createRequire(import.meta.url)
+    .resolve("@tsplc/compiler/globals")
+    .replaceAll("\\", "/");
+  const programFiles = Object.values(options.programs).map((entry) =>
+    resolve(dirname(filename), entry.module),
+  );
+  // Full-stack builds follow entry imports; standalone projects retain explicit tsconfig globals.
+  const scope = options.sourceScope ?? (options.services ? "entry" : "project");
+  // The project's own ambient declarations; a shared base tsconfig's typings are for the host runtime.
+  const ambient = parsed.fileNames.filter(
+    (file) => /\.d\.[cm]?ts$/.test(file) && file.startsWith(`${dirname(filename)}/`),
+  );
+  const projectFiles = scope === "project" ? parsed.fileNames : ambient;
+  const rootNames = [...new Set([...projectFiles, ...programFiles, sdk])];
+  const compilerOptions: ts.CompilerOptions = {
+    ...parsed.options,
+    ...typeCheckOnly,
+    // Lowered sources import their runtime helpers by .ts path and drop the imports they replace.
+    allowImportingTsExtensions: true,
+    noUnusedLocals: false,
+    noUnusedParameters: false,
+    strict: true,
+    noImplicitAny: true,
+    strictNullChecks: true,
+    noCheck: false,
+    allowJs: false,
+    skipLibCheck: false,
+    types: [],
+    lib: ["lib.es2022.d.ts"],
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+  };
+  // Nothing is emitted, and a service client's router type imports modules outside these (TS6059).
+  delete compilerOptions.rootDir;
+  delete compilerOptions.outDir;
+  let program = ts.createProgram(rootNames, compilerOptions);
+  const plcFiles = (program: ts.Program) => {
+    const files = new Set(runtimeSources(program));
+    for (const source of program.getSourceFiles())
+      if (source.fileName.startsWith(dirname(sdk) + "/")) files.add(source);
+    return files;
+  };
+  // Only PLC files: a type-only import of the server router brings the server's sources along.
+  const sourceDiagnostics = (program: ts.Program) =>
+    [
+      ...program.getConfigFileParsingDiagnostics(),
+      ...program.getOptionsDiagnostics(),
+      ...program.getGlobalDiagnostics(),
+      ...[...plcFiles(program)].flatMap((file) => [
+        ...program.getSyntacticDiagnostics(file),
+        ...program.getSemanticDiagnostics(file),
+      ]),
+    ].map(tsDiagnostic);
+  const diagnostics = sourceDiagnostics(program);
+  if (
+    program.getSyntacticDiagnostics().some((item) => !item.file || plcFiles(program).has(item.file))
+  )
+    return { diagnostics };
+  const virtualSources = new Map<string, string>();
+  // Lowering also adds modules, such as the service client, that exist only here.
+  let host: ts.CompilerHost = ts.createCompilerHost(compilerOptions);
+  const apply = (lowering: {
+    sources: Map<string, string>;
+    diagnostics: Diagnostic[];
+  }): boolean => {
+    diagnostics.push(...lowering.diagnostics);
+    for (const source of runtimeSources(program))
+      if (lowering.sources.has(source.fileName))
+        diagnostics.push(...suppressionDiagnostics(source));
+    if (lowering.diagnostics.length || (lowering.sources.size && hasErrors(diagnostics)))
+      return false;
+    if (lowering.sources.size) {
+      for (const [path, text] of lowering.sources) virtualSources.set(path, text);
+      // TSPLC_LOWERED=<directory> writes every generated or rewritten module, as the next step reads it.
+      const dump = process.env.TSPLC_LOWERED;
+      if (dump)
+        for (const [path, text] of lowering.sources) {
+          const target = join(dump, relative(dirname(filename), path));
+          mkdirSync(dirname(target), { recursive: true });
+          writeFileSync(target, text);
+        }
+      host = ts.createCompilerHost(compilerOptions);
+      const read = host.readFile,
+        exists = host.fileExists;
+      const directoryExists = host.directoryExists?.bind(host);
+      host.readFile = (path) => virtualSources.get(path) ?? read(path);
+      host.fileExists = (path) => virtualSources.has(path) || exists(path);
+      // Generated modules can live in a directory that only exists in memory.
+      host.directoryExists = (path) =>
+        [...virtualSources.keys()].some((file) => file.startsWith(`${path.replace(/\/$/, "")}/`)) ||
+        (directoryExists?.(path) ?? true);
+      program = ts.createProgram(rootNames, compilerOptions, host);
+      diagnostics.push(...sourceDiagnostics(program));
+    }
+    return true;
+  };
+  if (!apply(lowerElaboration(program, sdk, options.programs, dirname(filename))))
+    return { diagnostics };
+  const services = lowerServices(program, sdk, options.services);
+  if (!apply(services)) return { diagnostics };
+  const exposure = lowerExposure(program, sdk);
+  if (!apply(exposure)) return { diagnostics };
+  if (!apply(lowerEnvironment(program, sdk))) return { diagnostics };
+  if (!apply(lowerConstFunctions(program))) return { diagnostics };
+  const promises = lowerPromises(program, sdk);
+  if (!apply(promises)) return { diagnostics };
+  const lowering = lowerAsync(program, sdk);
+  for (const [key, value] of promises.runtimeBlocks) lowering.blocks.set(key, value);
+  if (!apply(lowering)) return { diagnostics };
+  const analyzer = new Analyzer(
+    program,
+    host,
+    dirname(filename),
+    sdk,
+    diagnostics,
+    serviceRecords(program, services),
+  );
+  const module = analyzer.run({ ...options.programs, ...lowering.programs });
+  for (const variable of module.variables) {
+    const item = exposure.variables.get(`${variable.span.file}:${variable.name}`);
+    if (item) variable.exposure = item;
+  }
+  for (const block of module.blocks) {
+    const runtime = lowering.blocks.get(`${block.span.file}:${block.name}`);
+    if (runtime) block.runtime = runtime;
+  }
+  for (const entry of module.programs) {
+    const background = lowering.schedules.get(entry.name);
+    if (background) entry.background = background;
+    const continuation = lowering.continuations.get(entry.name);
+    if (continuation) entry.continuation = continuation;
+  }
+  return hasErrors(diagnostics) ? { diagnostics } : { module, diagnostics };
+}
+
+export function checkHostConfig(file: string): readonly Diagnostic[] {
+  const bunTypes = createRequire(import.meta.url).resolve("@types/bun/index.d.ts");
+  const program = ts.createProgram([file], {
+    strict: true,
+    noEmit: true,
+    target: ts.ScriptTarget.ES2022,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    allowImportingTsExtensions: true,
+    skipLibCheck: true,
+    types: [bunTypes],
+  });
+  return ts.getPreEmitDiagnostics(program).map(tsDiagnostic);
+}
+
+class Analyzer {
+  private readonly checker: ts.TypeChecker;
+  private readonly variables = new Map<ts.Symbol, Variable>();
+  private readonly functions = new Map<ts.Symbol, PlcFunction>();
+  private readonly methods = new Map<ts.Symbol, PlcFunction>();
+  private readonly functionDeclarations = new Map<ts.Symbol, ts.FunctionDeclaration>();
+  private readonly instances = new Map<string, PlcFunction>();
+  private readonly pending: {
+    node: ts.FunctionDeclaration | ts.MethodDeclaration;
+    fn: PlcFunction;
+    environment: TypeEnvironment;
+  }[] = [];
+  private readonly resolver: TypeResolver;
+  private readonly blocks: BlockResolver;
+  private readonly globalVariables: Variable[] = [];
+  private readonly sources: readonly ts.SourceFile[];
+
+  // This scope is saved and restored for each block or generic function body.
+  private environment: TypeEnvironment = new Map();
+  private activeBlock: BlockSource | undefined;
+  private readonly ranges = new Map<string, IntegerInterval>();
+  private readonly loopCounters = new Set<string>();
+  private readonly aliases = new Map<ts.Symbol, Place>();
+  private copySources: Place[] = [];
+  private readonly breakTargets: ("loop" | "switch")[] = [];
+  private activeFunction: PlcFunction | undefined;
+
+  constructor(
+    private readonly program: ts.Program,
+    private readonly host: ts.ModuleResolutionHost,
+    private readonly root: string,
+    private readonly sdk: string,
+    private readonly diagnostics: Diagnostic[],
+    serviceRecord?: (type: ts.Type) => ts.Symbol | undefined,
+  ) {
+    this.checker = program.getTypeChecker();
+    this.resolver = new TypeResolver(this.checker, root, sdk, this.fail, serviceRecord);
+    this.blocks = new BlockResolver(
+      this.resolver,
+      span,
+      this.fail,
+      span(program.getSourceFile(sdk)!),
+    );
+    const roots = new Set(program.getRootFileNames());
+    this.sources = runtimeSources(program).filter(
+      (source) =>
+        source.fileName !== sdk &&
+        !source.fileName.startsWith(`${dirname(sdk)}/`) &&
+        !program.isSourceFileDefaultLibrary(source) &&
+        (!source.isDeclarationFile || roots.has(source.fileName)),
+    );
+  }
+
+  private readonly fail: Fail = (node, code, message) => {
+    throw new SemanticError(error(code, message, span(node)));
+  };
+
+  private type(node: ts.TypeNode): ResolvedType {
+    return this.resolver.resolve(node, this.environment);
+  }
+
+  private storageId(node: ts.Node, name: string): string {
+    return `${this.resolver.id(node, name)}${this.activeFunction ? `@${this.activeFunction.id}` : ""}`;
+  }
+
+  private guard(action: () => void): void {
+    try {
+      action();
+    } catch (cause) {
+      if (!(cause instanceof SemanticError)) throw cause;
+      this.diagnostics.push(cause.diagnostic);
+    }
+  }
+
+  run(entries: FrontendOptions["programs"]): PlcModule {
+    // Collect every declaration before resolving initializers and routine bodies.
+    // Generic calls can enqueue more helpers, so resolve entry points last.
+    this.collectDeclarations();
+    this.initializeStorage();
+    this.analyzeBlockBodies();
+    this.analyzePendingFunctions();
+    const programs = this.resolvePrograms(entries);
+
+    return {
+      types: [...this.resolver.types.values()],
+      variables: this.globalVariables,
+      functions: [...this.instances.values()],
+      blocks: [...this.blocks.definitions.values()],
+      programs,
+    };
+  }
+
+  private collectDeclarations(): void {
+    const classes = this.sources.flatMap((source) =>
+      source.statements.filter(ts.isClassDeclaration),
+    );
+    this.blocks.index(classes);
+    for (const node of classes) this.guard(() => this.blocks.collect(node));
+    for (const source of this.blocks.sources.values()) {
+      for (const method of source.methods)
+        this.guard(() => {
+          const fn = this.instantiate(method, [], method);
+          fn.owner = {
+            block: source.block.id,
+            access: this.methodAccess(method),
+          };
+          this.methods.set(this.resolver.symbol(method.name), fn);
+        });
+    }
+    for (const source of this.sources) {
+      this.diagnostics.push(...suppressionDiagnostics(source));
+      for (const statement of source.statements) {
+        this.guard(() => this.declaration(statement));
+      }
+    }
+  }
+
+  private methodAccess(method: ts.MethodDeclaration): MethodOwner["access"] {
+    if (method.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.PrivateKeyword))
+      return "private";
+    if (method.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ProtectedKeyword))
+      return "protected";
+    return "public";
+  }
+
+  private initializeStorage(): void {
+    for (const source of this.sources) {
+      for (const statement of source.statements) {
+        if (ts.isVariableStatement(statement) && !source.isDeclarationFile) {
+          this.guard(() => {
+            for (const declaration of statement.declarationList.declarations) {
+              if (!declaration.initializer)
+                this.fail(
+                  declaration,
+                  "PLC3001",
+                  "Persistent PLC state requires a constant initializer.",
+                );
+              const variable = this.variables.get(this.resolver.symbol(declaration.name));
+              if (!variable || variable.storage === "instance") continue;
+              const initializer = storageInitializer(
+                declaration.initializer,
+                this.resolver,
+                this.fail,
+              ).value;
+              const inferred = variable.type === "inferred";
+              const expression = this.expression(initializer, inferred ? undefined : variable.type);
+              variable.type = expression.type;
+              if (
+                inferred &&
+                variable.storage === "constant" &&
+                aggregate(this.resolver.types.get(variable.type))
+              )
+                variable.storage = "module";
+              if (variable.retain && variable.storage === "constant")
+                this.fail(
+                  declaration,
+                  "PLC3004",
+                  "retain requires mutable persistent storage or a static block instance.",
+                );
+              const value = this.constant(this.implicitCopy(expression));
+              if (!value)
+                this.fail(
+                  declaration.initializer,
+                  "PLC3001",
+                  "Persistent initializers must be compile-time constants.",
+                );
+              variable.initial = value;
+            }
+          });
+        }
+      }
+    }
+  }
+
+  private analyzeBlockBodies(): void {
+    for (const source of this.blocks.sources.values())
+      this.guard(() => {
+        for (const [variable, node] of source.initializers) {
+          const value = this.constant(this.expression(node, variable.type));
+          if (!value)
+            this.fail(node, "PLC3001", "Block state requires a compile-time constant initializer.");
+          variable.initial = value;
+        }
+        const { block } = source;
+        this.activeBlock = source;
+        try {
+          const routine = this.routineBody(
+            {
+              id: block.id,
+              name: block.name,
+              parameters: block.inputs,
+              locals: [],
+              body: [],
+              span: block.span,
+              ...(block.result && { result: block.result }),
+            },
+            source.fieldBindings,
+            source.method.body!,
+          );
+          block.locals = routine.locals;
+          block.body = routine.body;
+        } finally {
+          this.activeBlock = undefined;
+        }
+      });
+  }
+
+  private analyzePendingFunctions(): void {
+    // A worklist allows explicit generic instances to share source without sharing locals.
+    for (let index = 0; index < this.pending.length; index++) {
+      const instance = this.pending[index]!;
+      this.guard(() => {
+        this.environment = instance.environment;
+        this.activeBlock = instance.fn.owner
+          ? [...this.blocks.sources.values()].find(
+              (source) => source.block.id === instance.fn.owner?.block,
+            )
+          : undefined;
+        try {
+          // Declaration admission proved the parameter list and body before worklist analysis.
+          const fn = this.routineBody(
+            instance.fn,
+            [
+              ...(this.activeBlock?.fieldBindings ?? []),
+              ...instance.node.parameters.map(
+                (parameter, index) =>
+                  [this.resolver.symbol(parameter.name), instance.fn.parameters[index]!] as const,
+              ),
+            ],
+            instance.node.body!,
+          );
+          this.instances.set(fn.id, fn);
+          if (ts.isFunctionDeclaration(instance.node) && !instance.node.typeParameters?.length)
+            this.functions.set(this.resolver.symbol(instance.node.name!), fn);
+        } finally {
+          this.environment = new Map();
+          this.activeBlock = undefined;
+        }
+      });
+    }
+  }
+
+  // Lowers one routine body with its bindings layered over module storage.
+  private routineBody(
+    fn: PlcFunction,
+    bindings: Iterable<readonly [ts.Symbol, Variable]>,
+    body: ts.Block,
+  ): PlcFunction {
+    const saved = new Map(this.variables),
+      locals: Variable[] = [];
+    this.activeFunction = fn;
+    this.copySources = [];
+    for (const [symbol, variable] of bindings) this.variables.set(symbol, variable);
+    try {
+      return { ...fn, locals, body: this.statements(body.statements, locals) };
+    } finally {
+      this.variables.clear();
+      for (const [symbol, variable] of saved) this.variables.set(symbol, variable);
+      this.activeFunction = undefined;
+    }
+  }
+
+  private resolvePrograms(entries: FrontendOptions["programs"]): PlcProgram[] {
+    const programs: PlcProgram[] = [];
+    for (const [name, entry] of Object.entries(entries)) {
+      const source = this.program.getSourceFile(resolve(this.root, entry.module));
+      if (!source) {
+        this.diagnostics.push(error("PLC4001", `Program source not found: ${entry.module}.`));
+        continue;
+      }
+      this.guard(() => {
+        const moduleSymbol = this.checker.getSymbolAtLocation(source);
+        const exported =
+          moduleSymbol &&
+          this.checker
+            .getExportsOfModule(moduleSymbol)
+            .find((symbol) => symbol.name === entry.export);
+        if (!exported)
+          this.fail(source, "PLC4001", `Program export ${entry.export} was not found.`);
+        const symbol =
+          exported.flags & ts.SymbolFlags.Alias
+            ? this.checker.getAliasedSymbol(exported)
+            : exported;
+        const fn = this.functions.get(symbol);
+        if (!fn || fn.parameters.length || fn.result)
+          this.fail(
+            source,
+            "PLC4001",
+            "Program entry must be an implemented parameterless void function.",
+          );
+        programs.push({ id: `program:${name}`, name, entry: fn.id });
+      });
+    }
+    return programs;
+  }
+
+  private dependency(node: ts.ImportDeclaration | ts.ExportDeclaration): void {
+    if (!node.moduleSpecifier) return;
+    if (!ts.isStringLiteral(node.moduleSpecifier))
+      this.fail(node, "PLC1001", "Only static module imports are supported.");
+    const resolved = ts.resolveModuleName(
+      node.moduleSpecifier.text,
+      node.getSourceFile().fileName,
+      this.program.getCompilerOptions(),
+      this.host,
+    ).resolvedModule;
+    if (!resolved)
+      this.fail(
+        node.moduleSpecifier,
+        "PLC1008",
+        "This dependency could not be resolved to PLC source.",
+      );
+    const source = this.program.getSourceFile(resolved.resolvedFileName);
+    const typeOnly = ts.isImportDeclaration(node) ? node.importClause?.isTypeOnly : node.isTypeOnly;
+    if (typeOnly) return;
+    const bindings = ts.isImportDeclaration(node)
+      ? node.importClause?.namedBindings
+      : node.exportClause;
+    const defaultName = ts.isImportDeclaration(node) ? node.importClause?.name : undefined;
+    const namedOnly =
+      bindings &&
+      (ts.isNamedImports(bindings) || ts.isNamedExports(bindings)) &&
+      bindings.elements.length > 0 &&
+      bindings.elements.every(
+        (binding) =>
+          binding.isTypeOnly || !(this.resolver.symbol(binding.name).flags & ts.SymbolFlags.Value),
+      );
+    if (namedOnly && !defaultName) return;
+    if (source && !source.isDeclarationFile) return;
+    if (resolved.resolvedFileName.replaceAll("\\", "/").startsWith(`${dirname(this.sdk)}/`)) return;
+    const authoredIo =
+      source &&
+      this.sources.includes(source) &&
+      source.statements.some(ts.isVariableStatement) &&
+      source.statements.every(
+        (statement) =>
+          ts.isTypeAliasDeclaration(statement) ||
+          ts.isEmptyStatement(statement) ||
+          (ts.isVariableStatement(statement) &&
+            statement.declarationList.declarations.every(
+              (declaration) => declaration.type && this.type(declaration.type).io,
+            )),
+      );
+    if (authoredIo) return;
+    this.fail(
+      node.moduleSpecifier,
+      "PLC1008",
+      "Runtime dependencies need PLC TypeScript implementation source; JavaScript and declaration-only value imports are unsupported.",
+    );
+  }
+
+  private declaration(statement: ts.Statement): void {
+    if (ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)) {
+      this.dependency(statement);
+      return;
+    }
+    if (
+      ts.isClassDeclaration(statement) ||
+      ts.isTypeAliasDeclaration(statement) ||
+      ts.isInterfaceDeclaration(statement) ||
+      ts.isEmptyStatement(statement)
+    )
+      return;
+    if (ts.isEnumDeclaration(statement)) {
+      this.resolver.enumeration(statement);
+      return;
+    }
+    if (ts.isVariableStatement(statement)) {
+      this.moduleVariables(statement);
+      return;
+    }
+    if (ts.isFunctionDeclaration(statement)) {
+      if (!statement.name || !statement.body)
+        this.fail(statement, "PLC1001", "PLC functions need a name and an implementation.");
+      if (statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword)) {
+        this.fail(statement, "PLC1007", "Async execution is not supported in PLC scan code.");
+      }
+      if (statement.asteriskToken)
+        this.fail(statement, "PLC1007", "Generators are not supported in PLC scan code.");
+      const symbol = this.resolver.symbol(statement.name);
+      this.functionDeclarations.set(symbol, statement);
+      if (!statement.typeParameters?.length)
+        this.functions.set(symbol, this.instantiate(statement, [], statement));
+      return;
+    }
+    this.fail(
+      statement,
+      "PLC1001",
+      `${ts.SyntaxKind[statement.kind]} is not supported in PLC source.`,
+    );
+  }
+
+  private moduleVariables(statement: ts.VariableStatement): void {
+    if (!(statement.declarationList.flags & (ts.NodeFlags.Let | ts.NodeFlags.Const)))
+      this.fail(statement, "PLC1001", "Use let or const instead of var.");
+    const immutable = Boolean(statement.declarationList.flags & ts.NodeFlags.Const);
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name))
+        this.fail(declaration.name, "PLC1001", "Destructuring declarations are not supported.");
+      const initializer =
+        declaration.initializer &&
+        storageInitializer(declaration.initializer, this.resolver, this.fail);
+      const table = initializer && this.tableType(declaration, initializer.value);
+      const instance =
+        initializer && ts.isNewExpression(initializer.value)
+          ? this.blocks.instanceType(initializer.value)
+          : initializer && !table
+            ? this.blocks.instanceArrayType(declaration.type, initializer.value)
+            : undefined;
+      const literal = initializer && this.numericLiteral(initializer.value);
+      if (table && !immutable)
+        this.fail(declaration, "PLC2001", "A readonly table is a const declaration.");
+      const type = instance
+        ? { type: instance }
+        : (table ??
+          (declaration.type
+            ? this.type(declaration.type)
+            : { type: immutable ? "inferred" : literal ? numericLiteralType(literal) : "BOOL" }));
+      if (
+        !instance &&
+        !declaration.type &&
+        !immutable &&
+        !literal &&
+        declaration.initializer &&
+        initializer?.value.kind !== ts.SyntaxKind.TrueKeyword &&
+        initializer?.value.kind !== ts.SyntaxKind.FalseKeyword
+      )
+        this.fail(declaration, "PLC2001", "Annotate PLC storage explicitly.");
+      const ambient = declaration.getSourceFile().isDeclarationFile;
+      if (type.mode || this.resolver.hasReferences(type.type))
+        this.fail(declaration, "PLC2001", "Borrow schemas cannot be stored as values.");
+      if (this.resolver.types.get(type.type)?.kind === "block" && !instance)
+        this.fail(
+          declaration,
+          "PLC1007",
+          "Block instances require a static constructor initializer.",
+        );
+      if (
+        instance &&
+        (!immutable || (declaration.type && this.type(declaration.type).type !== instance))
+      )
+        this.fail(
+          declaration,
+          "PLC2001",
+          "Static block instances require const bindings and matching annotations.",
+        );
+      if (
+        initializer?.retain &&
+        (ambient ||
+          (immutable &&
+            type.type !== "inferred" &&
+            !instance &&
+            !aggregate(this.resolver.types.get(type.type))))
+      )
+        this.fail(
+          declaration,
+          "PLC3004",
+          "retain requires mutable persistent storage or a static block instance.",
+        );
+      if (ambient && !type.io)
+        this.fail(declaration, "PLC4002", "Ambient PLC variables must declare Input or Output.");
+      if (!ambient && type.io)
+        this.fail(declaration, "PLC4002", "Logical I/O belongs in an ambient declaration file.");
+      if (type.io === "input" && !immutable)
+        this.fail(declaration, "PLC4002", "Inputs must use declare const.");
+      if (type.io === "output" && immutable)
+        this.fail(declaration, "PLC4002", "Outputs must use declare let.");
+      const variable: Variable = {
+        id: this.storageId(declaration, declaration.name.text),
+        name: declaration.name.text,
+        type: type.type,
+        storage: instance
+          ? "instance"
+          : (type.io ??
+            (immutable && (table || !aggregate(this.resolver.types.get(type.type)))
+              ? "constant"
+              : "module")),
+        mutable: !immutable,
+        retain: initializer?.retain ?? false,
+        ...(statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)
+          ? { exported: true as const }
+          : {}),
+        span: span(declaration),
+      };
+      this.variables.set(this.resolver.symbol(declaration.name), variable);
+      this.globalVariables.push(variable);
+    }
+  }
+
+  /**
+   * `const table: readonly T[] = [...]` or `const table = [...] as const satisfies readonly T[]`,
+   * also spelled `ReadonlyArray<T>`, is a constant `FixedArray<T, N>` whose length is the
+   * literal's element count.
+   */
+  private tableType(
+    declaration: ts.VariableDeclaration,
+    initializer: ts.Expression,
+  ): ResolvedType | undefined {
+    const satisfied = ts.isSatisfiesExpression(initializer) ? initializer : undefined;
+    const annotation = declaration.type ?? satisfied?.type;
+    if (!annotation) return undefined;
+    let element: ts.TypeNode | undefined;
+    if (
+      ts.isTypeOperatorNode(annotation) &&
+      annotation.operator === ts.SyntaxKind.ReadonlyKeyword &&
+      ts.isArrayTypeNode(annotation.type)
+    )
+      element = annotation.type.elementType;
+    else if (
+      ts.isTypeReferenceNode(annotation) &&
+      annotation.typeName.getText() === "ReadonlyArray" &&
+      annotation.typeArguments?.length === 1 &&
+      this.resolver.standardLibrary(this.resolver.symbol(annotation.typeName))
+    )
+      element = annotation.typeArguments[0];
+    if (!element) return undefined;
+    let literal = satisfied?.expression ?? initializer;
+    while (
+      ts.isParenthesizedExpression(literal) ||
+      (ts.isAsExpression(literal) && ts.isConstTypeReference(literal.type))
+    )
+      literal = literal.expression;
+    if (!ts.isArrayLiteralExpression(literal))
+      this.fail(declaration, "PLC2001", "A readonly table is initialized by an array literal.");
+    return this.resolver.fixedArray(
+      annotation,
+      this.type(element),
+      { kind: "integer", value: literal.elements.length },
+      { kind: "integer", value: 0 },
+    );
+  }
+
+  private instantiate(
+    node: ts.FunctionDeclaration | ts.MethodDeclaration,
+    arguments_: readonly ts.TypeNode[],
+    call: ts.Node,
+  ): PlcFunction {
+    if (!node.name || !ts.isIdentifier(node.name))
+      this.fail(node, "PLC1001", "PLC routines need identifier names.");
+    const routineName = node.name.text;
+    const environment = this.resolver.bindings(
+      node.typeParameters,
+      arguments_,
+      this.environment,
+      call,
+    );
+    const suffix = (node.typeParameters ?? [])
+      .map((parameter) => this.resolver.key(environment.get(this.resolver.symbol(parameter.name))!))
+      .join(",");
+    const id = `${this.resolver.id(node, routineName)}${suffix ? `<${suffix}>` : ""}`;
+    const existing = this.instances.get(id);
+    if (existing) return existing;
+    // Bounds generic expansion; plain helpers each instantiate once.
+    if (suffix && [...this.instances.keys()].filter((key) => key.endsWith(">")).length >= 256)
+      this.fail(
+        call,
+        "PLC2001",
+        "Generic specialization exceeds 256 concrete helpers; recursive specialization is unsupported.",
+      );
+    const saved = this.environment;
+    this.environment = environment;
+    try {
+      const parameters = node.parameters.map((parameter) => {
+        if (
+          !ts.isIdentifier(parameter.name) ||
+          !parameter.type ||
+          parameter.initializer ||
+          parameter.questionToken ||
+          parameter.dotDotDotToken
+        )
+          this.fail(
+            parameter,
+            "PLC2001",
+            "PLC parameters need names and explicit types; optional/rest/default parameters are unsupported.",
+          );
+        const type = this.type(parameter.type);
+        const block = this.resolver.types.get(type.type)?.kind === "block";
+        if (type.mode !== "inOut" && !block && !this.resolver.isValue(type))
+          this.fail(parameter, "PLC2001", "Parameters require value types or InOut borrows.");
+        if (type.io) this.fail(parameter, "PLC2001", "Parameters cannot use logical I/O wrappers.");
+        // Records, arrays and blocks pass by reference, as objects do in TypeScript.
+        const mode =
+          type.mode ??
+          (block || aggregate(this.resolver.types.get(type.type)) ? "inOut" : undefined);
+        return {
+          id: `${this.resolver.id(parameter, parameter.name.text)}@${id}`,
+          name: parameter.name.text,
+          type: type.type,
+          storage: "parameter" as const,
+          mutable: mode === "inOut",
+          ...(mode && { mode }),
+          retain: false,
+          span: span(parameter),
+        };
+      });
+      let result: string | undefined;
+      if (node.type && node.type.kind !== ts.SyntaxKind.VoidKeyword) {
+        const type = this.type(node.type);
+        if (!this.resolver.isValue(type))
+          this.fail(node.type, "PLC2001", "Helper results require value types.");
+        if (type.io) this.fail(node.type, "PLC4002", "Helper results cannot use I/O wrappers.");
+        result = type.type;
+      } else if (!node.type) {
+        const signature = this.checker.getSignatureFromDeclaration(node);
+        if (
+          !signature ||
+          !(this.checker.getReturnTypeOfSignature(signature).flags & ts.TypeFlags.Void)
+        )
+          this.fail(node, "PLC2001", "Annotate helper results explicitly.");
+      }
+      const bounds = this.resolver.mathHelper(node, routineName);
+      const fn: PlcFunction = {
+        id,
+        name: `${routineName}${suffix ? `_${suffix}` : ""}`,
+        parameters,
+        locals: [],
+        body: [],
+        span: span(node),
+        ...(result && { result }),
+        ...(bounds && { bounds }),
+      };
+      this.instances.set(id, fn);
+      this.pending.push({ node, fn, environment });
+      return fn;
+    } finally {
+      this.environment = saved;
+    }
+  }
+
+  private byId(): Map<string, Variable> {
+    return new Map(
+      [
+        ...this.variables.values(),
+        ...(this.activeBlock
+          ? [...this.activeBlock.block.inputs, ...this.activeBlock.block.outputs]
+          : []),
+      ].map((variable) => [variable.id, variable]),
+    );
+  }
+
+  private checked(value: Expression): Expression {
+    const message = expressionIssue(value, this.resolver.types, this.byId(), this.ranges);
+    if (message) throw new SemanticError(error("PLC2002", message, value.span));
+    return value;
+  }
+
+  private coerce(value: Expression, destination: string): Expression {
+    if (value.type === destination) return value;
+    const source = this.resolver.types.get(value.type),
+      target = this.resolver.types.get(destination);
+    if (!source || !target)
+      throw new SemanticError(error("PLC2001", "This PLC type has not been resolved.", value.span));
+    const constant = fold(value, this.byId(), this.resolver.types);
+    if (
+      source.kind === "string" &&
+      target.kind === "string" &&
+      source.encoding === target.encoding &&
+      source.capacity <= target.capacity
+    )
+      return constant
+        ? { kind: "constant", type: destination, value: constant, span: value.span }
+        : { kind: "convert", type: destination, operand: value, policy: "exact", span: value.span };
+    if (!canAssign(source, target, constant))
+      throw new SemanticError(
+        error(
+          "PLC2002",
+          "Use an explicit conversion between these PLC domains or widths.",
+          value.span,
+        ),
+      );
+    if (constant) return { kind: "constant", type: destination, value: constant, span: value.span };
+    return this.checked({
+      kind: "convert",
+      type: destination,
+      operand: value,
+      policy: "exact",
+      span: value.span,
+    });
+  }
+
+  private constant(expression: Expression): Constant | undefined {
+    return fold(expression, this.byId(), this.resolver.types);
+  }
+
+  private numericLiteral(node: ts.Expression): string | undefined {
+    while (ts.isParenthesizedExpression(node)) node = node.expression;
+    if (ts.isNumericLiteral(node) || ts.isBigIntLiteral(node)) return node.getText();
+    if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken) {
+      const operand = this.numericLiteral(node.operand);
+      if (operand !== undefined) return operand.startsWith("-") ? operand.slice(1) : `-${operand}`;
+    }
+    return undefined;
+  }
+
+  private contextualLiteral(node: ts.Expression): boolean {
+    while (ts.isParenthesizedExpression(node)) node = node.expression;
+    return (
+      this.numericLiteral(node) !== undefined ||
+      ts.isStringLiteral(node) ||
+      ts.isNoSubstitutionTemplateLiteral(node)
+    );
+  }
+
+  private literal(node: ts.Expression, expected?: string): Expression | undefined {
+    const text = this.numericLiteral(node);
+    if (text === undefined) return undefined;
+    const type = expected ?? numericLiteralType(text);
+    const target = this.resolver.types.get(type);
+    if (!target || !["integer", "bits", "float"].includes(target.kind))
+      this.fail(
+        node,
+        "PLC2001",
+        "Numeric literals require an arithmetic or bit-string PLC type; use named enum members.",
+      );
+    let value: Constant;
+    if (target.kind === "float") {
+      const clean = text.replaceAll("_", "");
+      const number = /^-?0[xob]/i.test(clean) ? Number(parseInteger(clean)) : Number(clean);
+      value = { kind: "float", value: target.bits === 32 ? Math.fround(number) : number };
+    } else {
+      try {
+        value = { kind: "integer", value: String(parseInteger(text)) };
+      } catch (cause) {
+        this.fail(
+          node,
+          "PLC2002",
+          cause instanceof Error ? cause.message : "Invalid integer literal.",
+        );
+      }
+    }
+    return this.checked({ kind: "constant", type, value, span: span(node) });
+  }
+
+  private expression(node: ts.Expression, expected?: string): Expression {
+    if (
+      ts.isParenthesizedExpression(node) ||
+      ts.isSatisfiesExpression(node) ||
+      (ts.isAsExpression(node) && ts.isConstTypeReference(node.type))
+    )
+      return this.expression(node.expression, expected);
+    const literal = this.literal(node, expected);
+    if (literal) return literal;
+    const value = this.rawExpression(node, expected);
+    return expected ? this.coerce(value, expected) : value;
+  }
+
+  private rawExpression(node: ts.Expression, expected?: string): Expression {
+    const origin = { span: span(node) };
+    if (node.kind === ts.SyntaxKind.TrueKeyword || node.kind === ts.SyntaxKind.FalseKeyword) {
+      return {
+        ...origin,
+        type: "BOOL",
+        kind: "constant",
+        value: { kind: "bool", value: node.kind === ts.SyntaxKind.TrueKeyword },
+      };
+    }
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+      const type = expected ? this.resolver.types.get(expected) : undefined;
+      if (type?.kind === "enum") {
+        const member = type.members.find((member) => member.name === node.text);
+        if (member)
+          return {
+            ...origin,
+            type: type.id,
+            kind: "constant",
+            value: { kind: "integer", value: member.value },
+          };
+      }
+      if (type?.kind !== "string")
+        this.fail(node, "PLC2001", "String literals require a bounded STRING or WSTRING context.");
+      return this.checked({
+        ...origin,
+        type: type.id,
+        kind: "constant",
+        value: { kind: "string", value: node.text },
+      });
+    }
+    if (ts.isObjectLiteralExpression(node)) {
+      const type = expected ? this.resolver.types.get(expected) : undefined;
+      if (type?.kind === "array" && type.index) {
+        // Like an array literal, every element in order, so items evaluate in source order.
+        const order = "Enum-keyed record literals list every enum member once, in value order.";
+        const items: Expression[] = [];
+        for (const property of node.properties) {
+          if (!ts.isPropertyAssignment(property) || !ts.isComputedPropertyName(property.name))
+            this.fail(
+              property,
+              "PLC1001",
+              "Enum-keyed record literals use computed member keys such as [Station.A].",
+            );
+          const key = this.expression(property.name.expression, type.index);
+          if (key.kind !== "constant" || key.type !== type.index || key.value.kind !== "integer")
+            this.fail(property.name, "PLC2001", "Keys must be members of the record's enum.");
+          if (Number(key.value.value) !== type.lowerBound + items.length)
+            this.fail(property, "PLC2001", order);
+          items.push(this.implicitCopy(this.expression(property.initializer, type.element)));
+        }
+        if (items.length !== type.length) this.fail(node, "PLC2001", order);
+        return this.checked({ ...origin, type: type.id, kind: "array", items });
+      }
+      if (type?.kind !== "record")
+        this.fail(node, "PLC2001", "Record literals require an explicit closed PLC record type.");
+      const fields: Record<string, Expression> = Object.create(null);
+      const written = new Set<string>();
+      for (const [position, property] of node.properties.entries()) {
+        if (ts.isSpreadAssignment(property) && !position) {
+          for (const [name, value] of Object.entries(
+            this.spreadFields(property.expression, type.fields),
+          )) {
+            // TypeScript's spread shares a nested record or array, so a later write to it diverges.
+            this.recordCopySource(value);
+            fields[name] = this.implicitCopy(value);
+          }
+          continue;
+        }
+        if (
+          !(ts.isPropertyAssignment(property) || ts.isShorthandPropertyAssignment(property)) ||
+          !ts.isIdentifier(property.name)
+        )
+          this.fail(
+            property,
+            "PLC1001",
+            "Record literals take named fields after at most one leading spread; methods are unsupported.",
+          );
+        const fieldName = property.name.text;
+        const field = type.fields.find((field) => field.name === fieldName);
+        if (!field || written.has(field.name))
+          this.fail(property, "PLC2001", "Unknown or duplicate record field.");
+        written.add(field.name);
+        // An explicit field overrides the spread and keeps its source evaluation order.
+        delete fields[field.name];
+        fields[field.name] = this.implicitCopy(
+          this.expression(
+            ts.isPropertyAssignment(property) ? property.initializer : property.name,
+            field.type,
+          ),
+        );
+      }
+      if (this.resolver.unions.has(type.id))
+        for (const field of type.fields)
+          if (!Object.hasOwn(fields, field.name))
+            fields[field.name] = {
+              ...origin,
+              type: field.type,
+              kind: "constant",
+              value: defaultValue(field.type, this.resolver.types),
+            };
+      return this.checked({ ...origin, type: type.id, kind: "record", fields });
+    }
+    if (ts.isArrayLiteralExpression(node)) {
+      const type = expected ? this.resolver.types.get(expected) : undefined;
+      if (type?.kind !== "array")
+        this.fail(node, "PLC2001", "Array literals require an explicit FixedArray type.");
+      const items = node.elements.map((element) => {
+        if (ts.isOmittedExpression(element) || ts.isSpreadElement(element))
+          this.fail(element, "PLC1001", "Fixed arrays cannot have holes or spreading.");
+        return this.implicitCopy(this.expression(element, type.element));
+      });
+      return this.checked({ ...origin, type: type.id, kind: "array", items });
+    }
+    if (ts.isPropertyAccessExpression(node)) {
+      const declaration = this.resolver.symbol(node.name).declarations?.find(ts.isEnumMember);
+      if (declaration) {
+        const type = this.resolver.enumeration(declaration.parent).type;
+        const layout = this.resolver.types.get(type)!;
+        if (layout.kind !== "enum") this.fail(node, "PLC2001", "Invalid enum layout.");
+        return {
+          ...origin,
+          type,
+          kind: "constant",
+          value: {
+            kind: "integer",
+            value: layout.members.find((member) => member.name === declaration.name.getText())!
+              .value,
+          },
+        };
+      }
+      if (node.name.text === "length") {
+        const base = this.expression(node.expression),
+          type = this.resolver.types.get(base.type);
+        if (type?.kind === "array")
+          return { ...origin, type: "DINT", kind: "length", operand: base };
+      }
+    }
+    if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+      const place = this.place(node),
+        type = placeType(place, this.resolver.types, this.byId(), this.ranges);
+      if (type.issue || !type.type) this.fail(node, "PLC2001", type.issue ?? "Invalid PLC place.");
+      return { ...origin, type: type.type, kind: "load", place };
+    }
+    if (ts.isIdentifier(node) && this.aliases.has(this.resolver.symbol(node))) {
+      const place = this.place(node),
+        type = placeType(place, this.resolver.types, this.byId(), this.ranges);
+      if (type.issue || !type.type) this.fail(node, "PLC2001", type.issue ?? "Invalid PLC place.");
+      return { ...origin, type: type.type, kind: "load", place };
+    }
+    if (ts.isIdentifier(node)) {
+      const variable = this.variables.get(this.resolver.symbol(node));
+      if (!variable) this.fail(node, "PLC1002", "This value has no supported PLC storage.");
+      if (variable.type === "inferred")
+        this.fail(
+          node,
+          "PLC3001",
+          "Resolve constant initializer dependencies in declaration order.",
+        );
+      return {
+        ...origin,
+        type: variable.type,
+        kind: "load",
+        place: { root: variable.id, path: [] },
+      };
+    }
+    if (ts.isPrefixUnaryExpression(node)) {
+      const operator =
+        node.operator === ts.SyntaxKind.ExclamationToken
+          ? "not"
+          : node.operator === ts.SyntaxKind.MinusToken
+            ? "negate"
+            : node.operator === ts.SyntaxKind.TildeToken
+              ? "bitNot"
+              : undefined;
+      if (!operator) this.fail(node, "PLC2001", "Unsupported unary operation.");
+      const operand = this.expression(node.operand, operator === "not" ? "BOOL" : expected);
+      return this.checked({
+        ...origin,
+        type: operator === "not" ? "BOOL" : operand.type,
+        kind: "unary",
+        operator,
+        operand,
+      });
+    }
+    if (ts.isCallExpression(node)) {
+      const sdk = this.sdkExpression(node, expected);
+      if (sdk) return sdk;
+      const call = this.call(node);
+      if (!call.fn.result)
+        this.fail(node, "PLC2001", "A void helper cannot produce an expression value.");
+      return {
+        ...origin,
+        type: call.fn.result,
+        kind: "call",
+        function: call.fn.id,
+        arguments: call.arguments,
+        ...(call.instance && { instance: call.instance }),
+        ...(call.index && { index: call.index }),
+      };
+    }
+    if (ts.isConditionalExpression(node)) {
+      const then = this.expression(node.whenTrue, expected);
+      return {
+        ...origin,
+        type: then.type,
+        kind: "conditional",
+        condition: this.expression(node.condition, "BOOL"),
+        then,
+        else: this.expression(node.whenFalse, then.type),
+      };
+    }
+    if (ts.isBinaryExpression(node)) return this.binaryExpression(node, expected);
+    this.fail(node, "PLC1001", `${ts.SyntaxKind[node.kind]} is not supported in PLC expressions.`);
+  }
+
+  private binaryExpression(node: ts.BinaryExpression, expected?: string): Expression {
+    const origin = { span: span(node) };
+    const operator = operators.get(node.operatorToken.kind);
+    if (!operator)
+      this.fail(
+        node.operatorToken,
+        "PLC2001",
+        "Unsupported binary operation; implicit coercion is prohibited.",
+      );
+    const logical = operator === "and" || operator === "or";
+    const comparison = comparisonOperators.has(operator);
+    const leftIsLiteral = this.contextualLiteral(node.left);
+    const context = logical
+      ? "BOOL"
+      : comparison
+        ? leftIsLiteral
+          ? this.expression(node.right).type
+          : undefined
+        : expected;
+    let left = this.expression(node.left, context);
+    if (comparison && !leftIsLiteral && !this.contextualLiteral(node.right)) {
+      // Compare at the wider type; widening cannot change the value.
+      const wider = this.expression(node.right).type,
+        from = this.resolver.types.get(left.type),
+        to = this.resolver.types.get(wider);
+      if (from && to && !canAssign(to, from) && canAssign(from, to))
+        left = this.coerce(left, wider);
+    }
+    const right = this.expression(
+      node.right,
+      operator === "shiftLeft" || operator === "shiftRight" ? "DINT" : left.type,
+    );
+    if (operator === "divide" && this.resolver.types.get(left.type)?.kind !== "float")
+      this.fail(node, "PLC2002", "Use div<T>() for truncating integer division.");
+    return this.checked({
+      ...origin,
+      type: logical || comparison ? "BOOL" : left.type,
+      kind: "binary",
+      operator,
+      left,
+      right,
+    });
+  }
+
+  private sdkExpression(node: ts.CallExpression, expected?: string): Expression | undefined {
+    const origin = { span: span(node) };
+    const official = this.sdkCall(node);
+    if (official === "errorCode") {
+      if (node.arguments.length !== 1)
+        this.fail(node, "PLC1012", "errorCode requires one rejection reason.");
+      return this.expression(node.arguments[0]!, "UDINT");
+    }
+    if (
+      official &&
+      (Object.hasOwn(durationScales, official) || Object.hasOwn(calendarTypes, official))
+    ) {
+      if (node.arguments.length !== 1 || node.typeArguments?.length)
+        this.fail(node, "PLC2001", "Time constructors require one compile-time literal argument.");
+      const argument = node.arguments[0]!;
+      const scale = durationScales[official];
+      let value: Constant | undefined, type: string;
+      if (scale) {
+        type = "TIME";
+        let text = this.numericLiteral(argument);
+        if (text === undefined) {
+          const folded = this.constant(this.expression(argument));
+          if (folded?.kind === "integer") text = folded.value;
+        }
+        if (text !== undefined && /^-?0[xob]/i.test(text)) text = String(parseInteger(text));
+        value = text === undefined ? undefined : durationLiteral(text.replace(/n$/, ""), scale);
+      } else {
+        type = calendarTypes[official]!;
+        const layout = this.resolver.types.get(type)!;
+        value =
+          layout.kind === "calendar" &&
+          (ts.isStringLiteral(argument) || ts.isNoSubstitutionTemplateLiteral(argument))
+            ? calendarLiteral(layout.domain, argument.text)
+            : undefined;
+      }
+      if (!value)
+        this.fail(
+          argument,
+          "PLC2002",
+          "Invalid time literal: require an exact supported domain value and millisecond TIME precision.",
+        );
+      return this.checked({ ...origin, type, kind: "constant", value });
+    }
+    if (official === "now") {
+      if (node.arguments.length || node.typeArguments?.length)
+        this.fail(node, "PLC2001", "now() takes no arguments.");
+      return this.checked({
+        ...origin,
+        type: "DINT",
+        kind: "unary",
+        operator: "clock",
+        operand: {
+          ...origin,
+          type: "DINT",
+          kind: "constant",
+          value: { kind: "integer", value: "0" },
+        },
+      });
+    }
+    if (official === "timeToMilliseconds") {
+      if (node.arguments.length !== 1 || node.typeArguments?.length)
+        this.fail(
+          node,
+          "PLC2001",
+          "timeToMilliseconds requires one TIME argument and no type arguments.",
+        );
+      return this.checked({
+        ...origin,
+        type: "UDINT",
+        kind: "unary",
+        operator: "timeToMilliseconds",
+        operand: this.expression(node.arguments[0]!),
+      });
+    }
+    if (official === "defaultValue") {
+      if (node.arguments.length || node.typeArguments?.length !== 1)
+        this.fail(
+          node,
+          "PLC2001",
+          "defaultValue requires exactly one concrete type and no value arguments.",
+        );
+      const type = this.type(node.typeArguments[0]!);
+      if (!this.resolver.isValue(type))
+        this.fail(
+          node,
+          "PLC2001",
+          "defaultValue requires a fixed value layout, not an instance or borrow schema.",
+        );
+      if (type.io) this.fail(node, "PLC4002", "Default values cannot create logical I/O.");
+      return this.checked({
+        ...origin,
+        type: type.type,
+        kind: "constant",
+        value: defaultValue(type.type, this.resolver.types),
+      });
+    }
+    if (official === "copy") {
+      if (node.arguments.length !== 1 || (node.typeArguments && node.typeArguments.length !== 1))
+        this.fail(node, "PLC2001", "copy requires one fixed aggregate value.");
+      const operand = this.expression(
+        node.arguments[0]!,
+        node.typeArguments?.[0] ? this.type(node.typeArguments[0]).type : expected,
+      );
+      return this.checked({ ...origin, type: operand.type, kind: "copy", operand });
+    }
+    if (official && (Object.hasOwn(conversions, official) || Object.hasOwn(arithmetic, official))) {
+      const argument = node.typeArguments?.[0];
+      if (!argument || node.typeArguments?.length !== 1)
+        this.fail(
+          node,
+          "PLC2001",
+          "Numeric SDK operations require one explicit PLC type argument.",
+        );
+      const target = this.type(argument);
+      if (target.io)
+        this.fail(argument, "PLC2001", "I/O wrappers cannot select an operation type.");
+      const conversion = conversions[official];
+      if (conversion) {
+        if (node.arguments.length !== 1)
+          this.fail(node, "PLC2001", "Conversion needs exactly one operand.");
+        return this.checked({
+          ...origin,
+          type: target.type,
+          kind: "convert",
+          policy: conversion,
+          operand: this.expression(node.arguments[0]!),
+        });
+      }
+      const operation = arithmetic[official]!;
+      if (node.arguments.length !== 2)
+        this.fail(node, "PLC2001", "Arithmetic SDK operation needs two operands.");
+      return this.checked({
+        ...origin,
+        type: target.type,
+        kind: "binary",
+        ...operation,
+        left: this.expression(node.arguments[0]!, target.type),
+        right: this.expression(node.arguments[1]!, target.type),
+      });
+    }
+    return undefined;
+  }
+
+  private sdkCall(node: ts.CallExpression): string | undefined {
+    const name = calleeName(node.expression);
+    return name && this.resolver.sdkName(name);
+  }
+
+  private update(node: ts.CallExpression): Statement | undefined {
+    if (!ts.isPropertyAccessExpression(node.expression) || node.expression.name.text !== "update")
+      return undefined;
+    const place = this.place(node.expression.expression),
+      variable = this.byId().get(place.root),
+      type = variable && instancedBlock(variable.type, this.resolver.types),
+      [selector, ...rest] = place.path,
+      index = selector?.kind === "index" ? selector.value : undefined;
+    if (
+      !type ||
+      rest.length ||
+      (this.resolver.types.get(variable.type)?.kind === "array" ? !index : selector)
+    )
+      this.fail(node, "PLC1007", "Update requires a static block instance binding.");
+    const definition = this.blocks.definitions.get(type.block)!;
+    if (
+      node.typeArguments?.length ||
+      node.arguments.length !== 1 ||
+      !ts.isObjectLiteralExpression(node.arguments[0]!)
+    )
+      this.fail(node, "PLC2001", "Block update requires one complete named input record.");
+    const inputs: Record<string, Expression> = Object.create(null);
+    const written = new Set<string>();
+    for (const [position, property] of node.arguments[0].properties.entries()) {
+      if (ts.isSpreadAssignment(property) && !position) {
+        for (const [name, value] of Object.entries(
+          this.spreadFields(property.expression, definition.inputs),
+        )) {
+          const parameter = definition.inputs.find((input) => input.name === name)!;
+          inputs[name] = parameter.mode === "inOut" ? this.reference(value, parameter) : value;
+        }
+        continue;
+      }
+      if (
+        !(ts.isPropertyAssignment(property) || ts.isShorthandPropertyAssignment(property)) ||
+        !ts.isIdentifier(property.name)
+      )
+        this.fail(
+          property,
+          "PLC2001",
+          "Block inputs are named fields after at most one leading spread.",
+        );
+      const name = property.name.text;
+      const parameter = definition.inputs.find((input) => input.name === name);
+      if (!parameter || written.has(parameter.name))
+        this.fail(property, "PLC2001", "Unknown or duplicate block input.");
+      written.add(parameter.name);
+      const value = ts.isPropertyAssignment(property) ? property.initializer : property.name;
+      delete inputs[parameter.name];
+      inputs[parameter.name] = this.inputArgument(value, parameter);
+    }
+    if (definition.inputs.some((input) => !Object.hasOwn(inputs, input.name)))
+      this.fail(node, "PLC2001", "Block update must bind every input on each call.");
+    return {
+      kind: "blockUpdate",
+      instance: place.root,
+      ...(index && { index }),
+      inputs,
+      span: span(node),
+    };
+  }
+
+  private call(node: ts.CallExpression): {
+    fn: PlcFunction;
+    arguments: Expression[];
+    instance?: string;
+    index?: Expression;
+  } {
+    const name = calleeName(node.expression);
+    if (!name) this.fail(node, "PLC1001", "Call a statically resolved PLC helper or block method.");
+    const symbol = this.resolver.symbol(name);
+    // Structural return types can give a receiver a transient property symbol.
+    // Resolve its declaration back to the canonical instance method identity.
+    const method =
+      this.methods.get(symbol) ??
+      symbol.declarations
+        ?.filter(ts.isMethodDeclaration)
+        .map((node) => this.methods.get(this.resolver.symbol(node.name)))
+        .find((fn) => fn !== undefined);
+    if (method) {
+      if (!ts.isPropertyAccessExpression(node.expression) || node.typeArguments?.length)
+        this.fail(node, "PLC1007", "Methods require a static instance receiver.");
+      const receiver = node.expression.expression;
+      let instance: string | undefined;
+      let index: Expression | undefined;
+      if (receiver.kind === ts.SyntaxKind.ThisKeyword) {
+        if (method.owner?.block !== this.activeBlock?.block.id)
+          this.fail(node, "PLC1007", "Method receiver differs from the enclosing block.");
+      } else {
+        const place = this.place(receiver);
+        const variable = this.byId().get(place.root);
+        const type = variable && instancedBlock(variable.type, this.resolver.types);
+        const [selector, ...rest] = place.path;
+        index = selector?.kind === "index" ? selector.value : undefined;
+        if (
+          (variable?.storage !== "instance" && variable?.mode !== "inOut") ||
+          rest.length ||
+          (this.resolver.types.get(variable.type)?.kind === "array" ? !index : selector) ||
+          type?.block !== method.owner?.block
+        )
+          this.fail(node, "PLC1007", "Methods require a matching static block instance.");
+        if (method.owner?.access !== "public" && method.owner?.block !== this.activeBlock?.block.id)
+          this.fail(
+            node,
+            "PLC1007",
+            "Private and protected methods are only accessible within their block.",
+          );
+        instance = place.root;
+      }
+      return {
+        fn: method,
+        arguments: this.callArguments(node, method),
+        ...(instance && { instance }),
+        ...(index && { index }),
+      };
+    }
+    const declaration = this.functionDeclarations.get(symbol);
+    if (!declaration)
+      this.fail(node, "PLC1001", "Calls require PLC TypeScript implementation source.");
+    const fn = declaration.typeParameters?.length
+      ? this.instantiate(declaration, node.typeArguments ?? [], node)
+      : this.functions.get(symbol);
+    if (!fn || (!declaration.typeParameters?.length && node.typeArguments?.length))
+      this.fail(node, "PLC2001", "Type arguments require a generic helper.");
+    return { fn, arguments: this.callArguments(node, fn) };
+  }
+
+  private callArguments(node: ts.CallExpression, fn: PlcFunction): Expression[] {
+    if (node.arguments.length !== fn.parameters.length)
+      this.fail(node, "PLC2001", "PLC argument count differs from its signature.");
+    return fn.parameters.map((parameter, index) =>
+      this.inputArgument(node.arguments[index]!, parameter),
+    );
+  }
+
+  private inputArgument(value: ts.Expression, parameter: Variable): Expression {
+    if (parameter.mode !== "inOut") return this.expression(value, parameter.type);
+    if (ts.isCallExpression(value) && this.sdkCall(value) === "ref") {
+      if (value.arguments.length !== 1 || value.typeArguments?.length)
+        this.fail(value, "PLC3003", "ref takes one place.");
+      const target = this.target(value.arguments[0]!);
+      if (target.type !== parameter.type)
+        this.fail(value, "PLC2001", "Borrowed place type must exactly match its InOut parameter.");
+      return { kind: "borrow", place: target.place, type: target.type, span: span(value) };
+    }
+    if (this.resolver.types.get(parameter.type)?.kind === "block") {
+      const place = this.place(value);
+      if (placeType(place, this.resolver.types, this.byId(), this.ranges).type !== parameter.type)
+        this.fail(value, "PLC2001", "Pass a block instance of the parameter's type.");
+      return { kind: "borrow", place, type: parameter.type, span: span(value) };
+    }
+    return this.reference(this.expression(value, parameter.type), parameter);
+  }
+
+  /**
+   * An aggregate InOut argument borrows its place; a value with no writable address reaches
+   * the callee through a compiler temporary.
+   */
+  private reference(argument: Expression, parameter: Variable): Expression {
+    if (!aggregate(this.resolver.types.get(parameter.type)))
+      throw new SemanticError(
+        error(
+          "PLC3003",
+          "Scalar InOut arguments require a direct ref(place) borrow.",
+          argument.span,
+        ),
+      );
+    return argument.kind === "load" &&
+      !this.loopCounters.has(argument.place.root) &&
+      !placeType(argument.place, this.resolver.types, this.byId(), this.ranges, true).issue
+      ? { kind: "borrow", place: argument.place, type: argument.type, span: argument.span }
+      : this.implicitCopy(argument);
+  }
+
+  /**
+   * The fields `{ ...base }` supplies: base is a record whose fields are all target fields of the
+   * same type. A stored base is read field by field; `defaultValue<T>()` gives constants.
+   */
+  private spreadFields(
+    node: ts.Expression,
+    targets: readonly { name: string; type: string }[],
+  ): Record<string, Expression> {
+    let base = this.expression(node);
+    const layout = this.resolver.types.get(base.type);
+    if (
+      layout?.kind !== "record" ||
+      layout.fields.some(
+        (field) => targets.find((target) => target.name === field.name)?.type !== field.type,
+      )
+    )
+      this.fail(
+        node,
+        "PLC2001",
+        "A spread is a record whose fields are all fields of the target, with the same types.",
+      );
+    // Static initializers run before any scan, so a stored base contributes its initial value.
+    const initial =
+      !this.activeFunction && base.kind === "load" && !base.place.path.length
+        ? this.byId().get(base.place.root)?.initial
+        : undefined;
+    if (initial) base = { ...base, kind: "constant", value: initial };
+    if (base.kind === "load") {
+      const { place } = base;
+      return Object.fromEntries(
+        layout.fields.map((field) => [
+          field.name,
+          {
+            kind: "load",
+            type: field.type,
+            place: { root: place.root, path: [...place.path, { kind: "field", name: field.name }] },
+            span: base.span,
+          },
+        ]),
+      );
+    }
+    if (base.kind !== "constant" || base.value.kind !== "record")
+      this.fail(
+        node,
+        "PLC1001",
+        "Spread a record in storage or defaultValue<T>(); bind other values to a const first.",
+      );
+    const { value } = base;
+    return Object.fromEntries(
+      layout.fields.map((field) => [
+        field.name,
+        { kind: "constant", type: field.type, value: value.fields[field.name]!, span: base.span },
+      ]),
+    );
+  }
+
+  private statements(nodes: readonly ts.Statement[], locals: Variable[]): Statement[] {
+    return nodes.flatMap((node) => this.statement(node, locals));
+  }
+
+  private body(node: ts.Statement, locals: Variable[]): Statement[] {
+    return ts.isBlock(node)
+      ? this.statements(node.statements, locals)
+      : this.statement(node, locals);
+  }
+
+  /** A record or array assigned into storage copies: fixed storage cannot repoint at its source. */
+  private implicitCopy(value: Expression): Expression {
+    if (instancedBlock(value.type, this.resolver.types))
+      throw new SemanticError(
+        error("PLC3003", "Block instances cannot be copied, aliased or returned.", value.span),
+      );
+    return aggregate(this.resolver.types.get(value.type)) && value.kind === "load"
+      ? { kind: "copy", type: value.type, operand: value, span: value.span }
+      : value;
+  }
+
+  /** Remember a copied source, so a later write to it in this routine cannot silently diverge. */
+  private recordCopySource(value: Expression): void {
+    if (value.kind === "load" && aggregate(this.resolver.types.get(value.type)))
+      this.copySources.push(value.place);
+  }
+
+  /** An alias re-reads its path at each use, so its indexes must keep their value for its scope. */
+  private unchanging(value: Expression): boolean {
+    if (value.kind === "constant") return true;
+    if (value.kind === "convert") return this.unchanging(value.operand);
+    if (value.kind === "binary") return this.unchanging(value.left) && this.unchanging(value.right);
+    if (value.kind !== "load" || value.place.path.length) return false;
+    const root = this.byId().get(value.place.root);
+    return (
+      this.loopCounters.has(value.place.root) ||
+      Boolean(root && !root.mutable && ["parameter", "local", "constant"].includes(root.storage))
+    );
+  }
+
+  private place(node: ts.Expression): Place {
+    if (ts.isParenthesizedExpression(node)) return this.place(node.expression);
+    if (this.activeBlock && ts.isPropertyAccessExpression(node)) {
+      if (
+        ts.isIdentifier(node.expression) &&
+        this.resolver.symbol(node.expression) === this.activeBlock.inputSymbol
+      ) {
+        const variable = this.activeBlock.inputBindings.get(node.name.text);
+        if (!variable) this.fail(node, "PLC2001", "Unknown block input field.");
+        return { root: variable.id, path: [] };
+      }
+      if (
+        ts.isPropertyAccessExpression(node.expression) &&
+        node.expression.expression.kind === ts.SyntaxKind.ThisKeyword &&
+        node.expression.name.text === "out"
+      ) {
+        const variable = this.activeBlock.block.outputs.find(
+          (output) => output.name === node.name.text,
+        );
+        if (!variable) this.fail(node, "PLC2001", "Unknown block output field.");
+        return { root: variable.id, path: [] };
+      }
+    }
+    if (
+      ts.isPropertyAccessExpression(node) &&
+      this.activeBlock?.fieldBindings.has(this.resolver.symbol(node.name)) &&
+      node.expression.kind !== ts.SyntaxKind.ThisKeyword
+    )
+      this.fail(node, "PLC1007", "Private block state is accessible through this.field only.");
+    if (ts.isIdentifier(node)) {
+      const alias = this.aliases.get(this.resolver.symbol(node));
+      if (alias) return alias;
+    }
+    if (ts.isIdentifier(node) || ts.isPropertyAccessExpression(node)) {
+      const variable = this.variables.get(
+        this.resolver.symbol(ts.isIdentifier(node) ? node : node.name),
+      );
+      if (variable) return { root: variable.id, path: [] };
+    }
+    if (ts.isPropertyAccessExpression(node)) {
+      const base = this.place(node.expression);
+      return { root: base.root, path: [...base.path, { kind: "field", name: node.name.text }] };
+    }
+    if (ts.isElementAccessExpression(node) && node.argumentExpression) {
+      const base = this.place(node.expression),
+        value = this.expression(node.argumentExpression),
+        array = this.resolver.types.get(
+          placeType(base, this.resolver.types, this.byId(), this.ranges).type ?? "",
+        );
+      if (array?.kind === "array" && array.index && value.type !== array.index)
+        this.fail(node, "PLC2001", "An enum-keyed record is indexed only by its own enum.");
+      return { root: base.root, path: [...base.path, { kind: "index", value }] };
+    }
+    this.fail(node, "PLC1001", "Access requires statically allocated PLC storage.");
+  }
+
+  private target(node: ts.Expression): { place: Place; type: string } {
+    if (ts.isIdentifier(node)) {
+      const binding = this.checker.getSymbolAtLocation(node);
+      if (binding && binding.flags & ts.SymbolFlags.Alias)
+        this.fail(node, "PLC3002", "Imported scalar bindings are read-only.");
+    }
+    const place = this.place(node),
+      type = placeType(place, this.resolver.types, this.byId(), this.ranges, true);
+    if (type.issue || !type.type || this.loopCounters.has(place.root))
+      this.fail(node, "PLC3002", type.issue ?? "This PLC storage is read-only.");
+    const overlaps = (source: Place) =>
+      source.root === place.root &&
+      source.path.every((segment, index) => {
+        const other = place.path[index];
+        return (
+          !other ||
+          segment.kind !== "field" ||
+          other.kind !== "field" ||
+          segment.name === other.name
+        );
+      });
+    if (this.copySources.some(overlaps))
+      this.fail(
+        node,
+        "PLC3003",
+        "This value was assigned into other storage, which holds a copy, so this write will not reach it. Assign it afterwards, or use copy(value) if separate values are intended.",
+      );
+    return { place, type: type.type };
+  }
+
+  private statement(node: ts.Statement, locals: Variable[]): Statement[] {
+    const origin = { span: span(node) };
+    if (ts.isBlock(node)) return this.statements(node.statements, locals);
+    if (ts.isEmptyStatement(node)) return [];
+    if (ts.isIfStatement(node)) {
+      const condition = this.expression(node.expression, "BOOL");
+      const original = new Map(this.ranges);
+      const branch = (body: ts.Statement | undefined, truth: boolean) => {
+        this.ranges.clear();
+        for (const [root, range] of narrowRanges(
+          condition,
+          truth,
+          this.resolver.types,
+          this.byId(),
+          original,
+        ))
+          this.ranges.set(root, range);
+        try {
+          return body ? this.body(body, locals) : [];
+        } finally {
+          this.ranges.clear();
+          for (const [root, range] of original) this.ranges.set(root, range);
+        }
+      };
+      return [
+        {
+          ...origin,
+          kind: "if",
+          condition,
+          then: branch(node.thenStatement, true),
+          else: branch(node.elseStatement, false),
+        },
+      ];
+    }
+    if (ts.isReturnStatement(node)) {
+      const result = this.activeFunction?.result;
+      if (!result && node.expression)
+        this.fail(node, "PLC2001", "Void helpers and program entries cannot return a value.");
+      if (result && !node.expression)
+        this.fail(node, "PLC2001", "Typed helpers must return their declared PLC result.");
+      const value =
+        node.expression && result
+          ? this.implicitCopy(this.expression(node.expression, result))
+          : undefined;
+      return [{ ...origin, kind: "return", ...(value && { value }) }];
+    }
+    if (ts.isBreakStatement(node) || ts.isContinueStatement(node)) {
+      if (ts.isBreakStatement(node) && this.breakTargets.at(-1) === "switch")
+        this.fail(
+          node,
+          "PLC1001",
+          "Switch break must terminate its case; nested conditional switch breaks are unsupported.",
+        );
+      if (node.label || !this.loopCounters.size)
+        this.fail(
+          node,
+          "PLC1001",
+          "Loop control requires an enclosing bounded loop and cannot use a label.",
+        );
+      return [{ ...origin, kind: ts.isBreakStatement(node) ? "break" : "continue" }];
+    }
+    if (ts.isVariableStatement(node)) return this.localDeclarations(node, locals);
+    if (ts.isForStatement(node)) return this.loop(node, locals);
+    if (ts.isForOfStatement(node)) return this.forOf(node, locals);
+    if (ts.isSwitchStatement(node)) return this.switchStatement(node, locals);
+    if (ts.isExpressionStatement(node)) {
+      const expression = node.expression;
+      if (ts.isCallExpression(expression)) {
+        const update = this.update(expression);
+        if (update) return [update];
+        const call = this.call(expression);
+        return [
+          {
+            ...origin,
+            kind: "invoke",
+            function: call.fn.id,
+            arguments: call.arguments,
+            ...(call.instance && { instance: call.instance }),
+            ...(call.index && { index: call.index }),
+          },
+        ];
+      }
+      if (ts.isBinaryExpression(expression)) {
+        const variable = this.target(expression.left);
+        if (expression.operatorToken.kind !== ts.SyntaxKind.EqualsToken)
+          this.fail(expression, "PLC2001", "Use explicit assignment and arithmetic policies.");
+        const value = this.expression(expression.right, variable.type);
+        this.recordCopySource(value);
+        return [
+          {
+            ...origin,
+            kind: "assign",
+            destination: variable.place,
+            value: this.implicitCopy(value),
+          },
+        ];
+      }
+    }
+    this.fail(node, "PLC1001", `${ts.SyntaxKind[node.kind]} is not supported in PLC scan code.`);
+  }
+
+  private switchStatement(node: ts.SwitchStatement, locals: Variable[]): Statement[] {
+    const origin = { span: span(node) };
+    this.breakTargets.push("switch");
+    try {
+      const value = this.expression(node.expression);
+      const cases: { values: Constant[]; body: Statement[] }[] = [];
+      let fallback: Statement[] = [];
+      let pending: Constant[] = [],
+        pendingDefault = false;
+      for (const clause of node.caseBlock.clauses) {
+        if (ts.isDefaultClause(clause)) pendingDefault = true;
+        else {
+          const constant = this.constant(this.expression(clause.expression, value.type));
+          if (!constant)
+            this.fail(clause, "PLC2001", "Case values must be compile-time constants.");
+          pending.push(constant);
+        }
+        if (!clause.statements.length) continue;
+        let statements = [...clause.statements];
+        const last = statements.at(-1);
+        if (last && ts.isBreakStatement(last) && !last.label) statements = statements.slice(0, -1);
+        else if (statements.length && !(last && ts.isReturnStatement(last)))
+          this.fail(
+            clause,
+            "PLC1001",
+            "Switch cases must end with break or return; fallthrough is prohibited.",
+          );
+        const body = this.statements(statements, locals);
+        if (pending.length) cases.push({ values: pending, body });
+        if (pendingDefault) fallback = body;
+        pending = [];
+        pendingDefault = false;
+      }
+      if (pending.length) cases.push({ values: pending, body: [] });
+      return [{ ...origin, kind: "switch", value, cases, fallback }];
+    } finally {
+      this.breakTargets.pop();
+    }
+  }
+
+  private localDeclarations(node: ts.VariableStatement, locals: Variable[]): Statement[] {
+    const origin = { span: span(node) };
+    if (!(node.declarationList.flags & (ts.NodeFlags.Let | ts.NodeFlags.Const)))
+      this.fail(node, "PLC1001", "Use let or const for invocation locals.");
+    return node.declarationList.declarations.flatMap((declaration) => {
+      if (!ts.isIdentifier(declaration.name))
+        this.fail(declaration, "PLC1001", "Destructuring is not supported.");
+      if (!declaration.initializer)
+        this.fail(declaration, "PLC3001", "Initialize invocation-local PLC variables explicitly.");
+      const annotation = declaration.type ? this.type(declaration.type) : undefined;
+      if (annotation && !this.resolver.isValue(annotation))
+        this.fail(
+          declaration,
+          "PLC2001",
+          "Invocation locals require value types, not instances or borrow schemas.",
+        );
+      if (annotation?.io)
+        this.fail(declaration, "PLC4002", "Logical I/O cannot be invocation-local.");
+      if (
+        !annotation &&
+        !(node.declarationList.flags & ts.NodeFlags.Const) &&
+        this.numericLiteral(declaration.initializer) === undefined &&
+        ![ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword].includes(
+          declaration.initializer.kind,
+        )
+      )
+        this.fail(declaration, "PLC2001", "Annotate mutable numeric storage explicitly.");
+      const initial = this.expression(declaration.initializer, annotation?.type);
+      if (
+        node.declarationList.flags & ts.NodeFlags.Const &&
+        initial.kind === "load" &&
+        aggregate(this.resolver.types.get(initial.type))
+      ) {
+        for (const segment of initial.place.path)
+          if (segment.kind === "index" && !this.unchanging(segment.value))
+            this.fail(
+              declaration,
+              "PLC3003",
+              "An alias index must keep its value while the alias is in scope; use copy(value) for a snapshot.",
+            );
+        this.aliases.set(this.resolver.symbol(declaration.name), initial.place);
+        return [];
+      }
+      this.recordCopySource(initial);
+      const value = this.implicitCopy(initial);
+      const variable: Variable = {
+        id: this.storageId(declaration, declaration.name.text),
+        name: declaration.name.text,
+        type: value.type,
+        storage: "local",
+        mutable: !(node.declarationList.flags & ts.NodeFlags.Const),
+        retain: false,
+        span: span(declaration),
+      };
+      this.variables.set(this.resolver.symbol(declaration.name), variable);
+      locals.push(variable);
+      // A const is assigned once, so its initializer's range holds wherever it is read.
+      const bound =
+        !variable.mutable &&
+        valueRange(value, this.resolver.types, this.byId(), this.ranges, this.instances);
+      if (bound) this.ranges.set(variable.id, bound);
+      return { ...origin, kind: "assign", destination: { root: variable.id, path: [] }, value };
+    });
+  }
+
+  private loop(node: ts.ForStatement, locals: Variable[]): Statement[] {
+    let counter: Variable;
+    let initializer: ts.Expression;
+    let existing = false;
+    if (node.initializer && ts.isVariableDeclarationList(node.initializer)) {
+      if (
+        !(node.initializer.flags & ts.NodeFlags.Let) ||
+        node.initializer.declarations.length !== 1
+      )
+        this.fail(
+          node,
+          "PLC1001",
+          "A bounded for loop requires one let counter or an existing counter assignment.",
+        );
+      const declaration = node.initializer.declarations[0]!;
+      if (!ts.isIdentifier(declaration.name) || !declaration.initializer)
+        this.fail(node, "PLC2001", "Initialize the integer loop counter.");
+      const annotation = declaration.type ? this.type(declaration.type) : { type: "DINT" };
+      if (annotation.io)
+        this.fail(declaration, "PLC4002", "Loop counters cannot use I/O wrappers.");
+      counter = {
+        id: this.storageId(declaration, declaration.name.text),
+        name: declaration.name.text,
+        type: annotation.type,
+        storage: "local",
+        mutable: true,
+        retain: false,
+        span: span(declaration),
+      };
+      this.variables.set(this.resolver.symbol(declaration.name), counter);
+      locals.push(counter);
+      initializer = declaration.initializer;
+    } else if (
+      node.initializer &&
+      ts.isBinaryExpression(node.initializer) &&
+      node.initializer.operatorToken.kind === ts.SyntaxKind.EqualsToken
+    ) {
+      const target = this.target(node.initializer.left);
+      counter = this.byId().get(target.place.root)!;
+      if (target.place.path.length || !["local", "module", "field"].includes(counter.storage))
+        this.fail(
+          node.initializer,
+          "PLC1001",
+          "An existing loop counter must be a local, module variable or private block field.",
+        );
+      initializer = node.initializer.right;
+      existing = true;
+    } else
+      this.fail(
+        node,
+        "PLC1001",
+        "Initialize one let counter or assign an existing counter in the for header.",
+      );
+    const type = counter.type,
+      plcType = this.resolver.types.get(type);
+    if (plcType?.kind !== "integer")
+      this.fail(node.initializer!, "PLC2001", "Loop counters require integer types.");
+    const startExpression = this.expression(initializer, type);
+    const start = this.constant(startExpression);
+    const isCounter = (expression: ts.Expression): boolean => {
+      const place = this.place(expression);
+      return place.root === counter.id && place.path.length === 0;
+    };
+    const condition = node.condition;
+    if (!condition || !ts.isBinaryExpression(condition) || !isCounter(condition.left))
+      this.fail(node, "PLC1001", "Loop condition must compare its counter to a bounded integer.");
+    const boundExpression = this.expression(condition.right, type);
+    const bound = this.constant(boundExpression);
+    let step: bigint;
+    const increment = node.incrementor;
+    if (
+      increment &&
+      (ts.isPostfixUnaryExpression(increment) || ts.isPrefixUnaryExpression(increment)) &&
+      isCounter(increment.operand) &&
+      [ts.SyntaxKind.PlusPlusToken, ts.SyntaxKind.MinusMinusToken].includes(increment.operator)
+    )
+      step = increment.operator === ts.SyntaxKind.PlusPlusToken ? 1n : -1n;
+    else if (
+      increment &&
+      ts.isBinaryExpression(increment) &&
+      isCounter(increment.left) &&
+      [ts.SyntaxKind.PlusEqualsToken, ts.SyntaxKind.MinusEqualsToken].includes(
+        increment.operatorToken.kind,
+      )
+    ) {
+      const amount = this.constant(this.expression(increment.right, type));
+      if (amount?.kind !== "integer" || BigInt(amount.value) <= 0n)
+        this.fail(increment, "PLC2001", "Loop step must be a positive constant integer.");
+      step =
+        BigInt(amount.value) *
+        (increment.operatorToken.kind === ts.SyntaxKind.PlusEqualsToken ? 1n : -1n);
+    } else this.fail(node, "PLC1001", "Use i++, i--, i += step or i -= step in the for header.");
+    const operator = condition.operatorToken.kind,
+      ascending = step > 0n;
+    if (
+      !(
+        ascending
+          ? [ts.SyntaxKind.LessThanToken, ts.SyntaxKind.LessThanEqualsToken]
+          : [ts.SyntaxKind.GreaterThanToken, ts.SyntaxKind.GreaterThanEqualsToken]
+      ).includes(operator)
+    )
+      this.fail(condition, "PLC2001", "Loop direction and comparison must agree.");
+    const exclusive =
+      operator === ts.SyntaxKind.LessThanToken || operator === ts.SyntaxKind.GreaterThanToken;
+    if (start?.kind !== "integer" || bound?.kind !== "integer") {
+      const startRange = interval(startExpression, this.resolver.types, this.byId(), this.ranges);
+      const limitRange = interval(boundExpression, this.resolver.types, this.byId(), this.ranges);
+      if (!startRange || !limitRange)
+        this.fail(node, "PLC2001", "Loop bounds require finite integer ranges.");
+      const proof = loopBounds(startRange, limitRange, step, exclusive);
+      if (proof.count > 1_000_000n)
+        this.fail(node, "PLC2001", "A scan loop cannot exceed 1,000,000 iterations.");
+      if (existing && proof.count > 0n) {
+        const terminal = (step > 0n ? proof.range[1] : proof.range[0]) + step;
+        const [minimum, maximum] = integerRange(plcType);
+        if (terminal < minimum || terminal > maximum)
+          this.fail(
+            node,
+            "PLC2001",
+            "The existing loop counter would overflow on its final increment.",
+          );
+      }
+      this.loopCounters.add(counter.id);
+      this.ranges.set(counter.id, proof.range);
+      this.breakTargets.push("loop");
+      try {
+        return [
+          {
+            span: span(node),
+            kind: "for",
+            counter: counter.id,
+            ...(existing && { counterScope: "existing" as const }),
+            start: startExpression,
+            limit: boundExpression,
+            step: String(step),
+            ...(exclusive && { exclusive: true as const }),
+            maxIterations: Number(proof.count),
+            body: this.body(node.statement, locals),
+          },
+        ];
+      } finally {
+        this.breakTargets.pop();
+        this.loopCounters.delete(counter.id);
+        this.ranges.delete(counter.id);
+      }
+    }
+    const finish = BigInt(bound.value) + (exclusive ? (ascending ? -1n : 1n) : 0n),
+      first = BigInt(start.value);
+    const count = loopIterations(first, finish, step);
+    if (count > 1_000_000n)
+      this.fail(node, "PLC2001", "A scan loop cannot exceed 1,000,000 iterations.");
+    if (existing) {
+      const terminal = first + count * step,
+        [minimum, maximum] = integerRange(plcType);
+      if (terminal < minimum || terminal > maximum)
+        this.fail(
+          node,
+          "PLC2001",
+          "The existing loop counter would overflow on its final increment.",
+        );
+    }
+    this.loopCounters.add(counter.id);
+    this.ranges.set(counter.id, first <= finish ? [first, finish] : [finish, first]);
+    let body: Statement[];
+    this.breakTargets.push("loop");
+    try {
+      body = this.body(node.statement, locals);
+    } finally {
+      this.breakTargets.pop();
+      this.loopCounters.delete(counter.id);
+      this.ranges.delete(counter.id);
+    }
+    if (!count)
+      return existing
+        ? [
+            {
+              kind: "assign",
+              destination: { root: counter.id, path: [] },
+              value: { kind: "constant", type, value: start, span: span(initializer) },
+              span: span(node.initializer!),
+            },
+          ]
+        : [];
+    const limit: Expression = {
+      kind: "constant",
+      type,
+      value: { kind: "integer", value: String(finish) },
+      span: span(condition.right),
+    };
+    return [
+      {
+        span: span(node),
+        kind: "for",
+        counter: counter.id,
+        ...(existing && { counterScope: "existing" as const }),
+        start: { kind: "constant", type, value: start, span: span(initializer) },
+        limit,
+        step: String(step),
+        maxIterations: Number(count),
+        body,
+      },
+    ];
+  }
+
+  /**
+   * `for (const element of array)` is a bounded FOR over the array's declared bounds whose
+   * element binding aliases `array[counter]`. `array.entries()` also binds the counter. An
+   * enum-keyed Record iterates with `Object.values(record)`, or SDK `entries(record)` for its key.
+   */
+  private forOf(node: ts.ForOfStatement, locals: Variable[]): Statement[] {
+    const list = node.initializer;
+    if (
+      node.awaitModifier ||
+      !ts.isVariableDeclarationList(list) ||
+      !(list.flags & ts.NodeFlags.Const) ||
+      list.declarations.length !== 1
+    )
+      this.fail(node, "PLC1001", "for…of binds one const element of a PLC array.");
+    let iterated = node.expression,
+      form: "elements" | "entries" | "recordValues" | "recordEntries" = "elements";
+    if (ts.isCallExpression(iterated)) {
+      const callee = iterated.expression;
+      if (
+        ts.isPropertyAccessExpression(callee) &&
+        callee.name.text === "entries" &&
+        !iterated.arguments.length
+      ) {
+        form = "entries";
+        iterated = callee.expression;
+      } else if (iterated.arguments.length === 1) {
+        if (this.sdkCall(iterated) === "entries") form = "recordEntries";
+        else if (
+          ts.isPropertyAccessExpression(callee) &&
+          callee.name.text === "values" &&
+          ts.isIdentifier(callee.expression) &&
+          this.resolver.standardLibrary(this.resolver.symbol(callee.expression))
+        )
+          form = "recordValues";
+        if (form !== "elements") iterated = iterated.arguments[0]!;
+      }
+    }
+    const binding = list.declarations[0]!.name,
+      keyed = form === "entries" || form === "recordEntries";
+    const names = ts.isArrayBindingPattern(binding)
+      ? binding.elements.map((element) =>
+          ts.isBindingElement(element) &&
+          !element.dotDotDotToken &&
+          !element.initializer &&
+          ts.isIdentifier(element.name)
+            ? element.name
+            : undefined,
+        )
+      : [undefined, ts.isIdentifier(binding) ? binding : undefined];
+    const [indexName, elementName] = names;
+    if (names.length !== 2 || !elementName || Boolean(indexName) !== keyed)
+      this.fail(
+        binding,
+        "PLC1001",
+        "Bind one element, or destructure [index, element] from array.entries() or entries(record).",
+      );
+    const place = this.place(iterated),
+      array = this.resolver.types.get(
+        placeType(place, this.resolver.types, this.byId(), this.ranges).type ?? "",
+      );
+    if (array?.kind !== "array" || Boolean(array.index) !== form.startsWith("record"))
+      this.fail(
+        node.expression,
+        "PLC2001",
+        "for…of iterates a FixedArray, array.entries(), or an enum-keyed Record through Object.values(record) or entries(record).",
+      );
+    for (const segment of place.path)
+      if (segment.kind === "index" && !this.unchanging(segment.value))
+        this.fail(node.expression, "PLC3003", "An iterated array's index must keep its value.");
+
+    const origin = { span: span(node) };
+    const local = (declaration: ts.Node, name: string, type: string): Variable => {
+      const variable: Variable = {
+        id: this.storageId(declaration, name),
+        name,
+        type,
+        storage: "local",
+        mutable: true,
+        retain: false,
+        span: span(declaration),
+      };
+      locals.push(variable);
+      return variable;
+    };
+    const constant = (type: string, value: string): Expression => ({
+      ...origin,
+      kind: "constant",
+      type,
+      value: { kind: "integer", value },
+    });
+    const counter = local(node, form === "entries" && indexName ? indexName.text : "index", "DINT"),
+      index: Expression = {
+        ...origin,
+        kind: "load",
+        type: "DINT",
+        place: { root: counter.id, path: [] },
+      };
+    const before: Statement[] = [],
+      prefix: Statement[] = [];
+    const readonly = [counter.id];
+    const enumeration = array.index ? this.resolver.types.get(array.index) : undefined;
+    if (indexName && enumeration?.kind === "enum") {
+      // The enum key follows the counter: a CASE at the top of each iteration selects its member.
+      const key = local(indexName, indexName.text, enumeration.id);
+      const assign = (value: string): Statement => ({
+        ...origin,
+        kind: "assign",
+        destination: { root: key.id, path: [] },
+        value: constant(key.type, value),
+      });
+      before.push(assign(String(array.lowerBound)));
+      prefix.push({
+        ...origin,
+        kind: "switch",
+        value: index,
+        cases: enumeration.members.map((member) => ({
+          values: [{ kind: "integer", value: member.value }],
+          body: [assign(member.value)],
+        })),
+        fallback: [],
+      });
+      readonly.push(key.id);
+      this.variables.set(this.resolver.symbol(indexName), key);
+    } else if (indexName) this.variables.set(this.resolver.symbol(indexName), counter);
+    this.aliases.set(this.resolver.symbol(elementName), {
+      root: place.root,
+      path: [...place.path, { kind: "index", value: index }],
+    });
+
+    const upper = array.lowerBound + array.length - 1;
+    for (const id of readonly) this.loopCounters.add(id);
+    this.ranges.set(counter.id, [BigInt(array.lowerBound), BigInt(upper)]);
+    this.breakTargets.push("loop");
+    try {
+      return [
+        ...before,
+        {
+          ...origin,
+          kind: "for",
+          counter: counter.id,
+          start: constant("DINT", String(array.lowerBound)),
+          limit: constant("DINT", String(upper)),
+          step: "1",
+          maxIterations: array.length,
+          body: [...prefix, ...this.body(node.statement, locals)],
+        },
+      ];
+    } finally {
+      this.breakTargets.pop();
+      for (const id of readonly) this.loopCounters.delete(id);
+      this.ranges.delete(counter.id);
+    }
+  }
+}