@thigasdevelopment/luam 0.19.1 → 0.19.3

package/luam.mjs

@@ -1644,8 +1644,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {boolean} [combine] - if `true` or omitted, an optional value can be specified directly after the flag.
        * @return {Command} `this` command for chaining
        */
-      combineFlagAndOptionalValue(combine = true) {
-        this._combineFlagAndOptionalValue = !!combine;
+      combineFlagAndOptionalValue(combine2 = true) {
+        this._combineFlagAndOptionalValue = !!combine2;
         return this;
       }
       /**
@@ -3143,6 +3143,7 @@ var DEFAULT_ENVIRONMENT_FILE = ".env";
 var DEFAULT_LOCAL_ENVIRONMENT_FILE = ".env.local";
 var DEFAULT_ASSET_DESTINATION = ".";
 var DEFAULT_OUT_DIR = "build";
+var DEFAULT_CONTRACTS_DIR = ".luam/contracts";
 var DEFAULT_RESOURCES_DIR = "mods/deathmatch/resources";
 var DEFAULT_COMPILER_OPTIONS = {
   strict: true,
@@ -3252,7 +3253,7 @@ var EXIT_USAGE = 2;
 // src/config/manifest-context.ts
 var DEVELOPMENT_MODE = "development";
 var PRODUCTION_MODE = "production";
-var DEVELOPMENT_COMMANDS = ["dev", "ensure", "server"];
+var DEVELOPMENT_COMMANDS = ["dev", "ensure", "server", "test"];
 var PRODUCTION_COMMANDS = ["build"];
 function manifestMode(command) {
   if (DEVELOPMENT_COMMANDS.includes(command)) {
@@ -3492,14 +3493,14 @@ function readEscape(cursor) {
 }
 function scanQuotedString(cursor, diagnostics) {
   const position2 = cursor.position();
-  const quote2 = cursor.peek();
+  const quote3 = cursor.peek();
   cursor.advance();
   let value = "";
-  while (!cursor.isEof() && cursor.peek() !== quote2 && !isLineBreak(cursor.peek())) {
+  while (!cursor.isEof() && cursor.peek() !== quote3 && !isLineBreak(cursor.peek())) {
     value += cursor.peek() === "\\" ? readEscape(cursor) : cursor.advance();
   }
-  if (cursor.peek() !== quote2) {
-    const message = `Unterminated string. Close it with ${quote2}.`;
+  if (cursor.peek() !== quote3) {
+    const message = `Unterminated string. Close it with ${quote3}.`;
     diagnostics.push(createDiagnostic("lexer", "lex-unterminated-string", message, position2));
     return value;
   }
@@ -3827,19 +3828,21 @@ function parseTypeName(stream) {
   return { kind: "type-name", name: token.value, typeArguments, position: token.position };
 }
 function parseParameterType(stream) {
+  let name = null;
   if (stream.check("identifier") && stream.checkAhead(1, "punctuation", ":")) {
-    stream.next();
+    name = stream.next().value;
     stream.next();
   }
-  return parseTypeAnnotation(stream);
+  return { name, annotation: parseTypeAnnotation(stream) };
 }
 function parseFunctionType(stream) {
   const position2 = stream.expect("identifier", FUNCTION_TYPE).position;
   if (!stream.check("punctuation", "(")) {
-    return { kind: "type-function", parameters: [], isVariadic: true, returnType: null, position: position2 };
+    return { kind: "type-function", parameters: [], parameterNames: [], isVariadic: true, returnType: null, position: position2 };
   }
   stream.next();
   const parameters = [];
+  const parameterNames = [];
   let isVariadic = false;
   while (!stream.check("punctuation", ")") && !stream.isEof()) {
     if (stream.match("operator", "...")) {
@@ -3848,7 +3851,9 @@ function parseFunctionType(stream) {
         parseTypeAnnotation(stream);
       }
     } else {
-      parameters.push(parseParameterType(stream));
+      const parameter = parseParameterType(stream);
+      parameters.push(parameter.annotation);
+      parameterNames.push(parameter.name);
     }
     if (!stream.match("punctuation", ",")) {
       break;
@@ -3856,7 +3861,7 @@ function parseFunctionType(stream) {
   }
   stream.expect("punctuation", ")");
   const returnType = stream.match("punctuation", ":") ? parseTypeAnnotation(stream) : null;
-  return { kind: "type-function", parameters, isVariadic, returnType, position: position2 };
+  return { kind: "type-function", parameters, parameterNames, isVariadic, returnType, position: position2 };
 }
 function parseGroupedType(stream) {
   const position2 = stream.expect("punctuation", "(").position;
@@ -3989,10 +3994,18 @@ function parseNamedAnnotation(stream, declaration) {
   if (optional === null && annotation?.kind === "type-optional") {
     stream.report("parse-optional-position", `Write optional ${label2} as "name?: Type", not "name: Type?".`, annotation.position);
   }
+  if (optional !== null && annotation?.kind === "type-optional") {
+    const message = `The marker on the name already allows "nil". Remove the "?" after the type.`;
+    stream.report("parse-redundant-optional", message, annotation.position);
+  }
   if (optional !== null && annotation !== null) {
     stream.eraseFrom(checkpoint);
   }
-  return optional === null || annotation === null ? annotation : { kind: "type-optional", element: annotation, position: optional.position };
+  if (optional === null || annotation === null) {
+    return annotation;
+  }
+  const element = annotation.kind === "type-optional" ? annotation.element : annotation;
+  return { kind: "type-optional", element, position: optional.position };
 }
 
 // ../compiler/src/parser/function-expression.ts
@@ -4146,7 +4159,8 @@ function parsePrimary(stream) {
   if (token.kind === "keyword" && token.value === "new" && stream.checkAhead(1, "identifier")) {
     stream.next();
     const className = stream.next().value;
-    return { kind: "new-expression", className, args: parseArguments(stream), position: token.position };
+    const typeArguments = parseNewTypeArguments(stream);
+    return { kind: "new-expression", className, typeArguments, args: parseArguments(stream), position: token.position };
   }
   if (token.kind === "keyword" && CALLABLE_KEYWORDS.has(token.value) && stream.checkAhead(1, "punctuation", "(")) {
     stream.next();
@@ -4178,6 +4192,20 @@ function parsePrimary(stream) {
   }
   throw stream.error(`Unexpected "${stream.describeCurrent()}" in expression.`, "parse-unexpected-token");
 }
+function parseNewTypeArguments(stream) {
+  const args = [];
+  if (!stream.check("operator", "<")) {
+    return args;
+  }
+  const checkpoint = stream.checkpoint();
+  stream.next();
+  do {
+    args.push(parseTypeAnnotation(stream));
+  } while (stream.match("punctuation", ","));
+  stream.expect("operator", ">");
+  stream.eraseFrom(checkpoint);
+  return args;
+}
 function parseArguments(stream) {
   if (stream.check("string") || stream.check("template") || stream.check("punctuation", "{")) {
     return [parsePrimary(stream)];
@@ -4464,8 +4492,23 @@ var TokenStream = class {
 // ../compiler/src/parser/declarations.ts
 var DECLARATION_NAMES = /* @__PURE__ */ new Set(["class", "interface", "enum"]);
 var CLASS_MODIFIERS = /* @__PURE__ */ new Set(["extends", "implements"]);
+function skipTypeParameters(stream, offset) {
+  if (!stream.checkAhead(offset, "operator", "<")) {
+    return offset;
+  }
+  let depth = 0;
+  let index = offset;
+  do {
+    const token = stream.peek(index);
+    depth += token.kind === "operator" && token.value === "<" ? 1 : 0;
+    depth -= token.kind === "operator" && token.value === ">" ? 1 : 0;
+    index += 1;
+  } while (depth > 0 && stream.peek(index).kind !== "eof");
+  return index;
+}
 function isClassHeader(stream, offset = 0) {
-  return stream.checkAhead(offset + 2, "punctuation", "{") || stream.checkAhead(offset + 2, "keyword", "extends") || stream.checkAhead(offset + 2, "keyword", "implements");
+  const after = skipTypeParameters(stream, offset + 2);
+  return stream.checkAhead(after, "punctuation", "{") || stream.checkAhead(after, "keyword", "extends") || stream.checkAhead(after, "keyword", "implements");
 }
 function isDeclarationStart(stream) {
   let offset = 0;
@@ -4595,10 +4638,40 @@ function parseClassMember(stream) {
   expectClassFieldBoundary(stream, token);
   return { kind: "class-field", name: token.value, annotation, value, decorators, isStatic, position: token.position };
 }
+function parseTypeParameters(stream) {
+  const list = { names: [], constraints: [] };
+  if (!stream.check("operator", "<")) {
+    return list;
+  }
+  const checkpoint = stream.checkpoint();
+  stream.next();
+  do {
+    list.names.push(stream.expect("identifier").value);
+    list.constraints.push(stream.match("keyword", "extends") ? parseTypeAnnotation(stream) : null);
+  } while (stream.match("punctuation", ","));
+  stream.expect("operator", ">");
+  stream.eraseFrom(checkpoint);
+  return list;
+}
+function parseTypeArguments(stream) {
+  const args = [];
+  if (!stream.check("operator", "<")) {
+    return args;
+  }
+  const checkpoint = stream.checkpoint();
+  stream.next();
+  do {
+    args.push(parseTypeAnnotation(stream));
+  } while (stream.match("punctuation", ","));
+  stream.expect("operator", ">");
+  stream.eraseFrom(checkpoint);
+  return args;
+}
 function parseClassModifiers(stream, declaration) {
   while (stream.check("keyword") && CLASS_MODIFIERS.has(stream.current().value)) {
     if (stream.next().value === "extends") {
       declaration.superClass = stream.expect("identifier").value;
+      declaration.superClassArguments = parseTypeArguments(stream);
       continue;
     }
     do {
@@ -4609,7 +4682,19 @@ function parseClassModifiers(stream, declaration) {
 function parseClassDeclaration(stream, decorators) {
   const position2 = stream.next().position;
   const name = stream.expect("identifier").value;
-  const declaration = { kind: "class-declaration", name, superClass: null, interfaces: [], members: [], decorators, position: position2 };
+  const typeParameters = parseTypeParameters(stream);
+  const declaration = {
+    kind: "class-declaration",
+    name,
+    typeParameters: typeParameters.names,
+    typeConstraints: typeParameters.constraints,
+    superClass: null,
+    superClassArguments: [],
+    interfaces: [],
+    members: [],
+    decorators,
+    position: position2
+  };
   parseClassModifiers(stream, declaration);
   stream.expect("punctuation", "{");
   while (!stream.check("punctuation", "}") && !stream.isEof()) {
@@ -5069,8 +5154,8 @@ var TABLE_TYPE = { kind: "table" };
 function createArray(element) {
   return { kind: "array", element };
 }
-function createNamed(name) {
-  return { kind: "named", name };
+function createNamed(name, typeArguments = []) {
+  return typeArguments.length === 0 ? { kind: "named", name } : { kind: "named", name, typeArguments };
 }
 function createMap(key, value) {
   return { kind: "map", key, value };
@@ -5183,6 +5268,12 @@ function createUnion(options) {
   }
   return { kind: "union", options: flattened };
 }
+function namedNesting(type) {
+  if (type.kind !== "named") {
+    return 0;
+  }
+  return 1 + Math.max(0, ...(type.typeArguments ?? []).map(namedNesting));
+}
 function typeToString(type) {
   if (type.kind === "array") {
     return `${typeToString(type.element)}[]`;
@@ -5202,7 +5293,11 @@ function typeToString(type) {
   if (type.kind === "boolean-literal" || type.kind === "number-literal") {
     return String(type.value);
   }
-  if (type.kind === "named" || type.kind === "record") {
+  if (type.kind === "named") {
+    const args = type.typeArguments ?? [];
+    return args.length === 0 ? type.name : `${type.name}<${args.map(typeToString).join(", ")}>`;
+  }
+  if (type.kind === "record") {
     return type.name;
   }
   if (type.kind === "tuple") {
@@ -5292,6 +5387,59 @@ function isRecordAssignable(source, target, options) {
   }
   return true;
 }
+function isNamedAssignable(source, target, options) {
+  const sourceArguments = source.typeArguments ?? [];
+  const targetArguments = target.typeArguments ?? [];
+  if (source.name !== target.name || sourceArguments.length === 0 || targetArguments.length !== sourceArguments.length) {
+    return true;
+  }
+  return sourceArguments.every((argument, index) => isAssignable(argument, targetArguments[index] ?? ANY_TYPE, options));
+}
+function asRecord(name, members) {
+  return { kind: "record", name, origin: null, members };
+}
+function shapeOf(name, options) {
+  return options.resolveNominal?.(name) ?? null;
+}
+function withVisit(options, pair) {
+  return { ...options, visited: /* @__PURE__ */ new Set([...options.visited ?? [], pair]) };
+}
+function isNominalAssignable(source, target, options) {
+  const pair = `${source.name}>${target.name}`;
+  if (options.visited?.has(pair) === true) {
+    return true;
+  }
+  const declared = shapeOf(target.name, options);
+  const actual = shapeOf(source.name, options);
+  if (declared === null || actual === null) {
+    return true;
+  }
+  if (declared.kind === "class" || actual.kind === "class") {
+    return actual.kind === "class" && actual.ancestors.has(target.name);
+  }
+  return isRecordAssignable(asRecord(source.name, actual.members), asRecord(target.name, declared.members), withVisit(options, pair));
+}
+var SCALAR_KINDS = /* @__PURE__ */ new Set(["string", "number", "boolean", "thread", "userdata", "void", "nil", "function"]);
+function isNamedSourceAssignable(source, target, options) {
+  const actual = shapeOf(source.name, options);
+  if (actual === null) {
+    return true;
+  }
+  if (actual.kind === "class") {
+    return !SCALAR_KINDS.has(target.kind) && !isLiteralType(target);
+  }
+  return isAssignable(asRecord(source.name, actual.members), target, options);
+}
+function isNamedTargetAssignable(source, target, options) {
+  const declared = shapeOf(target.name, options);
+  if (declared === null) {
+    return true;
+  }
+  if (declared.kind === "class") {
+    return false;
+  }
+  return isAssignable(source, asRecord(target.name, declared.members), options);
+}
 function isAssignable(source, target, options = { allowNil: false }) {
   if (source.kind === "any" || target.kind === "any" || target.kind === "unknown") {
     return true;
@@ -5299,9 +5447,6 @@ function isAssignable(source, target, options = { allowNil: false }) {
   if (source.kind === "tuple" || target.kind === "tuple") {
     return isAssignable(firstValueOf(source), firstValueOf(target), options);
   }
-  if (source.kind === "named" || target.kind === "named") {
-    return true;
-  }
   if (source.kind === "nil" && (options.allowNil || target.kind === "optional" || target.kind === "nil")) {
     return true;
   }
@@ -5320,6 +5465,15 @@ function isAssignable(source, target, options = { allowNil: false }) {
   if (target.kind === "optional") {
     return isAssignable(source, target.element, options);
   }
+  if (source.kind === "named" && target.kind === "named") {
+    return source.name === target.name ? isNamedAssignable(source, target, options) : isNominalAssignable(source, target, options);
+  }
+  if (source.kind === "named") {
+    return isNamedSourceAssignable(source, target, options);
+  }
+  if (target.kind === "named") {
+    return isNamedTargetAssignable(source, target, options);
+  }
   if (target.kind === "table") {
     return isTableLike(source) || source.kind === "record";
   }
@@ -5458,7 +5612,8 @@ var RUNTIME_HELPERS = {
   math: { name: "math", file: "math.lua", injection: "automatic", features: ["number-extension"] },
   string: { name: "string", file: "string.lua", injection: "automatic", features: ["string-extension", "template-string"] },
   table: { name: "table", file: "table.lua", injection: "automatic", features: ["table-extension"] },
-  threads: { name: "threads", file: "threads.lua", injection: "reference", features: ["thread"], globals: ["sleep", "Threads"] }
+  threads: { name: "threads", file: "threads.lua", injection: "reference", features: ["thread"], globals: ["sleep", "Threads"] },
+  validate: { name: "validate", file: "validate.lua", injection: "automatic", features: ["boundary-validation"] }
 };
 var DEVELOPMENT_RUNTIME_HELPERS = {
   "development-logs-client": {
@@ -5599,6 +5754,11 @@ var MANIFEST_FIELDS = [
     owner: "dependencies",
     allowEmpty: true
   }),
+  field("contracts", STRING_TYPE, "Directory the export contract is written to and dependency contracts are read from.", {
+    defaultValue: DEFAULT_CONTRACTS_DIR,
+    rule: "contained-path",
+    owner: "dependencies"
+  }),
   table("engine", "Requirements the MTA server and client must meet.", ENGINE_FIELDS, { defaultValue: {}, owner: "engine" }),
   table("environment", "Files that declare and override the project environment.", ENVIRONMENT_FIELDS, { defaultValue: {}, owner: "environment" }),
   field("outDir", STRING_TYPE, "Directory the built resource is written to.", { defaultValue: DEFAULT_OUT_DIR, rule: "static-path", owner: "output" }),
@@ -5758,8 +5918,8 @@ function isNumber(type) {
 function isText(type) {
   return type.kind === "string" || type.kind === "string-literal" || type.kind === "any";
 }
-function fail(operator, expected, left, right, describe) {
-  const culprit = describe(isNumber(left) || isText(left) ? right : left);
+function fail(operator, expected, left, right, describe2) {
+  const culprit = describe2(isNumber(left) || isText(left) ? right : left);
   return { evaluated: null, error: `"${operator}" expects ${expected} on both sides but received ${culprit}.` };
 }
 function arithmetic(operator, left, right) {
@@ -5798,22 +5958,22 @@ function applyOr(left, right) {
   const value = isTruthy(left.value) ? left.value : right.value;
   return { value, type: unionOf([left.truthy, right.type]), truthy: unionOf([left.truthy, right.truthy]), falsy: right.falsy };
 }
-function applyOrdering(operator, left, right, describe) {
+function applyOrdering(operator, left, right, describe2) {
   const numeric = isNumber(left.type) && isNumber(right.type);
   const textual = isText(left.type) && isText(right.type);
   if (!numeric && !textual) {
-    return fail(operator, "two numbers or two strings", left.type, right.type, describe);
+    return fail(operator, "two numbers or two strings", left.type, right.type, describe2);
   }
   return { evaluated: booleanValue(compare(operator, left.value, right.value)), error: null };
 }
-function applyConcat(left, right, describe) {
+function applyConcat(left, right, describe2) {
   const usable = (type) => isText(type) || isNumber(type);
   if (!usable(left.type) || !usable(right.type)) {
-    return fail("..", "a string or a number", left.type, right.type, describe);
+    return fail("..", "a string or a number", left.type, right.type, describe2);
   }
   return { evaluated: stringValue(`${left.value}${right.value}`), error: null };
 }
-function applyBinary(operator, left, right, describe) {
+function applyBinary(operator, left, right, describe2) {
   if (operator === "and") {
     return { evaluated: applyAnd(left, right), error: null };
   }
@@ -5825,23 +5985,23 @@ function applyBinary(operator, left, right, describe) {
     return { evaluated: booleanValue(operator === "==" ? same : !same), error: null };
   }
   if (ORDERING.includes(operator)) {
-    return applyOrdering(operator, left, right, describe);
+    return applyOrdering(operator, left, right, describe2);
   }
   if (operator === "..") {
-    return applyConcat(left, right, describe);
+    return applyConcat(left, right, describe2);
   }
   if (!isNumber(left.type) || !isNumber(right.type)) {
-    return fail(operator, "a number", left.type, right.type, describe);
+    return fail(operator, "a number", left.type, right.type, describe2);
   }
   return { evaluated: numberValue(arithmetic(operator, left.value, right.value)), error: null };
 }
-function applyUnary(operator, operand, describe) {
+function applyUnary(operator, operand, describe2) {
   if (operator === "not") {
     return { evaluated: booleanValue(!isTruthy(operand.value)), error: null };
   }
   if (operator === "-") {
     if (!isNumber(operand.type)) {
-      return { evaluated: null, error: `"-" expects a number but received ${describe(operand.type)}.` };
+      return { evaluated: null, error: `"-" expects a number but received ${describe2(operand.type)}.` };
     }
     return { evaluated: numberValue(-operand.value), error: null };
   }
@@ -6300,8 +6460,8 @@ var RuleWalk = class {
   }
 };
 function normalizeManifest(value, positions) {
-  const walk3 = new RuleWalk(positions);
-  return { value: walk3.fields(MANIFEST_FIELDS, value, "", ""), diagnostics: walk3.diagnostics };
+  const walk4 = new RuleWalk(positions);
+  return { value: walk4.fields(MANIFEST_FIELDS, value, "", ""), diagnostics: walk4.diagnostics };
 }
 
 // ../compiler/src/manifest/manifest-analysis.ts
@@ -6537,6 +6697,7 @@ function validateConfig(value, positions) {
     sources: readSourceMapping(value),
     assets: readAssetMappings(value),
     dependencies,
+    contracts: readString(value, "contracts") ?? "",
     engine: readEngine(value),
     environment: readEnvironmentFiles(value),
     outDir: readString(value, "outDir") ?? "",
@@ -6601,7 +6762,7 @@ import { tmpdir } from "node:os";
 import { join as join2 } from "node:path";
 
 // src/cli/version.ts
-var VERSION = true ? "0.19.1" : "0.0.0-dev";
+var VERSION = true ? "0.19.3" : "0.0.0-dev";
 var PROGRAM_NAME = "luam";
 var PROGRAM_DESCRIPTION = "luam \u2014 the Luam compiler for Multi Theft Auto resources.";
 
@@ -6786,9 +6947,9 @@ function pluralize(count, singular, plural = `${singular}s`) {
 var MAX_ENTRIES_PER_FILE = 10;
 var MAX_FILES = 10;
 var GUTTER_WIDTH = 6;
-function groupByFile(entries2) {
+function groupByFile(entries3) {
   const groups = /* @__PURE__ */ new Map();
-  for (const entry of entries2) {
+  for (const entry of entries3) {
     const group = groups.get(entry.path);
     if (group === void 0) {
       groups.set(entry.path, [entry]);
@@ -6835,19 +6996,19 @@ function emit(reporter, entry, block) {
   }
   reporter.rawWarn(block);
 }
-function reportGroup(reporter, path, entries2, options) {
+function reportGroup(reporter, path, entries3, options) {
   const limit = options.maxPerFile ?? MAX_ENTRIES_PER_FILE;
   const source = options.sources.get(path);
   reporter.raw(reporter.style.paint("strong", path));
-  for (const entry of entries2.slice(0, limit)) {
+  for (const entry of entries3.slice(0, limit)) {
     emit(reporter, entry, entryBlock(reporter, entry, source));
   }
-  if (entries2.length > limit) {
-    reporter.detail(`  ... and ${pluralize(entries2.length - limit, "more diagnostic")} in this file.`);
+  if (entries3.length > limit) {
+    reporter.detail(`  ... and ${pluralize(entries3.length - limit, "more diagnostic")} in this file.`);
   }
 }
-function reportGroupedDiagnostics(reporter, entries2, options) {
-  const groups = [...groupByFile(entries2)];
+function reportGroupedDiagnostics(reporter, entries3, options) {
+  const groups = [...groupByFile(entries3)];
   const limit = options.maxFiles ?? MAX_FILES;
   for (const [path, group] of groups.slice(0, limit)) {
     reportGroup(reporter, path, group, options);
@@ -6863,9 +7024,9 @@ function formatFileDiagnostic(entry) {
   const location = `${path}:${diagnostic.position.line}:${diagnostic.position.column}`;
   return `${location} ${diagnostic.severity} ${diagnostic.code}: ${diagnostic.message}`;
 }
-function countFileDiagnostics(entries2) {
-  const errors = entries2.filter((entry) => entry.diagnostic.severity === "error").length;
-  return { errors, warnings: entries2.length - errors };
+function countFileDiagnostics(entries3) {
+  const errors = entries3.filter((entry) => entry.diagnostic.severity === "error").length;
+  return { errors, warnings: entries3.length - errors };
 }
 function countCliDiagnostics(diagnostics) {
   const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error").length;
@@ -6875,8 +7036,8 @@ function reportManifestDiagnostics(reporter, path, source, diagnostics) {
   if (diagnostics.length === 0) {
     return;
   }
-  const entries2 = diagnostics.map((diagnostic) => ({ path, diagnostic }));
-  reportFileDiagnostics(reporter, entries2, /* @__PURE__ */ new Map([[path, source]]));
+  const entries3 = diagnostics.map((diagnostic) => ({ path, diagnostic }));
+  reportFileDiagnostics(reporter, entries3, /* @__PURE__ */ new Map([[path, source]]));
 }
 function reportCliDiagnostics(reporter, diagnostics) {
   for (const diagnostic of diagnostics) {
@@ -6888,8 +7049,8 @@ function reportCliDiagnostics(reporter, diagnostics) {
     reporter.warn(line2);
   }
 }
-function reportPlainFileDiagnostics(reporter, entries2) {
-  for (const entry of entries2) {
+function reportPlainFileDiagnostics(reporter, entries3) {
+  for (const entry of entries3) {
     const line2 = formatFileDiagnostic(entry);
     if (entry.diagnostic.severity === "error") {
       reporter.rawError(line2);
@@ -6898,12 +7059,12 @@ function reportPlainFileDiagnostics(reporter, entries2) {
     reporter.rawWarn(line2);
   }
 }
-function reportFileDiagnostics(reporter, entries2, sources) {
+function reportFileDiagnostics(reporter, entries3, sources) {
   if (!reporter.capability.interactive) {
-    reportPlainFileDiagnostics(reporter, entries2);
+    reportPlainFileDiagnostics(reporter, entries3);
     return;
   }
-  reportGroupedDiagnostics(reporter, entries2, { sources });
+  reportGroupedDiagnostics(reporter, entries3, { sources });
 }
 function formatCounts(counts) {
   return `${pluralize(counts.errors, "error")}, ${pluralize(counts.warnings, "warning")}`;
@@ -7154,8 +7315,153 @@ function addProjectOptions(command) {
   return command.addOption(cwdOption()).addOption(manifestOption()).addOption(colorOption());
 }
 
+// src/build/contract-files.ts
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { dirname as dirname2, resolve as resolve4 } from "node:path";
+
+// ../compiler/src/project/export-abi.ts
+var ABI_VERSION = 1;
+var ABI_EXTENSION = ".abi.json";
+var MAX_ABI_BYTES = 262144;
+var MAX_EXPORTS = 512;
+var MAX_PARAMETERS = 32;
+var MAX_TYPE_LENGTH = 512;
+var NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var RESOURCE_PATTERN = /^[A-Za-z0-9_-]+$/;
+var SIDES = /* @__PURE__ */ new Set(["server", "client", "shared"]);
+function serializeAbi(abi) {
+  const exports = [...abi.exports].sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+  return `${JSON.stringify({ abi: abi.abi, resource: abi.resource, exports }, null, 4)}
+`;
+}
+function readString2(value, limit) {
+  return typeof value === "string" && value.length > 0 && value.length <= limit ? value : null;
+}
+function readParameter(value) {
+  if (typeof value !== "object" || value === null) {
+    return null;
+  }
+  const entry = value;
+  const name = readString2(entry.name, 64);
+  const type = readString2(entry.type, MAX_TYPE_LENGTH);
+  return name === null || type === null || !NAME_PATTERN.test(name) ? null : { name, type };
+}
+function readExport(value) {
+  if (typeof value !== "object" || value === null) {
+    return null;
+  }
+  const entry = value;
+  const name = readString2(entry.name, 128);
+  const side2 = readString2(entry.side, 16);
+  const returns = readString2(entry.returns, MAX_TYPE_LENGTH);
+  const parameters = Array.isArray(entry.parameters) ? entry.parameters : null;
+  if (name === null || !NAME_PATTERN.test(name) || side2 === null || !SIDES.has(side2) || returns === null || parameters === null) {
+    return null;
+  }
+  if (parameters.length > MAX_PARAMETERS) {
+    return null;
+  }
+  const read = parameters.map(readParameter);
+  if (read.some((parameter) => parameter === null)) {
+    return null;
+  }
+  return {
+    name,
+    side: side2,
+    http: entry.http === true,
+    parameters: read,
+    minimumArguments: typeof entry.minimumArguments === "number" && Number.isInteger(entry.minimumArguments) ? entry.minimumArguments : 0,
+    variadic: entry.variadic === true,
+    returns
+  };
+}
+function parseResourceAbi(text) {
+  if (text.length > MAX_ABI_BYTES) {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return null;
+  }
+  const document = parsed;
+  const resource = readString2(document.resource, 64);
+  const entries3 = Array.isArray(document.exports) ? document.exports : null;
+  if (document.abi !== ABI_VERSION || resource === null || !RESOURCE_PATTERN.test(resource) || entries3 === null || entries3.length > MAX_EXPORTS) {
+    return null;
+  }
+  const read = entries3.map(readExport);
+  if (read.some((entry) => entry === null)) {
+    return null;
+  }
+  return { abi: ABI_VERSION, resource, exports: read };
+}
+function abiFileName(resource) {
+  return `${resource}${ABI_EXTENSION}`;
+}
+function lookupAbiExport(contracts, resource, name) {
+  return contracts.find((entry) => entry.resource === resource)?.exports.find((entry) => entry.name === name) ?? null;
+}
+function knowsResource(contracts, resource) {
+  return contracts.some((entry) => entry.resource === resource);
+}
+function buildResourceAbi(resource, contributions) {
+  const exports = contributions.map((contribution) => {
+    const signature = contribution.signature;
+    return {
+      name: contribution.name,
+      side: contribution.side,
+      http: contribution.http,
+      parameters: signature?.parameters ?? [],
+      minimumArguments: signature?.minimumArguments ?? 0,
+      variadic: signature?.variadic ?? true,
+      returns: signature?.returns ?? "any"
+    };
+  });
+  return { abi: ABI_VERSION, resource, exports };
+}
+
+// src/build/contract-files.ts
+function contractPath(root, config, resource) {
+  return resolve4(root, config.contracts, abiFileName(resource));
+}
+function readDependencyContracts(root, config) {
+  const contracts = [];
+  const diagnostics = [];
+  for (const dependency of config.dependencies) {
+    const path = contractPath(root, config, dependency);
+    let text;
+    try {
+      text = readFileSync3(path, "utf8");
+    } catch {
+      continue;
+    }
+    const parsed = parseResourceAbi(text);
+    if (parsed === null) {
+      diagnostics.push(cliWarning("build-invalid-contract", `The export contract for "${dependency}" at "${path}" could not be read and was ignored.`));
+      continue;
+    }
+    if (parsed.resource !== dependency) {
+      diagnostics.push(cliWarning("build-invalid-contract", `The export contract at "${path}" names resource "${parsed.resource}" and was ignored.`));
+      continue;
+    }
+    contracts.push(parsed);
+  }
+  return { contracts, diagnostics };
+}
+function writeResourceContract(root, config, contract) {
+  const path = contractPath(root, config, config.name);
+  mkdirSync2(dirname2(path), { recursive: true });
+  writeFileSync3(path, serializeAbi(contract), "utf8");
+  return path;
+}
+
 // src/build/helper-files.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
+import { existsSync as existsSync3, readFileSync as readFileSync4 } from "node:fs";
 import { fileURLToPath } from "node:url";
 function bundledHelperPath(file) {
   return fileURLToPath(new URL(`./lua/${file}`, import.meta.url));
@@ -7167,7 +7473,7 @@ function resolveHelperPath(helper, file) {
   return existsSync3(packaged) ? packaged : bundledHelperPath(file);
 }
 function readHelperSource(helper, file) {
-  return readFileSync3(resolveHelperPath(helper, file), "utf8");
+  return readFileSync4(resolveHelperPath(helper, file), "utf8");
 }
 
 // src/build/build-phase.ts
@@ -7236,16 +7542,16 @@ function createPhaseTracker(listener = null) {
 }
 
 // src/build/project-inputs.ts
-import { existsSync as existsSync4, readFileSync as readFileSync4 } from "node:fs";
-import { resolve as resolve6 } from "node:path";
+import { existsSync as existsSync4, readFileSync as readFileSync5 } from "node:fs";
+import { resolve as resolve7 } from "node:path";
 
 // src/build/asset-resolution.ts
 import { statSync as statSync3 } from "node:fs";
-import { resolve as resolve5 } from "node:path";
+import { resolve as resolve6 } from "node:path";
 
 // src/build/project-files.ts
 import { readdirSync, statSync as statSync2 } from "node:fs";
-import { join as join3, relative, resolve as resolve4 } from "node:path";
+import { join as join3, relative, resolve as resolve5 } from "node:path";
 function isDirectory(path) {
   try {
     return statSync2(path).isDirectory();
@@ -7257,14 +7563,14 @@ function relativePath(root, absolute) {
   return normalizePattern(relative(root, absolute));
 }
 function walk(root, directory, excluded, tree) {
-  let entries2;
+  let entries3;
   try {
-    entries2 = readdirSync(directory, { withFileTypes: true });
+    entries3 = readdirSync(directory, { withFileTypes: true });
   } catch (error) {
     tree.errors.push(`"${relativePath(root, directory)}" could not be read: ${error instanceof Error ? error.message : String(error)}`);
     return;
   }
-  for (const entry of entries2) {
+  for (const entry of entries3) {
     const absolute = join3(directory, entry.name);
     const path = relativePath(root, absolute);
     if (path.length === 0 || isExcludedPath(path, excluded)) {
@@ -7281,7 +7587,7 @@ function listProjectFiles(root, roots, excluded = []) {
   const tree = { files: [], errors: [] };
   const seen = /* @__PURE__ */ new Set();
   for (const start of [...new Set(roots)].sort()) {
-    const absolute = resolve4(root, start);
+    const absolute = resolve5(root, start);
     if (!isDirectory(absolute) || seen.has(absolute)) {
       continue;
     }
@@ -7425,9 +7731,23 @@ var OCCUPIED_SIDES = {
 function occupiedSides(contribution) {
   return OCCUPIED_SIDES[contribution.side];
 }
-function toContributions(directives, environment) {
+function exportSignature(type) {
+  if (type === void 0 || type.kind !== "function") {
+    return null;
+  }
+  const parameters = type.parameters.map((parameter, index) => ({ name: type.parameterNames?.[index] ?? `arg${index + 1}`, type: typeToString(parameter) }));
+  return { parameters, minimumArguments: type.minimumArguments, variadic: type.isVariadic, returns: typeToString(type.returnType) };
+}
+function toContributions(directives, environment, globals) {
   return directives.exports.map(
-    (entry) => ({ kind: "export", name: entry.name, http: entry.http, side: environment, position: entry.position })
+    (entry) => ({
+      kind: "export",
+      name: entry.name,
+      http: entry.http,
+      side: environment,
+      signature: exportSignature(globals.get(entry.name)),
+      position: entry.position
+    })
   );
 }
 var INDENT = "    ";
@@ -7461,8 +7781,8 @@ function attribute(name, value) {
 function textElement(name, value) {
   return `${INDENT}<${name}>${escapeXml(value)}</${name}>`;
 }
-function section(text, entries2) {
-  return entries2.length === 0 ? [] : [`${INDENT}<!-- ${text} -->`, ...entries2];
+function section(text, entries3) {
+  return entries3.length === 0 ? [] : [`${INDENT}<!-- ${text} -->`, ...entries3];
 }
 function infoElement(info) {
   const attributes = info.author === void 0 ? [] : [attribute("author", info.author)];
@@ -7590,12 +7910,12 @@ var MISSING_LOAD_ORDER = 'is listed in "loadOrder" but no source file or asset m
 function missingEntry(entry) {
   return { path: entry, diagnostic: createDiagnostic("project", "project-load-order-missing", `"${entry}" ${MISSING_LOAD_ORDER}`, FILE_START) };
 }
-function resolveLoadOrder(entries2, scripts, assets) {
+function resolveLoadOrder(entries3, scripts, assets) {
   const byScript = new Map(scripts.map((script) => [normalizePath(script.source), script]));
   const byAsset = new Map(assets.map((asset) => [normalizePath(asset.source), asset]));
   const resolved2 = { scripts: [], assets: [], diagnostics: [] };
   const seen = /* @__PURE__ */ new Set();
-  for (const entry of entries2) {
+  for (const entry of entries3) {
     const path = normalizePath(entry).replace(/^\.\//, "");
     const script = byScript.get(path);
     const asset = byAsset.get(path);
@@ -7671,11 +7991,11 @@ var ENTRY = /^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/;
 var SENSITIVE = /(password|secret|token|key|credential|dsn|private)/i;
 var EMPTY_ENV_FILE = { entries: [], errors: [] };
 function unquote(raw) {
-  const quote2 = raw.slice(0, 1);
-  if (quote2 !== '"' && quote2 !== "'") {
+  const quote3 = raw.slice(0, 1);
+  if (quote3 !== '"' && quote3 !== "'") {
     return null;
   }
-  const closing = raw.lastIndexOf(quote2);
+  const closing = raw.lastIndexOf(quote3);
   return closing > 0 ? raw.slice(1, closing) : null;
 }
 function stripComment(raw) {
@@ -7693,7 +8013,7 @@ function classify(raw) {
   return { value, kind: value.length > 0 && Number.isFinite(Number(value)) ? "number" : "string" };
 }
 function parseEnvFile(source) {
-  const entries2 = [];
+  const entries3 = [];
   const errors = [];
   source.split(/\r?\n/).forEach((raw, index) => {
     const trimmed = raw.trim();
@@ -7707,9 +8027,9 @@ function parseEnvFile(source) {
       return;
     }
     const { value, kind } = classify(match[2]);
-    entries2.push({ key: match[1], value, kind, line: line2 });
+    entries3.push({ key: match[1], value, kind, line: line2 });
   });
-  return { entries: entries2, errors };
+  return { entries: entries3, errors };
 }
 function isSensitiveKey(key) {
   return SENSITIVE.test(key);
@@ -7875,14 +8195,14 @@ var MANIFEST_OUTPUT = "meta.xml";
 var HERE = ".";
 function isDirectory2(root, path) {
   try {
-    return statSync3(resolve5(root, path)).isDirectory();
+    return statSync3(resolve6(root, path)).isDirectory();
   } catch {
     return false;
   }
 }
 function exists(root, path) {
   try {
-    statSync3(resolve5(root, path));
+    statSync3(resolve6(root, path));
     return true;
   } catch {
     return false;
@@ -7950,10 +8270,10 @@ var CONFIGURATION_FILE = "config.lua";
 var MALFORMED_ENV = "build-env-malformed";
 var MISSING_ENV = "config-missing-env-file";
 function readTextFile(path) {
-  return existsSync4(path) ? readFileSync4(path, "utf8") : null;
+  return existsSync4(path) ? readFileSync5(path, "utf8") : null;
 }
 function readEnvironment(root, file, required, diagnostics) {
-  const source = readTextFile(resolve6(root, file));
+  const source = readTextFile(resolve7(root, file));
   if (source === null) {
     if (required) {
       diagnostics.push(cliError(MISSING_ENV, `"${file}" is configured under "environment" but does not exist. Create it or remove the setting.`));
@@ -7967,7 +8287,7 @@ function readEnvironment(root, file, required, diagnostics) {
   return parsed;
 }
 function readConfiguration(root, diagnostics) {
-  const content = readTextFile(resolve6(root, CONFIGURATION_FILE));
+  const content = readTextFile(resolve7(root, CONFIGURATION_FILE));
   if (content === null) {
     return null;
   }
@@ -7986,14 +8306,14 @@ function readProjectInputs(root, options) {
 }
 
 // src/build/source-discovery.ts
-import { readFileSync as readFileSync5 } from "node:fs";
-import { resolve as resolve7 } from "node:path";
+import { readFileSync as readFileSync6 } from "node:fs";
+import { resolve as resolve8 } from "node:path";
 
 // ../compiler/src/project/source-mapping.ts
 function createSourceResolver(mapping) {
   const matchers = new Map(SOURCE_SIDES.map((environment) => [environment, createPatternMatcher(mapping[environment])]));
   const patterns = SOURCE_SIDES.flatMap((environment) => [...matchers.get(environment)?.patterns ?? []]);
-  function resolve17(path) {
+  function resolve21(path) {
     const normalized = normalizePattern(path);
     const matches = [];
     for (const environment of SOURCE_SIDES) {
@@ -8007,8 +8327,8 @@ function createSourceResolver(mapping) {
   return {
     patterns,
     roots: watchRoots(patterns),
-    resolve: resolve17,
-    side: (path) => resolve17(path).environment
+    resolve: resolve21,
+    side: (path) => resolve21(path).environment
   };
 }
 function describeMatches(matches) {
@@ -8018,17 +8338,28 @@ function describeMatches(matches) {
 // ../compiler/src/project/source-kind.ts
 var SOURCE_EXTENSION = ".luam";
 var DECLARATION_EXTENSION = ".d.luam";
+var TEST_EXTENSION = ".test.luam";
 function isDeclarationPath(path) {
   return normalizePath(path).endsWith(DECLARATION_EXTENSION);
 }
+function isTestPath(path) {
+  return normalizePath(path).endsWith(TEST_EXTENSION);
+}
 
 // src/build/source-discovery.ts
 var MISSING_SOURCE = "config-missing-source";
 var NO_SOURCES = "config-no-sources";
 var SIDE_CONFLICT = "config-source-side-conflict";
+var TEST_SOURCE = "config-test-source";
 var UNREADABLE_SOURCE = "build-source-unreadable";
 function checkLiterals(root, resolver, found, diagnostics) {
   for (const pattern of resolver.patterns.filter(isLiteralPattern)) {
+    if (isTestPath(pattern)) {
+      diagnostics.push(
+        cliError(TEST_SOURCE, `"${pattern}" is listed in "sources" but "${TEST_EXTENSION}" files are run by "luam test" and never built into the resource.`)
+      );
+      continue;
+    }
     if (!pattern.endsWith(SOURCE_EXTENSION)) {
       diagnostics.push(cliError(MISSING_SOURCE, `"${pattern}" is listed in "sources" but does not end in "${SOURCE_EXTENSION}".`));
       continue;
@@ -8040,7 +8371,7 @@ function checkLiterals(root, resolver, found, diagnostics) {
 }
 function readSource(root, path, diagnostics) {
   try {
-    return readFileSync5(resolve7(root, path), "utf8");
+    return readFileSync6(resolve8(root, path), "utf8");
   } catch (error) {
     diagnostics.push(cliError(UNREADABLE_SOURCE, `The source file "${path}" could not be read: ${error instanceof Error ? error.message : String(error)}`));
     return null;
@@ -8052,7 +8383,7 @@ function discoverSources(root, sources, excluded = []) {
   const diagnostics = tree.errors.map((message) => cliError(UNREADABLE_SOURCE, message));
   const files = [];
   const matched = /* @__PURE__ */ new Set();
-  for (const path of tree.files.filter((entry) => entry.endsWith(SOURCE_EXTENSION))) {
+  for (const path of tree.files.filter((entry) => entry.endsWith(SOURCE_EXTENSION) && !isTestPath(entry))) {
     const resolution = resolver.resolve(path);
     if (resolution.matches.length === 0) {
       continue;
@@ -8120,25 +8451,57 @@ function fn(parameters, returnType, minimumArguments2, isVariadic = false, param
 var EMPTY_PROJECT_DECLARATIONS = { globals: [] };
 var ENV_GLOBAL = "env";
 var VALUE_TYPES = { boolean: BOOLEAN, number: NUMBER, string: STRING };
-function envMembers(entries2) {
+function envMembers(entries3) {
   const members = /* @__PURE__ */ new Map();
-  for (const entry of entries2) {
+  for (const entry of entries3) {
     members.set(entry.key, { name: entry.key, type: VALUE_TYPES[entry.kind] });
   }
   return [...members.values()].sort((left, right) => left.name.localeCompare(right.name));
 }
-function envDeclaration(entries2, origin) {
-  const env = record(ENV_GLOBAL, envMembers(entries2), origin);
+function envDeclaration(entries3, origin) {
+  const env = record(ENV_GLOBAL, envMembers(entries3), origin);
   return { name: ENV_GLOBAL, environment: "server", source: "project", type: env };
 }
-function projectDeclarations(entries2, origin) {
-  if (entries2 === null) {
+function projectDeclarations(entries3, origin) {
+  if (entries3 === null) {
     return EMPTY_PROJECT_DECLARATIONS;
   }
-  return { globals: [envDeclaration(entries2, origin)] };
-}
+  return { globals: [envDeclaration(entries3, origin)] };
+}
+
+// ../compiler/src/checker/test-declarations.ts
+var TEST_ORIGIN = "luam:test";
+var CALLBACK = fn([], VOID);
+var EXPECTATION_MEMBERS = [
+  { name: "toBe", type: fn([ANY], VOID, 1, false, ["expected"]) },
+  { name: "toBeFalsy", type: fn([], VOID) },
+  { name: "toBeNil", type: fn([], VOID) },
+  { name: "toBeTruthy", type: fn([], VOID) },
+  { name: "toContain", type: fn([ANY], VOID, 1, false, ["value"]) },
+  { name: "toEqual", type: fn([ANY], VOID, 1, false, ["expected"]) },
+  { name: "toNotBe", type: fn([ANY], VOID, 1, false, ["expected"]) },
+  { name: "toNotEqual", type: fn([ANY], VOID, 1, false, ["expected"]) },
+  { name: "toThrow", type: fn([optionalOf(STRING)], VOID, 0, false, ["message"]) }
+];
+var STUB_MEMBERS = [
+  { name: "calls", type: fn([STRING], arrayOf(TABLE), 1, false, ["name"]) },
+  { name: "reset", type: fn([], VOID) },
+  { name: "returns", type: fn([STRING, ANY], VOID, 2, false, ["name", "value"]) },
+  { name: "stub", type: fn([STRING, ANY], VOID, 2, false, ["name", "implementation"]) }
+];
+var EXPECTATION_TYPE = record("Expectation", EXPECTATION_MEMBERS, TEST_ORIGIN);
+var MTA_STUBS_TYPE = record("MtaStubs", STUB_MEMBERS, TEST_ORIGIN);
+var TEST_DECLARATIONS = [
+  { name: "afterEach", environment: "shared", source: "extension", type: fn([CALLBACK], VOID, 1, false, ["body"]) },
+  { name: "beforeEach", environment: "shared", source: "extension", type: fn([CALLBACK], VOID, 1, false, ["body"]) },
+  { name: "describe", environment: "shared", source: "extension", type: fn([STRING, CALLBACK], VOID, 2, false, ["name", "body"]) },
+  { name: "expect", environment: "shared", source: "extension", type: fn([ANY], EXPECTATION_TYPE, 1, false, ["value"]) },
+  { name: "mta", environment: "shared", source: "extension", type: MTA_STUBS_TYPE },
+  { name: "test", environment: "shared", source: "extension", type: fn([STRING, CALLBACK], VOID, 2, false, ["name", "body"]) }
+];
 
 // ../compiler/src/checker/ambient.ts
+var EVENT_NAME_PREFIX = "event:";
 var EMPTY_AMBIENT = { classes: [], interfaces: [], enums: [], globals: [], events: [] };
 function ambientFromRegistry(registry) {
   return {
@@ -8149,9 +8512,9 @@ function ambientFromRegistry(registry) {
     events: registry.allEvents()
   };
 }
-function withoutNames(entries2, excluded) {
+function withoutNames(entries3, excluded) {
   const names = new Set(excluded.map((entry) => entry.name));
-  return entries2.filter((entry) => !names.has(entry.name));
+  return entries3.filter((entry) => !names.has(entry.name));
 }
 function ownDeclarations(registry, ambient) {
   const all = ambientFromRegistry(registry);
@@ -8328,6 +8691,9 @@ var Binder = class {
   declaredSymbols() {
     return [...this.discarded, ...this.scopes.flatMap((scope) => [...scope.values()])];
   }
+  currentScopeNames() {
+    return [...this.scopes[this.scopes.length - 1]?.keys() ?? []];
+  }
   declare(symbol) {
     const scope = this.scopes[this.scopes.length - 1];
     scope?.set(symbol.name, symbol);
@@ -8366,6 +8732,211 @@ var Binder = class {
   }
 };
 
+// ../compiler/src/checker/flow.ts
+function createFlow() {
+  return { facts: /* @__PURE__ */ new Map(), reachable: true };
+}
+function cloneFlow(state) {
+  return { facts: new Map(state.facts), reachable: state.reachable };
+}
+function applyFacts(state, facts) {
+  for (const [path, type] of facts) {
+    state.facts.set(path, type);
+  }
+}
+function forgetPath(state, path) {
+  for (const key of [...state.facts.keys()]) {
+    if (key === path || key.startsWith(`${path}.`) || path.startsWith(`${key}.`)) {
+      state.facts.delete(key);
+    }
+  }
+}
+function joinFlows(states) {
+  const live = states.filter((state) => state.reachable);
+  const [first, ...rest] = live;
+  if (first === void 0) {
+    return { facts: /* @__PURE__ */ new Map(), reachable: false };
+  }
+  const facts = /* @__PURE__ */ new Map();
+  for (const [path, type] of first.facts) {
+    const others = rest.map((state) => state.facts.get(path));
+    if (others.some((other) => other === void 0)) {
+      continue;
+    }
+    facts.set(path, createUnion([type, ...others]));
+  }
+  return { facts, reachable: true };
+}
+function optionsOf(declared) {
+  if (declared.kind === "union") {
+    return declared.options;
+  }
+  return declared.kind === "optional" ? [declared.element, NIL_TYPE] : [];
+}
+function assignmentFact(narrowed, declared) {
+  const matched = optionsOf(declared).filter((option) => isAssignable(narrowed, option));
+  const [only] = matched;
+  return matched.length === 1 && only !== void 0 ? only : null;
+}
+
+// ../compiler/src/checker/type-substitution.ts
+function substituteType(type, substitutions) {
+  if (type.kind === "named") {
+    const args = type.typeArguments ?? [];
+    if (args.length > 0) {
+      return createNamed(type.name, args.map((argument) => substituteType(argument, substitutions)));
+    }
+    return substitutions.get(type.name) ?? type;
+  }
+  if (type.kind === "array") {
+    return createArray(substituteType(type.element, substitutions));
+  }
+  if (type.kind === "map") {
+    return createMap(substituteType(type.key, substitutions), substituteType(type.value, substitutions));
+  }
+  if (type.kind === "optional") {
+    return createOptional(substituteType(type.element, substitutions));
+  }
+  if (type.kind === "union") {
+    return createUnion(type.options.map((option) => substituteType(option, substitutions)));
+  }
+  if (type.kind === "function") {
+    const parameters = type.parameters.map((parameter) => substituteType(parameter, substitutions));
+    const returnType = substituteType(type.returnType, substitutions);
+    const variadicType = type.variadicType === void 0 ? void 0 : substituteType(type.variadicType, substitutions);
+    return createFunction(parameters, returnType, type.minimumArguments, type.isVariadic, type.parameterNames, variadicType);
+  }
+  if (type.kind === "tuple") {
+    return createTuple(type.elements.map((element) => substituteType(element, substitutions)));
+  }
+  if (type.kind === "record") {
+    const members = new Map([...type.members].map(([name, member]) => [name, substituteType(member, substitutions)]));
+    return createRecord(type.name, members, type.origin);
+  }
+  return type;
+}
+
+// ../compiler/src/checker/generic-class.ts
+var MAX_DEPTH = 32;
+function classSubstitutions(info, typeArguments) {
+  return new Map(info.typeParameters.map((parameter, index) => [parameter, typeArguments[index] ?? ANY_TYPE]));
+}
+function parentSubstitutions(registry, info, current) {
+  const parent = info.superClass === null ? null : registry.lookupClass(info.superClass);
+  if (parent === null) {
+    return null;
+  }
+  return classSubstitutions(parent, info.superArguments.map((argument) => substituteType(argument, current)));
+}
+function substitutionsFor(registry, receiver, owner) {
+  const info = registry.lookupClass(receiver.name);
+  if (info === null) {
+    return /* @__PURE__ */ new Map();
+  }
+  let current = info;
+  let substitutions = classSubstitutions(info, receiver.typeArguments ?? []);
+  for (let depth = 0; current !== null && depth < MAX_DEPTH; depth += 1) {
+    if (current.name === owner) {
+      return substitutions;
+    }
+    const next = parentSubstitutions(registry, current, substitutions);
+    if (next === null) {
+      return /* @__PURE__ */ new Map();
+    }
+    substitutions = next;
+    current = current.superClass === null ? null : registry.lookupClass(current.superClass);
+  }
+  return /* @__PURE__ */ new Map();
+}
+function specializeMember(context, receiver, member, property) {
+  const owner = context.declarations.lookupMemberOwner(receiver.name, property);
+  if (owner === null || owner === receiver.name) {
+    const own = context.declarations.lookupClass(receiver.name);
+    if (own === null || own.typeParameters.length === 0 || (receiver.typeArguments ?? []).length === 0) {
+      return member;
+    }
+    return { ...member, type: substituteType(member.type, classSubstitutions(own, receiver.typeArguments ?? [])) };
+  }
+  return { ...member, type: substituteType(member.type, substitutionsFor(context.declarations, receiver, owner)) };
+}
+function memberOf(context, receiver, property) {
+  const member = context.declarations.lookupMember(receiver.name, property);
+  return member === null ? null : specializeMember(context, receiver, member, property);
+}
+function unify(parameter, argument, names, bindings) {
+  if (parameter.kind === "named" && names.has(parameter.name)) {
+    if (!bindings.has(parameter.name) && argument.kind !== "nil") {
+      bindings.set(parameter.name, argument);
+    }
+    return;
+  }
+  if (parameter.kind === "array" && argument.kind === "array") {
+    unify(parameter.element, argument.element, names, bindings);
+    return;
+  }
+  if (parameter.kind === "optional") {
+    unify(parameter.element, argument.kind === "optional" ? argument.element : argument, names, bindings);
+    return;
+  }
+  if (parameter.kind === "map" && argument.kind === "map") {
+    unify(parameter.key, argument.key, names, bindings);
+    unify(parameter.value, argument.value, names, bindings);
+    return;
+  }
+  if (parameter.kind === "named" && argument.kind === "named" && parameter.name === argument.name) {
+    const parameterArguments = parameter.typeArguments ?? [];
+    const argumentArguments = argument.typeArguments ?? [];
+    parameterArguments.forEach((entry, index) => unify(entry, argumentArguments[index] ?? ANY_TYPE, names, bindings));
+    return;
+  }
+  if (parameter.kind === "function" && argument.kind === "function") {
+    parameter.parameters.forEach((entry, index) => unify(entry, argument.parameters[index] ?? ANY_TYPE, names, bindings));
+    unify(parameter.returnType, argument.returnType, names, bindings);
+  }
+}
+function inferTypeArguments(typeParameters, parameters, args) {
+  const names = new Set(typeParameters);
+  const bindings = /* @__PURE__ */ new Map();
+  parameters.forEach((parameter, index) => {
+    const argument = args[index];
+    if (argument !== void 0) {
+      unify(parameter, widenInferred(argument), names, bindings);
+    }
+  });
+  return typeParameters.map((parameter) => bindings.get(parameter) ?? ANY_TYPE);
+}
+function inheritsFrom(context, name, target) {
+  let current = context.declarations.lookupClass(name);
+  for (let depth = 0; current !== null && depth < MAX_DEPTH; depth += 1) {
+    if (current.name === target || current.interfaces.includes(target)) {
+      return true;
+    }
+    current = current.superClass === null ? null : context.declarations.lookupClass(current.superClass);
+  }
+  return context.declarations.interfaceExtends(name, target);
+}
+function satisfies(context, argument, constraint) {
+  if (argument.kind === "named" && constraint.kind === "named") {
+    return argument.name === constraint.name || inheritsFrom(context, argument.name, constraint.name);
+  }
+  return isAssignable(argument, constraint, { allowNil: false });
+}
+function checkTypeConstraints(context, name, typeArguments, position2) {
+  const info = context.declarations.lookupClass(name);
+  if (info === null) {
+    return;
+  }
+  info.typeConstraints.forEach((constraint, index) => {
+    const argument = typeArguments[index];
+    if (constraint === null || argument === void 0 || argument.kind === "any" || satisfies(context, argument, constraint)) {
+      return;
+    }
+    const parameter = info.typeParameters[index] ?? "T";
+    const message = `Type argument "${typeToString(argument)}" does not satisfy "${parameter} extends ${typeToString(constraint)}" on class "${name}".`;
+    context.report("check-generic-constraint", message, position2);
+  });
+}
+
 // ../mta-types/src/lua-standard.ts
 var LUA_GLOBALS = {
   _G: TABLE,
@@ -13203,6 +13774,18 @@ var DeclarationRegistry = class {
     }
     return null;
   }
+  lookupMemberOwner(name, member) {
+    const visited = /* @__PURE__ */ new Set();
+    let current = this.lookupClass(name);
+    while (current !== null && !visited.has(current.name)) {
+      if (current.members.has(member)) {
+        return current.name;
+      }
+      visited.add(current.name);
+      current = current.superClass === null ? null : this.lookupClass(current.superClass);
+    }
+    return null;
+  }
   lookupStaticMember(name, member) {
     const visited = /* @__PURE__ */ new Set();
     let current = this.lookupClass(name);
@@ -13262,7 +13845,17 @@ function buildRegistry() {
         procedural: member.procedural
       });
     }
-    registry.declareClass({ name: declaration.name, superClass: declaration.parent, interfaces: [], members, statics: /* @__PURE__ */ new Map(), position: MTA_POSITION });
+    registry.declareClass({
+      name: declaration.name,
+      typeParameters: [],
+      typeConstraints: [],
+      superClass: declaration.parent,
+      superArguments: [],
+      interfaces: [],
+      members,
+      statics: /* @__PURE__ */ new Map(),
+      position: MTA_POSITION
+    });
   }
   return registry;
 }
@@ -13349,12 +13942,22 @@ function missingKeys(source, target) {
   }
   return missing2;
 }
-function missingKeyHint(source, target) {
+function expandCandidate(option, resolveNominal) {
+  if (option.kind === "record") {
+    return option;
+  }
+  if (option.kind !== "named") {
+    return null;
+  }
+  const shape = resolveNominal?.(option.name) ?? null;
+  return shape === null || shape.kind !== "interface" ? null : { kind: "record", name: option.name, origin: null, members: shape.members };
+}
+function missingKeyHint(source, target, resolveNominal) {
   if (source.kind !== "record" || source.isLiteral !== true) {
     return "";
   }
   const options = target.kind === "union" ? target.options : [target];
-  const candidates3 = options.filter((option) => option.kind === "record");
+  const candidates3 = options.map((option) => expandCandidate(option, resolveNominal)).filter((option) => option !== null);
   const candidate = chooseCandidate(source, candidates3);
   if (candidate === null) {
     return "";
@@ -13402,39 +14005,6 @@ function mergeIntersection(context, parts, position2) {
   return createObjectType(members);
 }
 
-// ../compiler/src/checker/type-substitution.ts
-function substituteType(type, substitutions) {
-  if (type.kind === "named") {
-    return substitutions.get(type.name) ?? type;
-  }
-  if (type.kind === "array") {
-    return createArray(substituteType(type.element, substitutions));
-  }
-  if (type.kind === "map") {
-    return createMap(substituteType(type.key, substitutions), substituteType(type.value, substitutions));
-  }
-  if (type.kind === "optional") {
-    return createOptional(substituteType(type.element, substitutions));
-  }
-  if (type.kind === "union") {
-    return createUnion(type.options.map((option) => substituteType(option, substitutions)));
-  }
-  if (type.kind === "function") {
-    const parameters = type.parameters.map((parameter) => substituteType(parameter, substitutions));
-    const returnType = substituteType(type.returnType, substitutions);
-    const variadicType = type.variadicType === void 0 ? void 0 : substituteType(type.variadicType, substitutions);
-    return createFunction(parameters, returnType, type.minimumArguments, type.isVariadic, type.parameterNames, variadicType);
-  }
-  if (type.kind === "tuple") {
-    return createTuple(type.elements.map((element) => substituteType(element, substitutions)));
-  }
-  if (type.kind === "record") {
-    const members = new Map([...type.members].map(([name, member]) => [name, substituteType(member, substitutions)]));
-    return createRecord(type.name, members, type.origin);
-  }
-  return type;
-}
-
 // ../compiler/src/checker/context.ts
 var BUILTIN_TYPES = {
   any: ANY_TYPE,
@@ -13450,6 +14020,7 @@ var BUILTIN_TYPES = {
 };
 var TABLE_ANNOTATION = "table";
 var MAP_ARGUMENTS = 2;
+var MAX_GENERIC_DEPTH = 8;
 var PROJECT_POSITION = { line: 0, column: 0, offset: 0 };
 function nilHint(source, target, mode) {
   if (mode !== "strict" || source.kind !== "nil" || target.kind === "nil" || target.kind === "optional") {
@@ -13462,12 +14033,15 @@ var CheckContext = class {
   declarations = new DeclarationRegistry();
   diagnostics = [];
   reported = /* @__PURE__ */ new Set();
-  narrowings = [];
+  flow = createFlow();
   types = /* @__PURE__ */ new Map();
   references = /* @__PURE__ */ new Set();
   declaredGlobals = /* @__PURE__ */ new Map();
+  moduleGlobals = /* @__PURE__ */ new Map();
   externalReferences = /* @__PURE__ */ new Map();
   unknownTypes = /* @__PURE__ */ new Map();
+  eventReferences = /* @__PURE__ */ new Set();
+  globalReferences = /* @__PURE__ */ new Set();
   calledMembers = /* @__PURE__ */ new Set();
   staticAccess = /* @__PURE__ */ new Set();
   typeParameters = /* @__PURE__ */ new Set();
@@ -13475,6 +14049,7 @@ var CheckContext = class {
   mode;
   environment;
   mtaClasses;
+  contracts = [];
   isDeclarationFile = false;
   returnStack = [];
   methodStack = [];
@@ -13500,33 +14075,28 @@ var CheckContext = class {
   declareModuleGlobal(symbol) {
     this.binder.declareGlobal(symbol);
     this.declaredGlobals.set(symbol.name, symbol.position);
+    this.moduleGlobals.set(symbol.name, symbol.type);
   }
-  pushNarrowing(facts) {
-    this.narrowings.push(new Map(facts));
+  get flowState() {
+    return this.flow;
   }
-  get isNarrowed() {
-    return this.narrowings.length > 0;
+  setFlow(state) {
+    this.flow = state;
+  }
+  applyFlowFacts(facts) {
+    applyFacts(this.flow, facts);
+  }
+  markUnreachable() {
+    this.flow.reachable = false;
   }
-  popNarrowing() {
-    this.narrowings.pop();
+  get isNarrowed() {
+    return this.flow.facts.size > 0;
   }
   forgetNarrowing(path) {
-    for (const frame of this.narrowings) {
-      for (const key of [...frame.keys()]) {
-        if (key === path || key.startsWith(`${path}.`) || path.startsWith(`${key}.`)) {
-          frame.delete(key);
-        }
-      }
-    }
+    forgetPath(this.flow, path);
   }
   narrowedType(path) {
-    for (let index = this.narrowings.length - 1; index >= 0; index -= 1) {
-      const found = this.narrowings[index]?.get(path);
-      if (found !== void 0) {
-        return found;
-      }
-    }
-    return null;
+    return this.flow.facts.get(path) ?? null;
   }
   predeclareClass(info) {
     this.predeclared.set(info.name, info);
@@ -13593,6 +14163,12 @@ var CheckContext = class {
   isTypeParameter(name) {
     return this.typeParameters.has(name);
   }
+  noteGlobalReference(name) {
+    this.globalReferences.add(name);
+  }
+  noteEventReference(name) {
+    this.eventReferences.add(name);
+  }
   noteUnknownType(name, position2) {
     if (!this.unknownTypes.has(name)) {
       this.unknownTypes.set(name, position2);
@@ -13682,17 +14258,57 @@ var CheckContext = class {
       const parameters = annotation.parameters.map((parameter) => this.resolveAnnotation(parameter));
       const optional = parameters.findIndex((parameter) => parameter.kind === "optional");
       const minimum = optional === -1 ? parameters.length : optional;
-      return createFunction(parameters, this.resolveAnnotation(annotation.returnType), minimum, annotation.isVariadic);
+      return createFunction(parameters, this.resolveAnnotation(annotation.returnType), minimum, annotation.isVariadic, [...annotation.parameterNames]);
     }
     return this.resolveNamedAnnotation(annotation.name, annotation.typeArguments, annotation.position);
   }
+  nominalShape(name) {
+    const declaredInterface = this.declarations.lookupInterface(name);
+    if (declaredInterface !== null) {
+      const ancestors = this.declarations.allInterfaces().filter((other) => this.declarations.interfaceExtends(name, other.name));
+      return {
+        kind: "interface",
+        members: new Map(this.declarations.collectInterfaceContract(name).map((member) => [member.name, member.type])),
+        ancestors: new Set(ancestors.map((other) => other.name))
+      };
+    }
+    const declaredClass = this.declarations.lookupClass(name);
+    if (declaredClass === null) {
+      return null;
+    }
+    return {
+      kind: "class",
+      members: new Map(this.declarations.collectMembers(name).map((member) => [member.name, member.type])),
+      ancestors: this.classAncestors(name)
+    };
+  }
+  classAncestors(name) {
+    const ancestors = /* @__PURE__ */ new Set();
+    let current = this.declarations.lookupClass(name);
+    while (current !== null && !ancestors.has(current.name)) {
+      ancestors.add(current.name);
+      for (const contract of current.interfaces) {
+        ancestors.add(contract);
+        for (const other of this.declarations.allInterfaces()) {
+          if (this.declarations.interfaceExtends(contract, other.name)) {
+            ancestors.add(other.name);
+          }
+        }
+      }
+      current = current.superClass === null ? null : this.declarations.lookupClass(current.superClass);
+    }
+    return ancestors;
+  }
+  assignability() {
+    return { allowNil: this.allowNil, resolveNominal: (name) => this.nominalShape(name) };
+  }
   expectAssignable(source, target, position2, subject) {
-    if (isAssignable(source, target, { allowNil: this.allowNil })) {
+    if (isAssignable(source, target, this.assignability())) {
       return;
     }
     const received = isLiteralType(target) || target.kind === "union" ? source : widenLiteral(source);
     const message = `${subject} expects "${typeToString(target)}" but received "${typeToString(received)}".`;
-    const hint = `${nilHint(source, target, this.mode)}${missingKeyHint(source, target)}`;
+    const hint = `${nilHint(source, target, this.mode)}${missingKeyHint(source, target, (name) => this.nominalShape(name))}`;
     this.report("check-type-mismatch", `${message}${hint}`, position2);
   }
   declareProject(project) {
@@ -13738,6 +14354,25 @@ var CheckContext = class {
     }
     return createMap(this.resolveAnnotation(key), this.resolveAnnotation(value));
   }
+  resolveClassAnnotation(name, typeArguments, position2) {
+    const declared = this.declarations.lookupClass(name)?.typeParameters ?? [];
+    const resolved2 = typeArguments.map((argument) => this.resolveAnnotation(argument));
+    if (declared.length === 0) {
+      return createNamed(name);
+    }
+    if (resolved2.length !== declared.length) {
+      const expected = declared.length === 1 ? "1 type argument" : `${declared.length} type arguments`;
+      this.report("check-generic-arity", `Class "${name}" expects ${expected} but received ${resolved2.length}.`, position2);
+    }
+    const specialized = createNamed(name, declared.map((unused, index) => resolved2[index] ?? ANY_TYPE));
+    if (namedNesting(specialized) > MAX_GENERIC_DEPTH) {
+      const message = `Class "${name}" is nested more than ${MAX_GENERIC_DEPTH} levels deep here. Name the inner type with a "type" alias.`;
+      this.report("check-generic-depth", message, position2);
+      return createNamed(name);
+    }
+    checkTypeConstraints(this, name, specialized.typeArguments ?? [], position2);
+    return specialized;
+  }
   resolveNamedAnnotation(name, typeArguments, position2) {
     const builtin = BUILTIN_TYPES[name];
     if (builtin !== void 0) {
@@ -13752,7 +14387,7 @@ var CheckContext = class {
     const alias = this.binder.lookupAlias(name);
     if (alias === null) {
       this.noteUnknownType(name, position2);
-      return createNamed(name);
+      return this.resolveClassAnnotation(name, typeArguments, position2);
     }
     if (typeArguments.length !== alias.parameters.length) {
       const expected = alias.parameters.length === 1 ? "1 type argument" : `${alias.parameters.length} type arguments`;
@@ -14009,6 +14644,73 @@ function checkOverrides(context, info, statement) {
   }
 }
 
+// ../compiler/src/checker/metamethods.ts
+var CONTRACTS = [
+  { name: "__tostring", parameters: 0, returns: "string", documentation: 'Renders the instance for "tostring" and string coercion.' },
+  { name: "__eq", parameters: 1, returns: "boolean", documentation: 'Compares two instances of the same class with "==".' },
+  { name: "__lt", parameters: 1, returns: "boolean", documentation: 'Orders two instances with "<" and ">".' },
+  { name: "__le", parameters: 1, returns: "boolean", documentation: 'Orders two instances with "<=" and ">=".' },
+  { name: "__len", parameters: 0, returns: "number", documentation: 'Answers the length operator "#".' },
+  { name: "__concat", parameters: 1, returns: "any", documentation: 'Answers the concatenation operator "..".' },
+  { name: "__unm", parameters: 0, returns: "any", documentation: "Answers unary minus." },
+  { name: "__add", parameters: 1, returns: "any", documentation: 'Answers "+".' },
+  { name: "__sub", parameters: 1, returns: "any", documentation: 'Answers "-".' },
+  { name: "__mul", parameters: 1, returns: "any", documentation: 'Answers "*".' },
+  { name: "__div", parameters: 1, returns: "any", documentation: 'Answers "/".' },
+  { name: "__mod", parameters: 1, returns: "any", documentation: 'Answers "%".' },
+  { name: "__pow", parameters: 1, returns: "any", documentation: 'Answers "^".' }
+];
+var BLOCKED = {
+  __index: "it replaces member lookup, which the class helper owns",
+  __newindex: "it swallows a field write, which the class helper owns",
+  __call: "it makes an instance callable, which hides construction",
+  __gc: "Lua 5.1 does not run it for a table",
+  __metatable: "it hides the metatable the class helper needs",
+  __mode: "it turns instances into weak references the class helper cannot track"
+};
+var METAMETHOD_CONTRACTS = new Map(CONTRACTS.map((contract) => [contract.name, contract]));
+function isMetamethodName(name) {
+  return name.startsWith("__");
+}
+function isAllowedMetamethod(name) {
+  return METAMETHOD_CONTRACTS.has(name);
+}
+function isMetamethodMember(member) {
+  return member.kind === "class-method" && !member.isStatic && isAllowedMetamethod(member.name);
+}
+function reportReturn(context, className, contract, type, member) {
+  if (contract.returns === "any" || type.kind === "any" || type.kind === contract.returns) {
+    return;
+  }
+  const message = `Metamethod "${contract.name}" of class "${className}" must return "${contract.returns}" but returns "${typeToString(type)}".`;
+  context.report("check-invalid-metamethod", message, member.position);
+}
+function checkMetamethod(context, className, member, type) {
+  const contract = METAMETHOD_CONTRACTS.get(member.name);
+  if (contract === void 0 || type.kind !== "function") {
+    return;
+  }
+  if (type.parameters.length !== contract.parameters) {
+    const expected = contract.parameters === 1 ? "1 parameter" : `${contract.parameters} parameters`;
+    const message = `Metamethod "${contract.name}" of class "${className}" takes ${expected} beside "self" but declares ${type.parameters.length}.`;
+    context.report("check-invalid-metamethod", message, member.position);
+  }
+  reportReturn(context, className, contract, type.returnType, member);
+}
+function reportRejectedMetamethod(context, className, member) {
+  if (member.kind !== "class-method" || !isMetamethodName(member.name) || isAllowedMetamethod(member.name)) {
+    return;
+  }
+  const blocked = BLOCKED[member.name];
+  if (blocked !== void 0) {
+    context.report("check-blocked-metamethod", `Metamethod "${member.name}" cannot be declared on class "${className}" because ${blocked}.`, member.position);
+    return;
+  }
+  const known = [...METAMETHOD_CONTRACTS.keys()].map((name) => `"${name}"`).join(", ");
+  const message = `"${member.name}" is not a metamethod Luam exposes on class "${className}". Declared metamethods are ${known}.`;
+  context.report("check-blocked-metamethod", message, member.position);
+}
+
 // ../compiler/src/checker/accessor-names.ts
 function capitalize(name) {
   return `${name.charAt(0).toUpperCase()}${name.slice(1)}`;
@@ -14093,6 +14795,25 @@ var KNOWN_DECORATORS = /* @__PURE__ */ new Map([
       diagnostics: [CONFLICT]
     }
   ],
+  [
+    "Validated",
+    {
+      name: "Validated",
+      documentation: "Generates runtime checks for the declared field types.",
+      targets: ["class"],
+      generates: [
+        "`ClassName.validate(value: table): ClassName`, returning the value or raising a Lua error naming the path and the expected type.",
+        "`ClassName.matches(value: table): boolean`, the same check without raising."
+      ],
+      rules: [
+        "Both are static, so they are called on the class and never on an instance.",
+        "The check walks the declared field types with a depth, entry-count and string-length limit, and a failure names the path and the expected type but never the value.",
+        "A field whose type has no runtime shape is `check-unreifiable-type`, reported before anything is emitted.",
+        "It is the only decorator that adds runtime code beyond the class helper; a class without it emits nothing extra."
+      ],
+      diagnostics: [CONFLICT, "`check-unreifiable-type` when a field type cannot be checked at runtime."]
+    }
+  ],
   [
     "Serializable",
     {
@@ -14183,6 +14904,102 @@ var KNOWN_DECORATORS = /* @__PURE__ */ new Map([
   ]
 ]);
 
+// ../compiler/src/checker/validation-descriptor.ts
+var MAX_EXPANSION = 8;
+var PRIMITIVE_KINDS = {
+  nil: "nil",
+  boolean: "boolean",
+  number: "number",
+  string: "string",
+  table: "table",
+  thread: "thread",
+  userdata: "userdata",
+  function: "function"
+};
+function quote2(value) {
+  return `'${value.replace(/([\\'])/g, "\\$1").replace(/\n/g, "\\n")}'`;
+}
+function failed(type) {
+  return { lua: null, unreifiable: typeToString(type) };
+}
+function entries2(parts) {
+  return `{ ${parts.join(", ")} }`;
+}
+function combine(parts, render2) {
+  const broken = parts.find((part) => part.lua === null);
+  if (broken !== void 0) {
+    return broken;
+  }
+  return { lua: render2(parts.map((part) => part.lua)), unreifiable: null };
+}
+function namedDescriptor(context, type, name, seen) {
+  if (context.declarations.lookupClass(name) !== null) {
+    return { lua: entries2([`kind = 'instance'`, `name = ${quote2(name)}`]), unreifiable: null };
+  }
+  if (context.declarations.lookupEnum(name) !== null) {
+    return { lua: entries2([`kind = 'number'`]), unreifiable: null };
+  }
+  if (context.declarations.lookupInterface(name) === null || seen.has(name) || seen.size >= MAX_EXPANSION) {
+    return failed(type);
+  }
+  const members = context.declarations.collectMembers(name);
+  const nested = /* @__PURE__ */ new Set([...seen, name]);
+  const parts = members.map((member) => describe(context, member.type, nested));
+  return combine(parts, (values) => {
+    const rendered = members.map((member, index) => entries2([`key = ${quote2(member.name)}`, `value = ${values[index] ?? ""}`]));
+    return entries2([`kind = 'record'`, `name = ${quote2(name)}`, `members = ${entries2(rendered)}`]);
+  });
+}
+function describe(context, type, seen = /* @__PURE__ */ new Set()) {
+  const primitive = PRIMITIVE_KINDS[type.kind];
+  if (primitive !== void 0) {
+    return { lua: entries2([`kind = ${quote2(primitive)}`]), unreifiable: null };
+  }
+  if (type.kind === "string-literal") {
+    return { lua: entries2([`kind = 'literal'`, `value = ${quote2(type.value)}`]), unreifiable: null };
+  }
+  if (type.kind === "boolean-literal" || type.kind === "number-literal") {
+    return { lua: entries2([`kind = 'literal'`, `value = ${String(type.value)}`]), unreifiable: null };
+  }
+  if (type.kind === "optional") {
+    return combine([describe(context, type.element, seen)], (values) => entries2([`kind = 'optional'`, `element = ${values[0] ?? ""}`]));
+  }
+  if (type.kind === "array") {
+    return combine([describe(context, type.element, seen)], (values) => entries2([`kind = 'array'`, `element = ${values[0] ?? ""}`]));
+  }
+  if (type.kind === "map") {
+    return combine(
+      [describe(context, type.key, seen), describe(context, type.value, seen)],
+      (values) => entries2([`kind = 'map'`, `key = ${values[0] ?? ""}`, `value = ${values[1] ?? ""}`])
+    );
+  }
+  if (type.kind === "union") {
+    return combine(
+      type.options.map((option) => describe(context, option, seen)),
+      (values) => entries2([`kind = 'union'`, `options = ${entries2(values)}`])
+    );
+  }
+  if (type.kind === "record") {
+    const members = [...type.members];
+    const parts = members.map(([, member]) => describe(context, member, seen));
+    return combine(parts, (values) => {
+      const rendered = members.map(([key], index) => entries2([`key = ${quote2(key)}`, `value = ${values[index] ?? ""}`]));
+      return entries2([`kind = 'record'`, `name = ${quote2(type.name)}`, `members = ${entries2(rendered)}`]);
+    });
+  }
+  if (type.kind === "named") {
+    return namedDescriptor(context, type, type.name, seen);
+  }
+  return failed(type);
+}
+function classDescriptor(context, className, fields) {
+  const parts = fields.map((field2) => describe(context, field2.type));
+  return combine(parts, (values) => {
+    const rendered = fields.map((field2, index) => entries2([`key = ${quote2(field2.name)}`, `value = ${values[index] ?? ""}`]));
+    return entries2([`kind = 'record'`, `name = ${quote2(className)}`, `members = ${entries2(rendered)}`]);
+  });
+}
+
 // ../compiler/src/checker/decorators.ts
 function memberExpression(field2) {
   return {
@@ -14248,6 +15065,46 @@ function validateDecorators(context, decorators, target) {
 function decoratorFor(name, classDecorators, fieldDecorators) {
   return fieldDecorators.find((decorator) => decorator.name === name) ?? classDecorators.find((decorator) => decorator.name === name) ?? null;
 }
+function staticMethod(statement, name, returnAnnotation, kind, descriptor) {
+  const value = { name: "value", annotation: typeName("table", statement), isVararg: false, position: statement.position };
+  return {
+    kind: "class-method",
+    name,
+    isConstructor: false,
+    isSynthetic: true,
+    isStatic: true,
+    parameters: [value],
+    returnAnnotation,
+    body: [],
+    decorators: [],
+    generated: { kind, fields: [], descriptor },
+    position: statement.position
+  };
+}
+function expandValidated(context, statement, classDecorators, fieldTypes, occupied, generated) {
+  const found = classDecorators.find((decorator) => decorator.name === "Validated");
+  if (found === void 0) {
+    return;
+  }
+  const fields = [...fieldTypes].map(([field2, type]) => ({ name: field2.name, type, position: field2.position }));
+  const described = classDescriptor(context, statement.name, fields);
+  if (described.lua === null) {
+    const message = `Decorator "@Validated" cannot check type "${described.unreifiable}", which has no runtime shape. Remove the field, or narrow it to a checkable type.`;
+    context.report("check-unreifiable-type", message, found.position);
+    return;
+  }
+  for (const [name, kind, annotation] of [
+    ["validate", "validate", typeName(statement.name, statement)],
+    ["matches", "matches", typeName("boolean", statement)]
+  ]) {
+    if (occupied.has(name)) {
+      context.report("check-decorator-conflict", `Decorator "@Validated" would generate "${name}", which is already declared by "${occupied.get(name)}".`, found.position);
+      continue;
+    }
+    occupied.set(name, statement.name);
+    generated.push(staticMethod(statement, name, annotation, kind, described.lua));
+  }
+}
 function expandClassDecorators(context, statement, fieldTypes) {
   const generated = [];
   const occupied = new Map(statement.members.filter((member) => member.kind === "class-method").map((member) => [member.name, member.name]));
@@ -14309,6 +15166,7 @@ function expandClassDecorators(context, statement, fieldTypes) {
     Serializable: ["toTable", typeName("table", statement), "serializable"],
     Deserialize: ["fromTable", typeName("void", statement), "deserialize"]
   };
+  expandValidated(context, statement, classDecorators, fieldTypes, occupied, generated);
   for (const [decorator, [name, returnAnnotation, kind]] of Object.entries(classMethods)) {
     const found = classDecorators.find((value) => value.name === decorator);
     if (found !== void 0 && !occupied.has(name)) {
@@ -17567,6 +18425,9 @@ function checkEventUsage(context, expression) {
     return;
   }
   const name = eventName(expression);
+  if (name !== null) {
+    context.noteEventReference(name);
+  }
   const custom = name === null ? null : context.declarations.lookupEvent(name);
   const declared = name === null ? null : eventEnvironment(name);
   if (name === null || custom?.environment === "shared" || custom?.environment === context.environment || declared === null || declared === context.environment) {
@@ -17709,6 +18570,105 @@ function specializeEventCall(context, expression, signature) {
   return candidate === null ? null : specialize(signature, candidate);
 }
 
+// ../compiler/src/checker/method-receiver.ts
+var SELF_PARAMETER = "self";
+function resolveNonNominalMethod(receiver, method) {
+  if (receiver.kind !== "record") {
+    return null;
+  }
+  const member = receiver.members.get(method);
+  return member !== void 0 && member.kind === "function" ? member : null;
+}
+function withoutSelfParameter(signature) {
+  const names = signature.parameterNames;
+  if (names === void 0 || names[0] !== SELF_PARAMETER) {
+    return signature;
+  }
+  const minimum = Math.max(0, signature.minimumArguments - 1);
+  return createFunction(signature.parameters.slice(1), signature.returnType, minimum, signature.isVariadic, names.slice(1), signature.variadicType);
+}
+
+// ../compiler/src/checker/resource-exports.ts
+var RESOURCE_LOOKUP = "getResourceFromName";
+var EXPORTS_TABLE = "exports";
+var CALL_FUNCTION = "call";
+function literalString(expression) {
+  return expression?.kind === "string-literal" ? expression.value : null;
+}
+function resourceOfLookup(expression) {
+  if (expression?.kind !== "call-expression" || expression.callee.kind !== "identifier" || expression.callee.name !== RESOURCE_LOOKUP) {
+    return null;
+  }
+  return literalString(expression.args[0]);
+}
+function resourceOfExports(expression) {
+  if (expression.kind === "member-expression" && expression.object.kind === "identifier" && expression.object.name === EXPORTS_TABLE) {
+    return expression.property;
+  }
+  if (expression.kind !== "index-expression" || expression.object.kind !== "identifier" || expression.object.name !== EXPORTS_TABLE) {
+    return null;
+  }
+  return literalString(expression.index);
+}
+function abiType(context, text) {
+  const scanned = scan(text);
+  if (scanned.diagnostics.length > 0) {
+    return ANY_TYPE;
+  }
+  try {
+    return context.resolveAnnotation(parseTypeAnnotation(new TokenStream(scanned.tokens)));
+  } catch {
+    return ANY_TYPE;
+  }
+}
+function signatureOf(context, entry) {
+  const parameters = entry.parameters.map((parameter) => abiType(context, parameter.type));
+  const names = entry.parameters.map((parameter) => parameter.name);
+  const minimum = Math.min(Math.max(entry.minimumArguments, 0), parameters.length);
+  return createFunction(parameters, abiType(context, entry.returns), minimum, entry.variadic, names);
+}
+function checkSide(context, entry, resource, expression) {
+  if (canReference(context.environment, entry.side)) {
+    return;
+  }
+  const message = `Export "${entry.name}" of resource "${resource}" is ${entry.side}-only and cannot be called from a "${context.environment}" file.`;
+  context.report("check-resource-export-side", message, expression.position);
+}
+function checkKnownExport(context, resource, name, args, expression) {
+  const entry = lookupAbiExport(context.contracts, resource, name);
+  if (entry === null) {
+    const known = context.contracts.find((contract) => contract.resource === resource)?.exports.map((declared) => `"${declared.name}"`).join(", ");
+    const hint = known === void 0 || known.length === 0 ? " It exports nothing." : ` It exports ${known}.`;
+    checkValueList(context, args);
+    context.report("check-unknown-resource-export", `Resource "${resource}" has no export "${name}".${hint}`, expression.position);
+    return ANY_TYPE;
+  }
+  checkSide(context, entry, resource, expression);
+  return checkSignature(context, args, signatureOf(context, entry), expression.position);
+}
+function checkResourceCall(context, expression) {
+  if (context.contracts.length === 0) {
+    return null;
+  }
+  if (expression.method !== null) {
+    const resource2 = resourceOfExports(expression.callee);
+    if (resource2 === null || !knowsResource(context.contracts, resource2)) {
+      return null;
+    }
+    return checkKnownExport(context, resource2, expression.method, expression.args, expression);
+  }
+  if (expression.callee.kind !== "identifier" || expression.callee.name !== CALL_FUNCTION) {
+    return null;
+  }
+  const resource = resourceOfLookup(expression.args[0]);
+  const name = literalString(expression.args[1]);
+  if (resource === null || name === null || !knowsResource(context.contracts, resource)) {
+    return null;
+  }
+  checkValueList(context, expression.args.slice(0, 2));
+  return checkKnownExport(context, resource, name, expression.args.slice(2), expression);
+}
+
 // ../mta-types/src/library-members.ts
 var MATH_MEMBERS = {
   abs: fn([NUMBER], NUMBER, 1),
@@ -17983,12 +18943,13 @@ function resolveStaticMember(context, className, expression) {
   context.report("check-unknown-member", `Class "${className}" has no static member "${expression.property}".${hint}`, expression.position);
   return ANY_TYPE;
 }
-function resolveNamedMember(context, name, expression) {
+function resolveNamedMember(context, receiver, expression) {
+  const name = receiver.name;
   const enumeration = context.declarations.lookupEnum(name);
   if (enumeration !== null) {
     return checkEnumMember(context, name, enumeration.members, expression);
   }
-  const member = context.declarations.lookupMember(name, expression.property);
+  const member = memberOf(context, receiver, expression.property);
   if (member !== null) {
     if (member.deprecated === true) {
       context.warn("check-deprecated-use", `Member "${expression.property}" is deprecated.`, expression.position);
@@ -18023,6 +18984,29 @@ function nativeConstructor(context, name) {
   const constructor = symbol.type.members.get(NATIVE_CONSTRUCTOR);
   return constructor === void 0 || constructor.kind !== "function" ? null : constructor;
 }
+function constructorParameters(context, className) {
+  const constructor = context.declarations.lookupMember(className, "constructor");
+  return constructor?.type.kind === "function" ? constructor.type.parameters : [];
+}
+function resolveConstructorArguments(context, expression, typeParameters) {
+  const explicit = expression.typeArguments.map((argument) => context.resolveAnnotation(argument));
+  if (typeParameters.length === 0) {
+    if (explicit.length > 0) {
+      context.report("check-generic-arity", `Class "${expression.className}" does not accept type arguments.`, expression.position);
+    }
+    return [];
+  }
+  if (explicit.length === typeParameters.length) {
+    return explicit;
+  }
+  if (explicit.length > 0) {
+    const expected = typeParameters.length === 1 ? "1 type argument" : `${typeParameters.length} type arguments`;
+    context.report("check-generic-arity", `Class "${expression.className}" expects ${expected} but received ${explicit.length}.`, expression.position);
+    return typeParameters.map((unused, index) => explicit[index] ?? ANY_TYPE);
+  }
+  const argumentTypes = expression.args.map((argument) => checkExpression(context, argument));
+  return inferTypeArguments(typeParameters, constructorParameters(context, expression.className), argumentTypes);
+}
 function checkNewExpression(context, expression) {
   if (context.declarations.lookupClass(expression.className) === null) {
     const constructor2 = nativeConstructor(context, expression.className);
@@ -18041,13 +19025,20 @@ function checkNewExpression(context, expression) {
     const subject = pending === expression.className ? `Class "${pending}"` : `Class "${expression.className}" extends "${pending}", which`;
     context.report("check-class-before-declaration", `${subject} is declared further down this file, so it does not exist yet at this point.`, expression.position);
   }
+  const info = context.declarations.lookupClass(expression.className);
+  const typeArguments = resolveConstructorArguments(context, expression, info?.typeParameters ?? []);
+  checkTypeConstraints(context, expression.className, typeArguments, expression.position);
   const constructor = context.declarations.lookupMember(expression.className, "constructor");
   if (constructor !== null && constructor.type.kind === "function") {
-    checkSignature(context, expression.args, constructor.type, expression.position);
+    const substitutions = info === null ? /* @__PURE__ */ new Map() : classSubstitutions(info, typeArguments);
+    const signature = substituteType(constructor.type, substitutions);
+    if (signature.kind === "function") {
+      checkSignature(context, expression.args, signature, expression.position);
+    }
   } else {
     expression.args.forEach((argument) => checkExpression(context, argument));
   }
-  return createNamed(expression.className);
+  return createNamed(expression.className, typeArguments);
 }
 function resolveSuperMethod(context, expression) {
   const frame = context.currentClassMethod();
@@ -18136,14 +19127,14 @@ function isShapeOption(context, option) {
   }
   return context.declarations.lookupInterface(option.name) !== null || context.declarations.lookupClass(option.name) !== null;
 }
-function memberOf(context, option, property) {
+function memberOf2(context, option, property) {
   if (option.kind === "record") {
     return option.members.get(property) ?? null;
   }
   return option.kind === "named" ? context.declarations.lookupMember(option.name, property)?.type ?? null : null;
 }
 function optionMemberType(context, option, property) {
-  return isShapeOption(context, option) ? memberOf(context, option, property) : null;
+  return isShapeOption(context, option) ? memberOf2(context, option, property) : null;
 }
 function resolveUnionMember(context, type, expression) {
   if (!type.options.every((option) => isShapeOption(context, option))) {
@@ -18152,7 +19143,7 @@ function resolveUnionMember(context, type, expression) {
   const resolved2 = [];
   const missing2 = [];
   for (const option of type.options) {
-    const member = memberOf(context, option, expression.property);
+    const member = memberOf2(context, option, expression.property);
     if (member === null) {
       missing2.push(`"${typeToString(option)}"`);
     } else {
@@ -18319,26 +19310,6 @@ function conditionFacts(context, condition) {
   collectFacts(context, condition, facts);
   return facts;
 }
-function alwaysExits(body) {
-  const last = body[body.length - 1];
-  if (last === void 0) {
-    return false;
-  }
-  if (last.kind === "return-statement" || last.kind === "break-statement") {
-    return true;
-  }
-  if (last.kind !== "if-statement" || last.alternate === null) {
-    return false;
-  }
-  return last.clauses.every((clause) => alwaysExits(clause.body)) && alwaysExits(last.alternate);
-}
-function guardFacts(context, statement) {
-  const [clause] = statement.kind === "if-statement" ? statement.clauses : [];
-  if (statement.kind !== "if-statement" || statement.alternate !== null || statement.clauses.length !== 1 || clause === void 0) {
-    return /* @__PURE__ */ new Map();
-  }
-  return alwaysExits(clause.body) ? negatedFacts(context, clause.condition) : /* @__PURE__ */ new Map();
-}
 function negatedFacts(context, condition) {
   const facts = /* @__PURE__ */ new Map();
   if (condition.kind === "binary-expression" && condition.operator === "or") {
@@ -18369,23 +19340,58 @@ var ITERATOR_FUNCTIONS = /* @__PURE__ */ new Set(["pairs", "ipairs"]);
 function checkBlock(context, body) {
   context.binder.pushScope();
   checkStatements(context, body);
+  const declared = context.binder.currentScopeNames();
   context.binder.popScope();
+  for (const name of declared) {
+    context.forgetNarrowing(name);
+  }
 }
-function checkNarrowedBlock(context, facts, body) {
-  context.pushNarrowing(facts);
+function branch(context, entry, facts, body) {
+  const state = cloneFlow(entry);
+  applyFacts(state, facts);
+  context.setFlow(state);
   checkBlock(context, body);
-  context.popNarrowing();
+  return context.flowState;
 }
 function checkIf(context, clauses, alternate) {
+  const exits = [];
+  let current = context.flowState;
   for (const clause of clauses) {
+    context.setFlow(current);
     checkExpression(context, clause.condition);
-    checkNarrowedBlock(context, conditionFacts(context, clause.condition), clause.body);
+    const taken = conditionFacts(context, clause.condition);
+    const skipped = cloneFlow(current);
+    applyFacts(skipped, negatedFacts(context, clause.condition));
+    exits.push(branch(context, current, taken, clause.body));
+    current = skipped;
   }
   if (alternate === null) {
-    return;
+    exits.push(current);
+  } else {
+    context.setFlow(current);
+    checkBlock(context, alternate);
+    exits.push(context.flowState);
   }
-  const [only] = clauses;
-  checkNarrowedBlock(context, clauses.length === 1 && only !== void 0 ? negatedFacts(context, only.condition) : /* @__PURE__ */ new Map(), alternate);
+  context.setFlow(joinFlows(exits));
+}
+function checkLoopBody(context, body, facts) {
+  forgetAssignedPaths(context, body);
+  const entry = context.flowState;
+  const state = cloneFlow(entry);
+  applyFacts(state, facts);
+  context.setFlow(state);
+  checkBlock(context, body);
+  context.setFlow(entry);
+}
+function checkWhile(context, statement) {
+  forgetAssignedPaths(context, statement.body);
+  checkExpression(context, statement.condition);
+  checkLoopBody(context, statement.body, conditionFacts(context, statement.condition));
+  context.applyFlowFacts(negatedFacts(context, statement.condition));
+}
+function checkRepeat(context, statement) {
+  checkLoopBody(context, statement.body, /* @__PURE__ */ new Map());
+  checkExpression(context, statement.condition);
 }
 function checkNumericFor(context, statement) {
   const bounds = [statement.start, statement.limit, statement.step].filter((value) => value !== null);
@@ -18396,10 +19402,13 @@ function checkNumericFor(context, statement) {
     }
   }
   forgetAssignedPaths(context, statement.body);
+  const entry = context.flowState;
+  context.setFlow(cloneFlow(entry));
   context.binder.pushScope();
   context.binder.declare({ name: statement.variable.name, type: NUMBER_TYPE, isLocal: true, position: statement.variable.position, origin: "local" });
   checkStatements(context, statement.body);
   context.binder.popScope();
+  context.setFlow(entry);
 }
 function iteratedTypes(context, iterators) {
   const [iterator] = iterators;
@@ -18420,6 +19429,8 @@ function checkGenericFor(context, statement) {
   statement.iterators.forEach((iterator) => checkExpression(context, iterator));
   const iterated = iteratedTypes(context, statement.iterators);
   forgetAssignedPaths(context, statement.body);
+  const entry = context.flowState;
+  context.setFlow(cloneFlow(entry));
   context.binder.pushScope();
   statement.variables.forEach((variable, index) => {
     const inferred = iterated[index] ?? ANY_TYPE;
@@ -18428,6 +19439,7 @@ function checkGenericFor(context, statement) {
   });
   checkStatements(context, statement.body);
   context.binder.popScope();
+  context.setFlow(entry);
 }
 
 // ../compiler/src/checker/events.ts
@@ -18488,15 +19500,19 @@ function minimumArguments(context, parameters) {
 }
 function buildFunctionType(context, parameters, returnAnnotation, contextual = null) {
   const isVariadic = parameters.some((parameter) => parameter.isVararg);
-  const types = parameters.filter((parameter) => !parameter.isVararg).map((parameter, index) => parameter.annotation === null ? contextual?.parameters[index] ?? ANY_TYPE : context.resolveAnnotation(parameter.annotation));
-  return createFunction(types, context.resolveAnnotation(returnAnnotation), minimumArguments(context, parameters), isVariadic);
+  const named2 = parameters.filter((parameter) => !parameter.isVararg);
+  const types = named2.map((parameter, index) => parameter.annotation === null ? contextual?.parameters[index] ?? ANY_TYPE : context.resolveAnnotation(parameter.annotation));
+  const names = named2.map((parameter) => parameter.name);
+  return createFunction(types, context.resolveAnnotation(returnAnnotation), minimumArguments(context, parameters), isVariadic, names);
 }
-function checkFunctionBody(context, parameters, returnAnnotation, body, signature, selfType) {
+function checkFunctionBody(context, parameters, returnAnnotation, body, signature, selfType2) {
   forgetAssignedPaths(context, body);
+  const entry = context.flowState;
+  context.setFlow(cloneFlow(entry));
   context.binder.pushScope();
   context.pushReturnType(returnAnnotation === null ? null : context.resolveAnnotation(returnAnnotation));
-  if (selfType !== null) {
-    context.binder.declare({ name: "self", type: selfType, isLocal: true, position: ORIGIN });
+  if (selfType2 !== null) {
+    context.binder.declare({ name: "self", type: selfType2, isLocal: true, position: ORIGIN });
   }
   let parameterIndex = 0;
   for (const parameter of parameters) {
@@ -18512,6 +19528,7 @@ function checkFunctionBody(context, parameters, returnAnnotation, body, signatur
     signature.returnType = inferred;
   }
   context.binder.popScope();
+  context.setFlow(entry);
 }
 function valueAt(values, valueTypes, index) {
   if (values[index] !== void 0) {
@@ -18535,6 +19552,9 @@ function checkLocal(context, statement) {
       context.expectAssignable(valueType, declared, value.position, `Variable "${declaration.name}"`);
     }
     context.binder.declare({ name: declaration.name, type: declared, isLocal: true, position: declaration.position, origin: "local" });
+    if (value !== void 0) {
+      recordAssignedFact(context, declaration.name, valueType, declared);
+    }
   });
 }
 function checkCompoundOperand(context, operator, type, position2) {
@@ -18548,6 +19568,15 @@ function checkCompoundOperand(context, operator, type, position2) {
     context.report("check-invalid-operand", `Operator "${operator}" cannot be applied to "${typeToString(type)}".`, position2);
   }
 }
+function recordAssignedFact(context, path, valueType, declared) {
+  if (path === null || valueType.kind === "any") {
+    return;
+  }
+  const fact = assignmentFact(widenInferred(valueType), declared);
+  if (fact !== null) {
+    context.applyFlowFacts(/* @__PURE__ */ new Map([[path, fact]]));
+  }
+}
 function checkAssignment(context, statement) {
   const valueTypes = checkValueList(context, statement.values);
   statement.targets.forEach((target, index) => {
@@ -18583,6 +19612,7 @@ function checkAssignment(context, statement) {
     if (value !== void 0) {
       context.expectAssignable(valueType, declared, value.position, "Assignment");
     }
+    recordAssignedFact(context, pathOf2(target), valueType, declared);
   });
 }
 function checkFunctionDeclaration(context, statement) {
@@ -18661,18 +19691,19 @@ function checkStatement(context, statement) {
     case "function-declaration":
       return checkFunctionDeclaration(context, statement);
     case "return-statement":
-      return checkReturn(context, statement);
+      checkReturn(context, statement);
+      context.markUnreachable();
+      return;
+    case "break-statement":
+    case "continue-statement":
+      context.markUnreachable();
+      return;
     case "do-statement":
       return checkBlock(context, statement.body);
     case "while-statement":
-      checkExpression(context, statement.condition);
-      forgetAssignedPaths(context, statement.body);
-      return checkBlock(context, statement.body);
+      return checkWhile(context, statement);
     case "repeat-statement":
-      forgetAssignedPaths(context, statement.body);
-      checkBlock(context, statement.body);
-      checkExpression(context, statement.condition);
-      return;
+      return checkRepeat(context, statement);
     case "if-statement":
       return checkIf(context, statement.clauses, statement.alternate);
     case "numeric-for-statement":
@@ -18702,18 +19733,8 @@ function checkStatement(context, statement) {
   }
 }
 function checkStatements(context, statements) {
-  let guards = 0;
   for (const statement of statements) {
     checkStatement(context, statement);
-    const facts = guardFacts(context, statement);
-    if (facts.size > 0) {
-      context.pushNarrowing(facts);
-      guards += 1;
-    }
-  }
-  while (guards > 0) {
-    context.popNarrowing();
-    guards -= 1;
   }
 }
 
@@ -18788,7 +19809,7 @@ function checkMember(context, expression) {
   if (objectType.kind === "map" && isAssignable(STRING_TYPE, objectType.key)) {
     return context.record(expression, objectType.value);
   }
-  const named2 = objectType.kind === "named" ? resolveNamedMember(context, objectType.name, expression) : null;
+  const named2 = objectType.kind === "named" ? resolveNamedMember(context, objectType, expression) : null;
   if (named2 !== null) {
     return context.record(expression, named2);
   }
@@ -18845,10 +19866,14 @@ function isLegacySuperCall(expression) {
 }
 function checkMethodCall(context, expression, method, receiver) {
   if (receiver.kind !== "named") {
-    checkValueList(context, expression.args);
-    return ANY_TYPE;
+    const signature = resolveNonNominalMethod(receiver, method);
+    if (signature === null) {
+      checkValueList(context, expression.args);
+      return ANY_TYPE;
+    }
+    return checkSignature(context, expression.args, withoutSelfParameter(signature), expression.position);
   }
-  const declared = context.declarations.lookupMember(receiver.name, method);
+  const declared = memberOf(context, receiver, method);
   if (declared?.type.kind === "function") {
     if (declared.deprecated === true) {
       context.warn("check-deprecated-use", `Member "${method}" is deprecated.`, expression.position);
@@ -18867,6 +19892,10 @@ function checkMethodCall(context, expression, method, receiver) {
   return checkSignature(context, expression.args, member.type, expression.position);
 }
 function checkCall(context, expression) {
+  const contracted = checkResourceCall(context, expression);
+  if (contracted !== null) {
+    return context.record(expression, contracted);
+  }
   if (isLegacySuperCall(expression)) {
     checkValueList(context, expression.args);
     context.report("check-invalid-super", 'Call "super(...)" directly instead of "self:super(...)".', expression.position);
@@ -18967,6 +19996,9 @@ function checkMultiValueExpression(context, expression, expected = null) {
       if (symbol === null) {
         checkGlobalReference(context, expression.name, expression.position);
       }
+      if (symbol === null || symbol.isLocal !== true) {
+        context.noteGlobalReference(expression.name);
+      }
       return context.record(expression, context.narrowedType(expression.name) ?? symbol?.type ?? ANY_TYPE);
     }
     case "member-expression":
@@ -19079,6 +20111,11 @@ function registerMembers(context, info, statement) {
   for (const member of [...statement.members, ...generated]) {
     const type = member.kind === "class-field" ? fieldTypes.get(member) ?? ANY_TYPE : member.isSynthetic ? syntheticMethodType(context, member, fieldTypes) : buildFunctionType(context, member.parameters, member.returnAnnotation);
     const decorators = member.decorators.map((decorator) => decorator.name);
+    if (member.kind === "class-method" && isMetamethodMember(member)) {
+      checkMetamethod(context, info.name, member, type);
+      continue;
+    }
+    reportRejectedMetamethod(context, info.name, member);
     const space = member.isStatic ? info.statics : info.members;
     space.set(member.name, {
       name: member.name,
@@ -19106,9 +20143,22 @@ function declareBuilder(context, info, statement) {
     }
   }
   members.set("build", { name: "build", type: { kind: "function", parameters: [], minimumArguments: 0, isVariadic: false, returnType: createNamed(statement.name) }, isMethod: true, position: statement.position });
-  context.declarations.declareClass({ name, superClass: null, interfaces: [], members, statics: /* @__PURE__ */ new Map(), position: statement.position });
+  context.declarations.declareClass({
+    name,
+    typeParameters: [],
+    typeConstraints: [],
+    superClass: null,
+    superArguments: [],
+    interfaces: [],
+    members,
+    statics: /* @__PURE__ */ new Map(),
+    position: statement.position
+  });
   context.declareModuleGlobal({ name, type: createNamed(name), isLocal: false, position: statement.position });
 }
+function selfType(info) {
+  return createNamed(info.name, info.typeParameters.map((parameter) => createNamed(parameter)));
+}
 function checkMethodBody(context, info, member) {
   const explicitSelf = member.parameters.find((parameter) => parameter.name === "self");
   if (explicitSelf !== void 0) {
@@ -19123,7 +20173,7 @@ function checkMethodBody(context, info, member) {
     return;
   }
   context.pushClassMethod({ className: info.name, methodName: member.name });
-  checkFunctionBody(context, member.parameters, member.returnAnnotation, member.body, signature, createNamed(info.name));
+  checkFunctionBody(context, member.parameters, member.returnAnnotation, member.body, signature, selfType(info));
   context.popClassMethod();
 }
 function resolveSuperClass(context, statement) {
@@ -19146,6 +20196,10 @@ function resolveSuperClass(context, statement) {
   context.report("check-unknown-class", message, statement.position);
   return null;
 }
+function resolveClassHeader(context, info, statement) {
+  info.superArguments = statement.superClassArguments.map((argument) => context.resolveAnnotation(argument));
+  info.typeConstraints = statement.typeConstraints.map((constraint) => constraint === null ? null : context.resolveAnnotation(constraint));
+}
 function declareClassInfo(context, statement) {
   if (context.declarations.lookupClass(statement.name) !== null) {
     context.report("check-duplicate-class", `Class "${statement.name}" is already defined.`, statement.position);
@@ -19157,12 +20211,16 @@ function declareClassInfo(context, statement) {
   }
   const info = {
     name: statement.name,
+    typeParameters: statement.typeParameters,
+    typeConstraints: [],
     superClass: null,
+    superArguments: [],
     interfaces: statement.interfaces,
     members: /* @__PURE__ */ new Map(),
     statics: /* @__PURE__ */ new Map(),
     position: statement.position
   };
+  context.noteTypeParameters(statement.typeParameters);
   context.declarations.declareClass(info);
   context.declareModuleGlobal({ name: info.name, type: createNamed(info.name), isLocal: false, position: statement.position });
   return info;
@@ -19173,6 +20231,7 @@ function declareLocalClass(context, statement) {
     return null;
   }
   info.superClass = resolveSuperClass(context, statement);
+  resolveClassHeader(context, info, statement);
   return info;
 }
 function checkClassDeclaration(context, statement) {
@@ -19286,6 +20345,7 @@ function predeclareModule(context, body) {
   const declared = declareHeaders(context, body);
   for (const entry of declared) {
     entry.info.superClass = resolveSuperClass(context, entry.statement);
+    resolveClassHeader(context, entry.info, entry.statement);
   }
   for (const entry of declared) {
     breakCycle(context, entry.info);
@@ -19345,17 +20405,23 @@ function externalReferences(context) {
   }
   return external;
 }
+function referencedNames(context, external) {
+  const events = [...context.eventReferences].map((name) => `${EVENT_NAME_PREFIX}${name}`);
+  return /* @__PURE__ */ new Set([...external.keys(), ...context.globalReferences, ...context.unknownTypes.keys(), ...events]);
+}
 function check(program2, mode, environment = DEFAULT_ENVIRONMENT, options = {}) {
   const ambient = options.ambient ?? EMPTY_AMBIENT;
   const project = options.project ?? EMPTY_PROJECT_DECLARATIONS;
   const context = new CheckContext(mode, environment, ambient, project, options.oop === true);
   context.isDeclarationFile = options.isDeclarationFile === true;
+  context.contracts = options.contracts ?? [];
   const structure = context.isDeclarationFile ? checkDeclarationFile(program2.body) : checkJumps(program2.body);
   const directives = collectDirectives(program2.body, { isDeclarationFile: context.isDeclarationFile });
   predeclareModule(context, program2.body);
   checkStatements(context, program2.body);
   reportUnknownTypes(context);
   reportUnusedSymbols(context, options.noUnusedLocals === true, options.noUnusedParameters === true);
+  const external = externalReferences(context);
   return {
     diagnostics: sortDiagnostics([...structure, ...directives.diagnostics, ...context.diagnostics]),
     types: context.types,
@@ -19364,7 +20430,9 @@ function check(program2, mode, environment = DEFAULT_ENVIRONMENT, options = {})
     declarations: context.declarations,
     aliases: context.binder.resolvedAliases(),
     declaredGlobals: context.declaredGlobals,
-    externalReferences: externalReferences(context),
+    moduleGlobals: context.moduleGlobals,
+    externalReferences: external,
+    referencedNames: referencedNames(context, external),
     directives: directives.directives,
     mode,
     environment,
@@ -19491,8 +20559,8 @@ function typeOf(state, expression) {
 function indentLine(state, text) {
   return `${INDENT2.repeat(state.indent)}${text}`;
 }
-function markSource(state, sourceLine, symbol = state.symbol) {
-  const marker = { sourceLine };
+function markSource(state, sourceLine2, symbol = state.symbol) {
+  const marker = { sourceLine: sourceLine2 };
   if (symbol !== void 0) {
     marker.symbol = symbol;
   }
@@ -19762,6 +20830,13 @@ function emitGeneratedMethod(state, className, member) {
         end
     end`;
   }
+  if (member.generated?.kind === "validate" || member.generated?.kind === "matches") {
+    const helper = member.generated.kind === "validate" ? "__luam_validate" : "__luam_matches";
+    requireHelper(state, "validate");
+    return `${member.name} = function(value)
+        return ${helper}(value, ${member.generated.descriptor ?? "{ kind = 'table' }"})
+    end`;
+  }
   if (member.generated?.kind === "to-string") {
     const values = names.map((name) => `'${name}=' .. tostring(self.${name})`).join(" .. ', ' .. ");
     const body = values.length === 0 ? "''" : values;
@@ -19797,24 +20872,24 @@ ${names.map((name) => `        self.${name} = values.${name}`).join("\n")}
     end`;
 }
 function emitMembers(state, statement) {
-  const entries2 = [];
+  const entries3 = [];
   state.indent += 1;
   for (const member of statement.members) {
     if (member.kind === "class-method") {
-      entries2.push(indentLine(state, `${markSource(state, member.position.line, `${statement.name}${member.isStatic ? "." : ":"}${member.name}`)}${emitMethod(state, statement.name, member)}`));
+      entries3.push(indentLine(state, `${markSource(state, member.position.line, `${statement.name}${member.isStatic ? "." : ":"}${member.name}`)}${emitMethod(state, statement.name, member)}`));
       continue;
     }
     if (member.decorators.some((decorator) => decorator.name === "Lazy")) {
       continue;
     }
     const value = member.value === null ? "nil" : emitExpression(state, member.value);
-    entries2.push(indentLine(state, `${markSource(state, member.position.line, statement.name)}${member.name} = ${value}`));
+    entries3.push(indentLine(state, `${markSource(state, member.position.line, statement.name)}${member.name} = ${value}`));
   }
   for (const generated of state.generatedMembers.get(statement) ?? []) {
-    entries2.push(indentLine(state, `${markSource(state, generated.position.line, `${statement.name}:${generated.name}`)}${emitMethod(state, statement.name, generated)}`));
+    entries3.push(indentLine(state, `${markSource(state, generated.position.line, `${statement.name}:${generated.name}`)}${emitMethod(state, statement.name, generated)}`));
   }
   state.indent -= 1;
-  return entries2;
+  return entries3;
 }
 function emitClassHeader(statement) {
   const name = emitString(statement.name);
@@ -19840,15 +20915,15 @@ ${assignments}
         return value
     end`);
   state.indent += 1;
-  const entries2 = methods.map((method) => indentLine(state, method));
+  const entries3 = methods.map((method) => indentLine(state, method));
   state.indent -= 1;
-  return [`class '${name}' {`, entries2.join(",\n"), "}"].join("\n");
+  return [`class '${name}' {`, entries3.join(",\n"), "}"].join("\n");
 }
 function emitClassDeclaration(state, statement) {
   requireHelper(state, "class");
   const header = emitClassHeader(statement);
-  const entries2 = emitMembers(state, statement);
-  const declaration = entries2.length === 0 ? `${header} {}` : [`${header} {`, entries2.join(",\n"), indentLine(state, "}")].join("\n");
+  const entries3 = emitMembers(state, statement);
+  const declaration = entries3.length === 0 ? `${header} {}` : [`${header} {`, entries3.join(",\n"), indentLine(state, "}")].join("\n");
   const builder = emitBuilder(state, statement);
   return builder === null ? declaration : `${declaration}
 ${builder}`;
@@ -20786,6 +21861,7 @@ function compile(source, options = {}) {
   const isDeclarationFile = options.filePath !== void 0 && isDeclarationPath(options.filePath);
   const checked = check(parsed.program, mode, environment, {
     ambient: options.ambient ?? EMPTY_AMBIENT,
+    contracts: options.contracts ?? [],
     project: options.project ?? EMPTY_PROJECT_DECLARATIONS,
     isDeclarationFile,
     oop: settings.oop,
@@ -20799,7 +21875,9 @@ function compile(source, options = {}) {
     environment,
     declarations: ownDeclarations(checked.declarations, options.ambient),
     declaredGlobals: checked.declaredGlobals,
+    moduleGlobals: checked.moduleGlobals,
     externalReferences: checked.externalReferences,
+    referencedNames: checked.referencedNames,
     directives: checked.directives,
     topLevelReturn: findTopLevelReturn(parsed.program.body),
     events: checked.events
@@ -20890,6 +21968,199 @@ function fingerprintDeclarations(declarations) {
   const events = declarations.events.map(eventText);
   return hashString([...classes, ...interfaces, ...enums, ...globals, ...events].sort(compareText).join(";"));
 }
+function appendText(entries3, name, text) {
+  const existing = entries3.get(name);
+  entries3.set(name, existing === void 0 ? text : `${existing}|${text}`);
+}
+function fingerprintByName(declarations) {
+  const entries3 = /* @__PURE__ */ new Map();
+  for (const info of declarations.classes) {
+    appendText(entries3, info.name, classText(info));
+  }
+  for (const info of declarations.interfaces) {
+    appendText(entries3, info.name, interfaceText(info));
+  }
+  for (const info of declarations.enums) {
+    appendText(entries3, info.name, enumText(info));
+  }
+  for (const info of declarations.globals) {
+    appendText(entries3, info.name, globalText(info));
+  }
+  for (const info of declarations.events) {
+    appendText(entries3, `${EVENT_NAME_PREFIX}${info.name}`, eventText(info));
+  }
+  return new Map([...entries3].map(([name, text]) => [name, hashString(text)]));
+}
+
+// ../compiler/src/project/dependency-graph.ts
+var MAX_CLOSURE_SIZE = 512;
+function indexOwners(nodes, environment) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    if (!canReference(environment, node.environment)) {
+      continue;
+    }
+    for (const name of node.provides.keys()) {
+      const existing = owners.get(name);
+      if (existing === void 0) {
+        owners.set(name, [node]);
+        continue;
+      }
+      existing.push(node);
+    }
+  }
+  return owners;
+}
+function walk3(node, owners) {
+  const visited = /* @__PURE__ */ new Set();
+  const pending = [...node.requires, ...node.provides.keys()];
+  while (pending.length > 0) {
+    const name = pending.pop();
+    if (name === void 0 || visited.has(name)) {
+      continue;
+    }
+    visited.add(name);
+    if (visited.size > MAX_CLOSURE_SIZE) {
+      return null;
+    }
+    for (const owner of owners.get(name) ?? []) {
+      for (const required of owner.requires) {
+        if (!visited.has(required)) {
+          pending.push(required);
+        }
+      }
+    }
+  }
+  return visited;
+}
+function ownerText(owners, name) {
+  const list = owners.get(name) ?? [];
+  return `${name}=${list.map((owner) => `${owner.path}:${owner.provides.get(name) ?? ""}`).sort().join("+")}`;
+}
+function createDependencyGraph(nodes) {
+  const byPath = new Map(nodes.map((node) => [node.path, node]));
+  const indexes = /* @__PURE__ */ new Map();
+  const closures = /* @__PURE__ */ new Map();
+  const keys = /* @__PURE__ */ new Map();
+  function ownersFor(environment) {
+    const cached = indexes.get(environment);
+    if (cached !== void 0) {
+      return cached;
+    }
+    const owners = indexOwners(nodes, environment);
+    indexes.set(environment, owners);
+    return owners;
+  }
+  function closureOf(path) {
+    if (closures.has(path)) {
+      return closures.get(path) ?? null;
+    }
+    const node = byPath.get(path);
+    const closure = node === void 0 ? null : walk3(node, ownersFor(node.environment));
+    closures.set(path, closure);
+    return closure;
+  }
+  function keyOf(path) {
+    if (keys.has(path)) {
+      return keys.get(path) ?? null;
+    }
+    const node = byPath.get(path);
+    const closure = closureOf(path);
+    if (node === void 0 || closure === null) {
+      keys.set(path, null);
+      return null;
+    }
+    const owners = ownersFor(node.environment);
+    const key = hashString([...closure].sort().map((name) => ownerText(owners, name)).join(";"));
+    keys.set(path, key);
+    return key;
+  }
+  return {
+    closureOf,
+    keyOf,
+    dependentsOf: (names) => {
+      const dependents = /* @__PURE__ */ new Set();
+      for (const node of nodes) {
+        const closure = closureOf(node.path);
+        if (closure === null) {
+          dependents.add(node.path);
+          continue;
+        }
+        for (const name of names) {
+          if (closure.has(name)) {
+            dependents.add(node.path);
+            break;
+          }
+        }
+      }
+      return dependents;
+    },
+    providedBy: (paths) => {
+      const names = /* @__PURE__ */ new Set();
+      for (const path of paths) {
+        for (const name of byPath.get(path)?.provides.keys() ?? []) {
+          names.add(name);
+        }
+      }
+      return names;
+    }
+  };
+}
+
+// ../compiler/src/project/ambient-scope.ts
+function optionsKey(options) {
+  return `${options.strict ? "strict" : ""}|${options.oop ? "oop" : ""}|${options.noUnusedLocals ? "nul" : ""}|${options.noUnusedParameters ? "nup" : ""}`;
+}
+function declaresNothing(declarations) {
+  const { classes, interfaces, enums, globals, events } = declarations;
+  return classes.length === 0 && interfaces.length === 0 && enums.length === 0 && globals.length === 0 && events.length === 0;
+}
+function sharedEnums(collected) {
+  const declared = new Set(collected.flatMap((entry) => entry.declarations.enums.map((enumeration) => enumeration.name)));
+  if (declared.size === 0) {
+    return declared;
+  }
+  return new Set(collected.flatMap((entry) => entry.externalReferences.filter((name) => declared.has(name))));
+}
+function baseKey(context) {
+  const mode = context.development ? "development" : "release";
+  const contracts = context.contracts.map((contract) => serializeAbi(contract)).join(";");
+  return `${optionsKey(context.options)}|${mode}|${JSON.stringify(context.project.globals)}|${[...context.references].sort().join(",")}|${hashString(contracts)}`;
+}
+function environmentKeys(collected) {
+  const keys = {};
+  for (const environment of ALL_ENVIRONMENTS) {
+    const visible = collected.filter((entry) => canReference(environment, entry.environment));
+    keys[environment] = hashString(visible.map((entry) => `${entry.path}=${entry.fingerprint}`).join(";"));
+  }
+  return keys;
+}
+function createResolver(collected) {
+  const visible = /* @__PURE__ */ new Map();
+  const merged = /* @__PURE__ */ new Map();
+  for (const environment of ALL_ENVIRONMENTS) {
+    const entries3 = collected.filter((entry) => canReference(environment, entry.environment) && !declaresNothing(entry.declarations));
+    visible.set(environment, entries3);
+    merged.set(environment, mergeAmbient(entries3.map((entry) => entry.declarations)));
+  }
+  return (entry) => {
+    if (declaresNothing(entry.declarations)) {
+      return merged.get(entry.environment) ?? EMPTY_AMBIENT;
+    }
+    const entries3 = visible.get(entry.environment) ?? [];
+    return mergeAmbient(entries3.filter((candidate) => candidate.path !== entry.path).map((candidate) => candidate.declarations));
+  };
+}
+function createAmbientScope(collected, context) {
+  const graph = createDependencyGraph(collected);
+  const base = baseKey(context);
+  const fallback = environmentKeys(collected);
+  return {
+    graph,
+    keyFor: (entry) => hashString(`${base}|${graph.keyOf(entry.path) ?? fallback[entry.environment]}`),
+    resolve: createResolver(collected)
+  };
+}
 
 // ../compiler/src/project/module-graph.ts
 function buildSymbolTable(modules) {
@@ -20950,53 +22221,13 @@ function validateModuleReferences(modules) {
 function flattenDiagnostics(modules) {
   return modules.flatMap((module) => module.diagnostics.map((diagnostic) => ({ path: module.path, diagnostic })));
 }
-function optionsKey(options) {
-  return `${options.strict ? "strict" : ""}|${options.oop ? "oop" : ""}|${options.noUnusedLocals ? "nul" : ""}|${options.noUnusedParameters ? "nup" : ""}`;
-}
-function sharedEnums(collected) {
-  const declared = new Set(collected.flatMap((entry) => entry.declarations.enums.map((enumeration) => enumeration.name)));
-  if (declared.size === 0) {
-    return declared;
-  }
-  return new Set(collected.flatMap((entry) => entry.externalReferences.filter((name) => declared.has(name))));
-}
-function ambientKeys(collected, context) {
-  const keys = {};
-  const { project, references, options } = context;
-  const mode = context.development ? "development" : "release";
-  const projectKey = `${optionsKey(options)}|${mode}|${JSON.stringify(project.globals)}|${[...references].sort().join(",")}`;
-  for (const environment of ALL_ENVIRONMENTS) {
-    const visible = collected.filter((entry) => canReference(environment, entry.environment));
-    keys[environment] = hashString(`${projectKey}|${visible.map((entry) => `${entry.path}=${entry.fingerprint}`).join(";")}`);
-  }
-  return keys;
-}
-function declaresNothing(declarations) {
-  const { classes, interfaces, enums, globals, events } = declarations;
-  return classes.length === 0 && interfaces.length === 0 && enums.length === 0 && globals.length === 0 && events.length === 0;
-}
-function createAmbientResolver(collected) {
-  const visible = /* @__PURE__ */ new Map();
-  const merged = /* @__PURE__ */ new Map();
-  for (const environment of ALL_ENVIRONMENTS) {
-    const entries2 = collected.filter((entry) => canReference(environment, entry.environment) && !declaresNothing(entry.declarations));
-    visible.set(environment, entries2);
-    merged.set(environment, mergeAmbient(entries2.map((entry) => entry.declarations)));
-  }
-  return (entry) => {
-    if (declaresNothing(entry.declarations)) {
-      return merged.get(entry.environment) ?? EMPTY_AMBIENT;
-    }
-    const entries2 = visible.get(entry.environment) ?? [];
-    return mergeAmbient(entries2.filter((candidate) => candidate.path !== entry.path).map((candidate) => candidate.declarations));
-  };
-}
 function compileModule(file, ambient, context) {
   const result = compile(file.source, {
     filePath: file.path,
     ...file.environment === void 0 ? {} : { environment: file.environment },
     ambient,
-    project: context.project,
+    contracts: context.contracts,
+    project: isTestPath(file.path) ? context.testProject : context.project,
     projectReferences: context.projectReferences,
     compilerOptions: context.compilerOptions,
     development: context.development
@@ -21009,7 +22240,7 @@ function compileModule(file, ambient, context) {
     requiredHelpers: result.requiredHelpers,
     declaredGlobals: result.declaredGlobals,
     externalReferences: result.externalReferences,
-    contributions: toContributions(result.directives, result.environment),
+    contributions: toContributions(result.directives, result.environment, result.moduleGlobals),
     diagnostics: result.diagnostics,
     lines: result.lines,
     topLevelReturn: result.topLevelReturn,
@@ -21050,20 +22281,22 @@ function createProjectCache() {
       environment: result.environment,
       declarations: result.declarations,
       externalReferences: [...result.externalReferences.keys()],
-      fingerprint: fingerprintDeclarations(result.declarations)
+      fingerprint: fingerprintDeclarations(result.declarations),
+      provides: fingerprintByName(result.declarations),
+      requires: result.referencedNames
     };
     declarationCache.set(file.path, entry);
     return entry;
   }
   function moduleFor(pair, context, reused) {
     const { file, entry } = pair;
-    const ambientKey = context.keys[entry.environment];
+    const ambientKey = context.scope.keyFor(entry);
     const cached = moduleCache.get(file.path);
     if (cached !== void 0 && cached.hash === entry.hash && cached.ambientKey === ambientKey) {
       reused.count += 1;
       return cached.module;
     }
-    const module = compileModule(file, context.resolve(entry), context);
+    const module = compileModule(file, context.scope.resolve(entry), context);
     moduleCache.set(file.path, { hash: entry.hash, ambientKey, module });
     return module;
   }
@@ -21077,10 +22310,12 @@ function createProjectCache() {
       const collected = pairs.map((pair) => pair.entry);
       const projectReferences = sharedEnums(collected);
       const development = options.development === true;
+      const contracts = options.contracts ?? [];
       const context = {
-        keys: ambientKeys(collected, { project, references: projectReferences, options: compilerOptions, development }),
-        resolve: createAmbientResolver(collected),
+        scope: createAmbientScope(collected, { project, references: projectReferences, options: compilerOptions, development, contracts }),
+        contracts,
         project,
+        testProject: { globals: [...project.globals, ...TEST_DECLARATIONS] },
         projectReferences,
         compilerOptions,
         development
@@ -21159,8 +22394,8 @@ function materialize(build, resource, includeMap) {
   const bundled = materializeBundles(resource, build.bundles, helperContent);
   return { ...build, scripts: bundled.scripts, map: includeMap ? bundled.map : null };
 }
-function diagnosticSources(files, entries2) {
-  const paths = new Set(entries2.map((entry) => entry.path));
+function diagnosticSources(files, entries3) {
+  const paths = new Set(entries3.map((entry) => entry.path));
   return new Map(files.filter((file) => paths.has(file.path)).map((file) => [file.path, file.source]));
 }
 function runCompile(root, config, options = {}) {
@@ -21168,10 +22403,12 @@ function runCompile(root, config, options = {}) {
   const tracker = options.tracker ?? createPhaseTracker();
   const started = performance.now();
   tracker.begin("discovery");
-  const excluded = [config.outDir];
+  const excluded = [config.outDir, config.contracts];
   const sources = discoverSources(root, config.sources, excluded);
   const inputs = readProjectInputs(root, { assets: config.assets, environment: config.environment, excluded });
-  const diagnostics = [...sources.diagnostics, ...inputs.diagnostics];
+  const files = [...sources.files, ...options.additionalFiles ?? []].sort((left, right) => left.path.localeCompare(right.path));
+  const contracts = readDependencyContracts(root, config);
+  const diagnostics = [...sources.diagnostics, ...inputs.diagnostics, ...contracts.diagnostics];
   if (hasCliErrors(diagnostics)) {
     tracker.end("failed");
     return {
@@ -21184,13 +22421,15 @@ function runCompile(root, config, options = {}) {
       environmentTemplate: null,
       phases: tracker.durations(),
       sources: /* @__PURE__ */ new Map(),
-      map: null
+      map: null,
+      contract: null
     };
   }
-  tracker.begin("compile", sources.files.length);
+  tracker.begin("compile", files.length);
   const declarations = projectDeclarations(inputs.declared?.entries ?? null, config.environment.file);
-  const project = cache3.compile(sources.files, {
+  const project = cache3.compile(files, {
     project: declarations,
+    contracts: contracts.contracts,
     compilerOptions: config.compilerOptions,
     development: options.development === true,
     onProgress: (event) => tracker.advance(event.item, event.index, event.total)
@@ -21211,19 +22450,20 @@ function runCompile(root, config, options = {}) {
     build,
     diagnostics,
     fileDiagnostics: assembly.diagnostics,
-    fileCount: sources.files.length,
+    fileCount: files.length,
     durationMs: performance.now() - started,
     stats: project.stats,
     environmentTemplate: inputs.deployed === null ? null : renderEnvironmentTemplate(inputs.deployed),
     phases: tracker.durations(),
-    sources: diagnosticSources(sources.files, assembly.diagnostics),
-    map: build?.map ?? null
+    sources: diagnosticSources(files, assembly.diagnostics),
+    map: build?.map ?? null,
+    contract: build === null ? null : buildResourceAbi(config.name, project.modules.flatMap((module) => module.contributions))
   };
 }
 
 // src/build/resource-map-file.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync2, readFileSync as readFileSync6, readdirSync as readdirSync2, unlinkSync, writeFileSync as writeFileSync3 } from "node:fs";
-import { dirname as dirname2, isAbsolute as isAbsolute3, join as join4, posix, relative as relative2, resolve as resolve8 } from "node:path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync3, readFileSync as readFileSync7, readdirSync as readdirSync2, unlinkSync, writeFileSync as writeFileSync4 } from "node:fs";
+import { dirname as dirname3, isAbsolute as isAbsolute3, join as join4, posix, relative as relative2, resolve as resolve9 } from "node:path";
 var RESOURCE_MAP_SUFFIX = ".luam-map.json";
 function isObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -21288,10 +22528,10 @@ function reason(error) {
   return error instanceof Error ? error.message : String(error);
 }
 function resourceMapPath(root, config) {
-  return resolve8(root, config.outDir, `${config.name}${RESOURCE_MAP_SUFFIX}`);
+  return resolve9(root, config.outDir, `${config.name}${RESOURCE_MAP_SUFFIX}`);
 }
 function explicitResourceMapPath(root, path) {
-  return isAbsolute3(path) ? path : resolve8(root, path);
+  return isAbsolute3(path) ? path : resolve9(root, path);
 }
 function writeResourceMap(root, config, map) {
   const path = resourceMapPath(root, config);
@@ -21301,15 +22541,15 @@ function writeResourceMap(root, config, map) {
     }
     return;
   }
-  mkdirSync2(dirname2(path), { recursive: true });
+  mkdirSync3(dirname3(path), { recursive: true });
   const content = serializeResourceMap(map);
-  if (!existsSync5(path) || readFileSync6(path, "utf8") !== content) {
-    writeFileSync3(path, content, "utf8");
+  if (!existsSync5(path) || readFileSync7(path, "utf8") !== content) {
+    writeFileSync4(path, content, "utf8");
   }
 }
 function readResourceMap(path) {
   try {
-    const value = JSON.parse(readFileSync6(path, "utf8"));
+    const value = JSON.parse(readFileSync7(path, "utf8"));
     if (isObject(value) && Number.isInteger(value.version) && value.version !== RESOURCE_MAP_VERSION) {
       return { map: null, error: `Resource map version ${String(value.version)} is not supported.` };
     }
@@ -21323,13 +22563,13 @@ function isSearchable(name) {
   return !name.startsWith(".") && !SKIPPED_DIRECTORIES.has(name);
 }
 function collectResourceMaps(directory, found) {
-  let entries2;
+  let entries3;
   try {
-    entries2 = readdirSync2(directory, { withFileTypes: true });
+    entries3 = readdirSync2(directory, { withFileTypes: true });
   } catch {
     return;
   }
-  for (const entry of entries2) {
+  for (const entry of entries3) {
     const absolute = join4(directory, entry.name);
     if (entry.isDirectory()) {
       if (isSearchable(entry.name)) {
@@ -21353,8 +22593,8 @@ function discoverResourceMap(root) {
 }
 
 // src/build/resource-writer.ts
-import { existsSync as existsSync7, mkdirSync as mkdirSync3, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
-import { dirname as dirname3, isAbsolute as isAbsolute4, relative as relative4, resolve as resolve10 } from "node:path";
+import { existsSync as existsSync7, mkdirSync as mkdirSync4, readFileSync as readFileSync8, writeFileSync as writeFileSync5 } from "node:fs";
+import { dirname as dirname4, isAbsolute as isAbsolute4, relative as relative4, resolve as resolve11 } from "node:path";
 
 // src/build/lua-tokens.ts
 var WHITESPACE = /* @__PURE__ */ new Set([" ", "	", "\n", "\r", "\v", "\f"]);
@@ -21411,7 +22651,7 @@ function readLongBracket2(source, start, level, file) {
   return end + closing.length;
 }
 function readShortString(source, start, file) {
-  const quote2 = source[start];
+  const quote3 = source[start];
   let index = start + 1;
   while (index < source.length) {
     const char = source[index];
@@ -21419,7 +22659,7 @@ function readShortString(source, start, file) {
       index += 2;
       continue;
     }
-    if (char === quote2) {
+    if (char === quote3) {
       return index + 1;
     }
     if (char === "\n") {
@@ -21558,7 +22798,7 @@ function minifyLuaFiles(files) {
 
 // src/build/resource-prune.ts
 import { existsSync as existsSync6, readdirSync as readdirSync3, rmdirSync, unlinkSync as unlinkSync2 } from "node:fs";
-import { join as join5, relative as relative3, resolve as resolve9 } from "node:path";
+import { join as join5, relative as relative3, resolve as resolve10 } from "node:path";
 var GENERATED_MANIFEST = "meta.xml";
 var GENERATED_EXTENSION = ".lua";
 var PROTECTED = /* @__PURE__ */ new Set([ENVIRONMENT_FILE, ".env.local"]);
@@ -21575,14 +22815,14 @@ function isGenerated(relativePath2, options) {
   return options.generatedRoots.some((root) => isUnderRoot(relativePath2, root));
 }
 function removeEmptyDirectories(targetDir, directory) {
-  if (resolve9(directory) === resolve9(targetDir)) {
+  if (resolve10(directory) === resolve10(targetDir)) {
     return;
   }
   if (readdirSync3(directory).length > 0) {
     return;
   }
   rmdirSync(directory);
-  removeEmptyDirectories(targetDir, resolve9(directory, ".."));
+  removeEmptyDirectories(targetDir, resolve10(directory, ".."));
 }
 function pruneResource(targetDir, keep, options) {
   if (!existsSync6(targetDir)) {
@@ -21635,7 +22875,7 @@ function resourceFiles(build) {
   return files;
 }
 function resolveInside(targetDir, path) {
-  const absolute = resolve10(targetDir, path);
+  const absolute = resolve11(targetDir, path);
   const inside = relative4(targetDir, absolute);
   if (inside.startsWith("..") || isAbsolute4(inside)) {
     throw new Error(`The generated file "${path}" resolves outside the resource directory "${targetDir}".`);
@@ -21643,11 +22883,11 @@ function resolveInside(targetDir, path) {
   return absolute;
 }
 function writeIfChanged(absolute, content) {
-  if (existsSync7(absolute) && readFileSync7(absolute).equals(content)) {
+  if (existsSync7(absolute) && readFileSync8(absolute).equals(content)) {
     return false;
   }
-  mkdirSync3(dirname3(absolute), { recursive: true });
-  writeFileSync4(absolute, content);
+  mkdirSync4(dirname4(absolute), { recursive: true });
+  writeFileSync5(absolute, content);
   return true;
 }
 function writeEnvironmentFile(targetDir, template) {
@@ -21658,8 +22898,8 @@ function writeEnvironmentFile(targetDir, template) {
   if (existsSync7(absolute)) {
     return false;
   }
-  mkdirSync3(dirname3(absolute), { recursive: true });
-  writeFileSync4(absolute, template, "utf8");
+  mkdirSync4(dirname4(absolute), { recursive: true });
+  writeFileSync5(absolute, template, "utf8");
   return true;
 }
 function writeResource(targetDir, build, options) {
@@ -21683,7 +22923,7 @@ function writeResource(targetDir, build, options) {
     advance(path);
   }
   for (const asset of build.assets) {
-    if (writeIfChanged(resolveInside(targetDir, asset.path), readFileSync7(resolve10(options.root, asset.source)))) {
+    if (writeIfChanged(resolveInside(targetDir, asset.path), readFileSync8(resolve11(options.root, asset.source)))) {
       written.push(asset.path);
       advance(asset.path);
       continue;
@@ -21800,16 +23040,16 @@ function reportBuildOutcome(context, outcome, action) {
 }
 
 // src/commands/resource-targets.ts
-import { isAbsolute as isAbsolute5, resolve as resolve11 } from "node:path";
+import { isAbsolute as isAbsolute5, resolve as resolve12 } from "node:path";
 function resolveBuildTarget(root, config) {
-  return resolve11(root, config.outDir, config.name);
+  return resolve12(root, config.outDir, config.name);
 }
 function resolveServerTarget(root, config) {
   if (config.serverPath === null) {
     return null;
   }
-  const serverRoot = isAbsolute5(config.serverPath) ? config.serverPath : resolve11(root, config.serverPath);
-  return resolve11(serverRoot, config.resourcesDir, config.name);
+  const serverRoot = isAbsolute5(config.serverPath) ? config.serverPath : resolve12(root, config.serverPath);
+  return resolve12(serverRoot, config.resourcesDir, config.name);
 }
 
 // src/reporting/progress-renderer.ts
@@ -21854,7 +23094,7 @@ function createProgressRenderer(reporter, options = {}) {
     paint(reporter.style.eraseLine());
     dirty = false;
   }
-  function render(event) {
+  function render2(event) {
     const columns = Math.max(20, reporter.capability.columns - 1);
     const line2 = activeLine(reporter, event);
     paint(`${reporter.style.eraseLine()}${line2.slice(0, columns)}`);
@@ -21874,7 +23114,7 @@ function createProgressRenderer(reporter, options = {}) {
     if (frames > 0 && now() - lastPaintAt < throttleMs) {
       return;
     }
-    render(event);
+    render2(event);
   }
   return {
     listen: (event) => {
@@ -21932,6 +23172,9 @@ async function runBuildCommand(context, options = {}) {
     return EXIT_DIAGNOSTICS;
   }
   writeResourceMap(context.root, context.config, writtenMap(outcome.map, minify));
+  if (outcome.contract !== null && outcome.contract.exports.length > 0) {
+    writeResourceContract(context.root, context.config, outcome.contract);
+  }
   tracker.end();
   renderer.clear();
   reportBuildOutcome(context, outcome, "Build");
@@ -21982,6 +23225,298 @@ function registerCheckCommand(program2, runtime) {
   });
 }
 
+// src/commands/config-command.ts
+import { existsSync as existsSync8, mkdirSync as mkdirSync5, readFileSync as readFileSync9, writeFileSync as writeFileSync6 } from "node:fs";
+import { dirname as dirname5, relative as relative5, resolve as resolve13 } from "node:path";
+
+// ../compiler/src/project/config-reader.ts
+var Reader = class {
+  text;
+  index = 0;
+  problems = [];
+  constructor(text) {
+    this.text = text;
+  }
+  position() {
+    const before = this.text.slice(0, this.index);
+    const lines = before.split("\n");
+    return { line: lines.length, column: (lines[lines.length - 1]?.length ?? 0) + 1 };
+  }
+  fail(message) {
+    const { line: line2, column } = this.position();
+    this.problems.push({ line: line2, column, message });
+    return null;
+  }
+  skipComment() {
+    if (!this.text.startsWith("--", this.index)) {
+      return false;
+    }
+    if (this.text.startsWith("--[[", this.index)) {
+      const end2 = this.text.indexOf("]]", this.index + 4);
+      this.index = end2 === -1 ? this.text.length : end2 + 2;
+      return true;
+    }
+    const end = this.text.indexOf("\n", this.index);
+    this.index = end === -1 ? this.text.length : end + 1;
+    return true;
+  }
+  skip() {
+    for (; ; ) {
+      const before = this.index;
+      while (this.index < this.text.length && /\s/.test(this.text[this.index] ?? "")) {
+        this.index += 1;
+      }
+      this.skipComment();
+      if (this.index === before) {
+        return;
+      }
+    }
+  }
+  done() {
+    this.skip();
+    return this.index >= this.text.length;
+  }
+  peek() {
+    this.skip();
+    return this.text[this.index] ?? "";
+  }
+  take(value) {
+    this.skip();
+    if (!this.text.startsWith(value, this.index)) {
+      return false;
+    }
+    this.index += value.length;
+    return true;
+  }
+  word() {
+    this.skip();
+    const match = /^[A-Za-z_][A-Za-z0-9_]*/.exec(this.text.slice(this.index));
+    if (match === null) {
+      return null;
+    }
+    this.index += match[0].length;
+    return match[0];
+  }
+  literal() {
+    this.skip();
+    const rest = this.text.slice(this.index);
+    const string = /^(\[\[[\s\S]*?\]\]|'(?:\\.|[^'\\])*'|"(?:\\.|[^"\\])*")/.exec(rest);
+    if (string !== null) {
+      this.index += string[0].length;
+      return "string";
+    }
+    const number = /^-?(?:0[xX][0-9a-fA-F]+|\d+\.?\d*(?:[eE][-+]?\d+)?|\.\d+)/.exec(rest);
+    if (number !== null) {
+      this.index += number[0].length;
+      return "number";
+    }
+    const word = /^(true|false|nil)\b/.exec(rest);
+    if (word === null) {
+      return null;
+    }
+    this.index += word[0].length;
+    return word[0] === "nil" ? "nil" : "boolean";
+  }
+  key() {
+    this.skip();
+    if (this.take("[")) {
+      const rest = this.text.slice(this.index);
+      const quoted2 = /^'([A-Za-z_][A-Za-z0-9_]*)'|^"([A-Za-z_][A-Za-z0-9_]*)"/.exec(rest);
+      if (quoted2 === null) {
+        return null;
+      }
+      this.index += quoted2[0].length;
+      return this.take("]") && this.take("=") ? quoted2[1] ?? quoted2[2] ?? null : null;
+    }
+    const start = this.index;
+    const word = this.word();
+    if (word === null || !this.take("=") || this.peek() === "=") {
+      this.index = start;
+      return null;
+    }
+    return word;
+  }
+};
+
+// ../compiler/src/project/config-extractor.ts
+var GENERATED_MARKER = '# Generated by "luam config" from';
+var MAX_SOURCE_BYTES = 262144;
+var MAX_DEPTH2 = 8;
+var MAX_ENTRIES = 512;
+function renderRecord(fields) {
+  return `{ ${fields.map(([name, type]) => `${name}: ${type}`).join(", ")} }`;
+}
+function render(value) {
+  if (value.kind === "literal") {
+    return value.type === "nil" ? "any" : value.type;
+  }
+  if (value.kind === "array") {
+    return `${value.element}[]`;
+  }
+  return value.kind === "record" && value.fields.length > 0 ? renderRecord(value.fields) : "table";
+}
+function unify2(types) {
+  const unique = [...new Set(types)];
+  return unique.length === 1 ? unique[0] ?? "any" : "any";
+}
+function readTable2(reader, depth) {
+  if (depth > MAX_DEPTH2) {
+    return reader.fail(`A table nested deeper than ${MAX_DEPTH2} levels is not extracted.`);
+  }
+  const fields = [];
+  const elements = [];
+  for (let count = 0; ; count += 1) {
+    if (reader.take("}")) {
+      break;
+    }
+    if (count > MAX_ENTRIES) {
+      return reader.fail(`A table with more than ${MAX_ENTRIES} entries is not extracted.`);
+    }
+    const key = reader.key();
+    const value = readValue(reader, depth + 1);
+    if (value === null) {
+      return null;
+    }
+    if (key === null) {
+      elements.push(render(value));
+    } else {
+      fields.push([key, render(value)]);
+    }
+    if (!reader.take(",") && !reader.take(";") && reader.peek() !== "}") {
+      return reader.fail('Expected "," or "}" in a table.');
+    }
+  }
+  if (fields.length > 0 && elements.length > 0) {
+    return { kind: "table" };
+  }
+  return elements.length > 0 ? { kind: "array", element: unify2(elements) } : { kind: "record", fields };
+}
+function readValue(reader, depth) {
+  if (reader.take("{")) {
+    return readTable2(reader, depth);
+  }
+  const literal2 = reader.literal();
+  if (literal2 === null) {
+    return reader.fail("Only literals and table constructors are extracted. Declare this value by hand.");
+  }
+  if (reader.peek() === "." || reader.peek() === "(" || reader.peek() === "+") {
+    return reader.fail("An expression is not extracted. Declare this value by hand.");
+  }
+  return { kind: "literal", type: literal2 };
+}
+function extractConfigDeclarations(source) {
+  if (source.length > MAX_SOURCE_BYTES) {
+    return { declarations: [], problems: [{ line: 1, column: 1, message: `A file larger than ${MAX_SOURCE_BYTES} bytes is not extracted.` }] };
+  }
+  const reader = new Reader(source);
+  const declarations = /* @__PURE__ */ new Map();
+  while (!reader.done()) {
+    reader.take("local");
+    const name = reader.word();
+    if (name === null || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || !reader.take("=")) {
+      reader.fail("Only a top-level assignment of a literal or a table is extracted.");
+      break;
+    }
+    const value = readValue(reader, 1);
+    if (value === null) {
+      break;
+    }
+    declarations.set(name, render(value));
+    reader.take(";");
+  }
+  return { declarations: [...declarations].map(([name, type]) => ({ name, type })), problems: reader.problems };
+}
+function renderConfigDeclarations(source, declarations) {
+  const lines = declarations.map((declaration) => `declare ${declaration.name}: ${declaration.type}`);
+  return `${GENERATED_MARKER} "${source}". Do not edit.
+
+${lines.join("\n")}
+`;
+}
+function isGeneratedDeclaration(text) {
+  return text.startsWith(GENERATED_MARKER);
+}
+
+// src/commands/config-command.ts
+var DEFAULT_CONFIG_SOURCE = "config.lua";
+var DEFAULT_CONFIG_OUTPUT = "config.d.luam";
+function escapes(root, path) {
+  const inside = relative5(root, path);
+  return inside.startsWith("..") || resolve13(root, inside) !== path;
+}
+function readSource2(root, source, reporter) {
+  const path = resolve13(root, source);
+  if (escapes(root, path)) {
+    reporter.error(`Config declarations read only inside the project, but "${source}" points outside it.`);
+    return null;
+  }
+  if (!existsSync8(path)) {
+    reporter.error(`Config declarations found no file at "${source}".`);
+    return null;
+  }
+  try {
+    return readFileSync9(path, "utf8");
+  } catch {
+    reporter.error(`Config declarations could not read "${source}".`);
+    return null;
+  }
+}
+function writable(root, out, reporter) {
+  const path = resolve13(root, out);
+  if (escapes(root, path)) {
+    reporter.error(`Config declarations write only inside the project, but "${out}" points outside it.`);
+    return null;
+  }
+  if (existsSync8(path) && !isGeneratedDeclaration(readFileSync9(path, "utf8"))) {
+    reporter.error(`"${out}" was not generated by this command and was left alone. Choose another path with --out.`);
+    return null;
+  }
+  return path;
+}
+function runConfigCommand(root, reporter, options = {}) {
+  const source = options.source ?? DEFAULT_CONFIG_SOURCE;
+  const out = options.out ?? DEFAULT_CONFIG_OUTPUT;
+  const text = readSource2(root, source, reporter);
+  if (text === null) {
+    return EXIT_DIAGNOSTICS;
+  }
+  const extracted = extractConfigDeclarations(text);
+  for (const problem of extracted.problems) {
+    reporter.warn(`${source}:${problem.line}:${problem.column} ${problem.message}`);
+  }
+  if (extracted.declarations.length === 0) {
+    reporter.error(`Config declarations found nothing to declare in "${source}".`);
+    return EXIT_DIAGNOSTICS;
+  }
+  const rendered = renderConfigDeclarations(source, extracted.declarations);
+  if (options.write !== true) {
+    reporter.info(rendered.trimEnd());
+    reporter.info(`Config declarations would write ${extracted.declarations.length} name(s) to "${out}". Pass --write to save it.`);
+    return EXIT_OK;
+  }
+  const path = writable(root, out, reporter);
+  if (path === null) {
+    return EXIT_DIAGNOSTICS;
+  }
+  mkdirSync5(dirname5(path), { recursive: true });
+  writeFileSync6(path, rendered, "utf8");
+  reporter.info(`Config declarations wrote ${extracted.declarations.length} name(s) to "${out}".`);
+  return EXIT_OK;
+}
+
+// src/cli/registry/config-registration.ts
+function registerConfigCommand(program2, runtime) {
+  const command = program2.command("config").description('Derive a declaration file from the literal data in a native "config.lua".');
+  addProjectOptions(command).addOption(valueOption("--source <path>", 'Native Lua file to read. Defaults to "config.lua".')).addOption(valueOption("--out <path>", 'Declaration file to write. Defaults to "config.d.luam".')).addOption(new Option("--write", "Write the declaration file instead of printing it."));
+  command.action((options) => {
+    runtime.exitCode = runConfigCommand(commandRoot(runtime, options), runtime.reporter, {
+      source: options.source ?? null,
+      out: options.out ?? null,
+      write: options.write === true
+    });
+  });
+}
+
 // src/commands/ensure-runner.ts
 function hasChanges(result) {
   return result.written.length > 0 || result.removed.length > 0;
@@ -22006,7 +23541,7 @@ function restartResource(scope, serverConsole) {
   reporter.success(`Restarted "${scope.context.config.name}" through the owned server console.`);
   return true;
 }
-function failed(outcome) {
+function failed2(outcome) {
   return { ok: false, outcome, sync: null, restarted: false };
 }
 async function runOnce(scope, target, cache3, options) {
@@ -22029,7 +23564,7 @@ async function runOnce(scope, target, cache3, options) {
   if (outcome.build === null) {
     reportBuildOutcome(context, outcome, "Build");
     reporter.warn("Skipping sync and restart because the build reported errors.");
-    return failed(outcome);
+    return failed2(outcome);
   }
   const writeOptions = trackedWriteOptions(context.root, context.config, outcome.environmentTemplate, tracker);
   reportBuildOutcome(context, outcome, "Build");
@@ -22077,8 +23612,8 @@ function reportRebuildSeparator(reporter, at = /* @__PURE__ */ new Date()) {
 }
 
 // src/watch/source-watcher.ts
-import { existsSync as existsSync8, watch } from "node:fs";
-import { relative as relative5, resolve as resolve12 } from "node:path";
+import { existsSync as existsSync9, watch } from "node:fs";
+import { relative as relative6, resolve as resolve14 } from "node:path";
 var DEFAULT_DEBOUNCE_MS = 120;
 function watchSources(root, sources, onChange, debounceMs = DEFAULT_DEBOUNCE_MS) {
   const resolver = createSourceResolver(sources);
@@ -22094,12 +23629,12 @@ function watchSources(root, sources, onChange, debounceMs = DEFAULT_DEBOUNCE_MS)
     }, debounceMs);
   };
   const isWatched = (directory, filename) => {
-    const path = normalizePattern(relative5(root, resolve12(directory, filename)));
+    const path = normalizePattern(relative6(root, resolve14(directory, filename)));
     return path.endsWith(SOURCE_EXTENSION) && resolver.resolve(path).matches.length > 0;
   };
   for (const entry of resolver.roots) {
-    const absolute = resolve12(root, entry);
-    if (!existsSync8(absolute)) {
+    const absolute = resolve14(root, entry);
+    if (!existsSync9(absolute)) {
       continue;
     }
     watchers.push(
@@ -22292,26 +23827,26 @@ function parseMtaLogLine(line2, activeResource, fallback = /* @__PURE__ */ new D
     const level = severity?.[1] === void 0 ? "info" : logLevel(severity[1]) ?? "info";
     const message = stamped.rest.replace(resource[0], "").replace(severity?.[0] ?? "", "").replace(/^\s*[:|-]?\s*/, "");
     const sourcePath = resource[2];
-    const sourceLine = resource[3];
+    const sourceLine2 = resource[3];
     return {
       timestamp: stamped.value,
       environment: "server",
       level,
       message,
       resource: activeResource,
-      ...sourcePath !== void 0 && sourceLine !== void 0 ? { source: { path: sourcePath, line: Number(sourceLine) } } : {}
+      ...sourcePath !== void 0 && sourceLine2 !== void 0 ? { source: { path: sourcePath, line: Number(sourceLine2) } } : {}
     };
   }
   return { timestamp: stamped.value, environment: "server", level: "info", message: stamped.rest, resource: activeResource };
 }
 
 // src/logging/server-log-follower.ts
-import { closeSync, existsSync as existsSync9, openSync, readSync, statSync as statSync4 } from "node:fs";
-import { isAbsolute as isAbsolute6, resolve as resolve13 } from "node:path";
+import { closeSync, existsSync as existsSync10, openSync, readSync, statSync as statSync4 } from "node:fs";
+import { isAbsolute as isAbsolute6, resolve as resolve15 } from "node:path";
 var DEFAULT_POLL_INTERVAL_MS = 100;
 function resolveServerLogPath(root, serverPath) {
-  const server = isAbsolute6(serverPath) ? serverPath : resolve13(root, serverPath);
-  return resolve13(server, "mods/deathmatch/logs/server.log");
+  const server = isAbsolute6(serverPath) ? serverPath : resolve15(root, serverPath);
+  return resolve15(server, "mods/deathmatch/logs/server.log");
 }
 function identity(path) {
   const stats = statSync4(path);
@@ -22336,7 +23871,7 @@ function followServerLog(path, onLine, options = {}) {
   let initialized = false;
   let closed = false;
   const poll = () => {
-    if (closed || !existsSync9(path)) {
+    if (closed || !existsSync10(path)) {
       return;
     }
     try {
@@ -22452,9 +23987,9 @@ function connectServerConsoleInput(input, output, interrupt) {
 
 // src/server/server-executable-resolver.ts
 import { realpathSync, statSync as statSync5 } from "node:fs";
-import { isAbsolute as isAbsolute7, relative as relative6, resolve as resolve14 } from "node:path";
+import { isAbsolute as isAbsolute7, relative as relative7, resolve as resolve16 } from "node:path";
 function isInside(root, path) {
-  const pathFromRoot = relative6(root, path);
+  const pathFromRoot = relative7(root, path);
   return pathFromRoot.length === 0 || !pathFromRoot.startsWith("..") && !isAbsolute7(pathFromRoot);
 }
 function candidates2(platform) {
@@ -22467,14 +24002,14 @@ function candidates2(platform) {
   throw new Error(`Local MTA server startup is not supported on platform "${platform}". Use Windows or Linux.`);
 }
 function resolveServerExecutable(options) {
-  const serverRoot = resolve14(options.root, options.serverPath);
+  const serverRoot = resolve16(options.root, options.serverPath);
   const names = options.configured === null ? candidates2(options.platform ?? process.platform) : [options.configured];
   const attempted = [];
-  if (options.configured !== null && (isAbsolute7(options.configured) || !isInside(serverRoot, resolve14(serverRoot, options.configured)))) {
+  if (options.configured !== null && (isAbsolute7(options.configured) || !isInside(serverRoot, resolve16(serverRoot, options.configured)))) {
     throw new Error(`Configured development.server.executable must stay inside serverPath but received "${options.configured}".`);
   }
   for (const name of names) {
-    const path = resolve14(serverRoot, name);
+    const path = resolve16(serverRoot, name);
     attempted.push(path);
     try {
       if (!statSync5(path).isFile()) {
@@ -22744,9 +24279,52 @@ function registerDevCommand(program2, runtime) {
   });
 }
 
+// src/testing/lua-interpreter.ts
+import { spawnSync as spawnSync2 } from "node:child_process";
+var REQUIRED_LUA_VERSION = "Lua 5.1";
+var LUA_CANDIDATES = ["lua5.1", "lua51", "lua", "luajit"];
+var LUA_ENV_VARIABLE = "LUAM_LUA";
+var INSTALL_HINT = 'Install a Lua 5.1 interpreter and put it on PATH, or point "--lua" or the LUAM_LUA variable at one. LuaJIT reports "Lua 5.1" and is accepted.';
+function probeInterpreter(executable) {
+  const result = spawnSync2(executable, ["-e", "io.write(_VERSION)"], { encoding: "utf8", shell: false, windowsHide: true });
+  if (result.error !== void 0 || result.status !== 0) {
+    return null;
+  }
+  return result.stdout.trim();
+}
+function findLuaInterpreter(request = {}) {
+  const probe = request.probe ?? probeInterpreter;
+  const pinned = request.explicit ?? request.env ?? null;
+  const candidates3 = pinned === null ? LUA_CANDIDATES : [pinned];
+  for (const executable of candidates3) {
+    const version = probe(executable);
+    if (version === REQUIRED_LUA_VERSION) {
+      return { executable, version };
+    }
+  }
+  return null;
+}
+function describeMissingInterpreter(request = {}) {
+  const pinned = request.explicit ?? request.env ?? null;
+  if (pinned !== null) {
+    return `"${pinned}" is not a ${REQUIRED_LUA_VERSION} interpreter.`;
+  }
+  return `No ${REQUIRED_LUA_VERSION} interpreter was found on PATH (tried ${LUA_CANDIDATES.map((name) => `"${name}"`).join(", ")}).`;
+}
+
 // src/commands/doctor-command.ts
-function runDoctorCommand(reporter, editorService) {
+function reportInterpreter(reporter, probe) {
+  const interpreter = findLuaInterpreter(probe === void 0 ? {} : { probe });
+  if (interpreter === null) {
+    reporter.warn(`No ${REQUIRED_LUA_VERSION} interpreter was found on PATH, so "luam test" cannot run.`);
+    reporter.detail(INSTALL_HINT);
+    return;
+  }
+  reporter.success(`"${interpreter.executable}" reports ${interpreter.version} and can run "luam test".`);
+}
+function runDoctorCommand(reporter, editorService, probe) {
   reporter.success(`Luam CLI ${VERSION} is running on Node.js ${process.versions.node}.`);
+  reportInterpreter(reporter, probe);
   const editors = editorService.detect();
   if (editors.length === 0) {
     reporter.warn("No supported editor command was found on PATH.");
@@ -22792,7 +24370,7 @@ function registerEnsureCommand(program2, runtime) {
 }
 
 // src/cli/registry/init-registration.ts
-import { resolve as resolve16 } from "node:path";
+import { resolve as resolve18 } from "node:path";
 
 // src/commands/init-command.ts
 import { basename as basename2 } from "node:path";
@@ -22854,7 +24432,7 @@ function renderManifest(source, details) {
 }
 
 // src/scaffold/template-files.ts
-import { existsSync as existsSync10, readFileSync as readFileSync8 } from "node:fs";
+import { existsSync as existsSync11, readFileSync as readFileSync10 } from "node:fs";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // ../template/src/template.ts
@@ -22870,10 +24448,10 @@ function bundledTemplatePath(source) {
 }
 function resolveTemplatePath(source) {
   const packaged = fileURLToPath2(resolveTemplateUrl(source));
-  return existsSync10(packaged) ? packaged : bundledTemplatePath(source);
+  return existsSync11(packaged) ? packaged : bundledTemplatePath(source);
 }
 function readTemplateSource(source) {
-  return readFileSync8(resolveTemplatePath(source), "utf8");
+  return readFileSync10(resolveTemplatePath(source), "utf8");
 }
 
 // src/scaffold/scaffold-plan.ts
@@ -22889,19 +24467,19 @@ function buildScaffoldPlan(details) {
 }
 
 // src/scaffold/scaffold-writer.ts
-import { existsSync as existsSync11, mkdirSync as mkdirSync4, writeFileSync as writeFileSync5 } from "node:fs";
-import { dirname as dirname4, resolve as resolve15 } from "node:path";
+import { existsSync as existsSync12, mkdirSync as mkdirSync6, writeFileSync as writeFileSync7 } from "node:fs";
+import { dirname as dirname6, resolve as resolve17 } from "node:path";
 function writeScaffold(targetDir, plan, force) {
   const written = [];
   const skipped = [];
   for (const file of plan.files) {
-    const absolute = resolve15(targetDir, file.path);
-    if (!force && existsSync11(absolute)) {
+    const absolute = resolve17(targetDir, file.path);
+    if (!force && existsSync12(absolute)) {
       skipped.push(file.path);
       continue;
     }
-    mkdirSync4(dirname4(absolute), { recursive: true });
-    writeFileSync5(absolute, file.content, "utf8");
+    mkdirSync6(dirname6(absolute), { recursive: true });
+    writeFileSync7(absolute, file.content, "utf8");
     written.push(file.path);
   }
   return { written: written.sort((left, right) => left.localeCompare(right)), skipped: skipped.sort((left, right) => left.localeCompare(right)) };
@@ -22951,7 +24529,7 @@ function registerInitCommand(program2, runtime) {
   command.addOption(cwdOption()).addOption(valueOption("--name <name>", "Resource name. Defaults to the destination directory name.")).addOption(new Option("--force", "Overwrite files that already exist.")).addOption(new Option("-y, --yes", "Accept the defaults without prompting.")).addOption(colorOption());
   command.action(async (path, options) => {
     const root = commandRoot(runtime, options);
-    const target = path === void 0 ? root : resolve16(root, path);
+    const target = path === void 0 ? root : resolve18(root, path);
     runtime.exitCode = await runInitCommand(target, runtime.logger, {
       name: options.name ?? null,
       force: options.force === true,
@@ -22969,7 +24547,7 @@ async function runSetupCommand(reporter, options) {
     reporter.detail("Supported commands: code, code-insiders, cursor, codium, windsurf.");
     return EXIT_DIAGNOSTICS;
   }
-  let failed2 = false;
+  let failed3 = false;
   for (const editor of editors) {
     if (options.editorService.hasExtension(editor)) {
       reporter.success(`${editor.name}: Luam is already installed.`);
@@ -22988,12 +24566,12 @@ async function runSetupCommand(reporter, options) {
     const result = await options.editorService.install(editor);
     if (result.error !== null) {
       reporter.error(`${editor.name}: installation failed. ${result.error}`);
-      failed2 = true;
+      failed3 = true;
       continue;
     }
     reporter.success(`${editor.name}: installed from the ${result.source}.`);
   }
-  return failed2 ? EXIT_DIAGNOSTICS : EXIT_OK;
+  return failed3 ? EXIT_DIAGNOSTICS : EXIT_OK;
 }
 
 // src/editor/installation-prompt.ts
@@ -23074,13 +24652,640 @@ function registerServerCommand(program2, runtime) {
   });
 }
 
+// src/testing/test-report.ts
+import { readFileSync as readFileSync11 } from "node:fs";
+import { resolve as resolve19 } from "node:path";
+function sourceLine(root, path, line2, cache3) {
+  let lines = cache3.get(path);
+  if (lines === void 0) {
+    try {
+      lines = readFileSync11(resolve19(root, path), "utf8").split(/\r?\n/);
+    } catch {
+      lines = [];
+    }
+    cache3.set(path, lines);
+  }
+  return lines[line2 - 1] ?? null;
+}
+function columnOf(text, symbol) {
+  if (text === null) {
+    return 1;
+  }
+  const symbolIndex = symbol === void 0 ? -1 : text.indexOf(symbol);
+  if (symbolIndex >= 0) {
+    return symbolIndex + 1;
+  }
+  const indent = /^\s*/.exec(text)?.[0].length ?? 0;
+  return indent + 1;
+}
+function resolveTestPosition(root, map, result, cache3) {
+  if (map === null || result.file === null || result.line === null) {
+    return null;
+  }
+  const resolution = resolveResourcePosition(map, result.file, result.line);
+  if (resolution.status !== "resolved") {
+    return null;
+  }
+  const { file, line: line2, symbol } = resolution.position;
+  return { path: file, line: line2, column: columnOf(sourceLine(root, file, line2, cache3), symbol) };
+}
+function formatLocation(root, map, result, cache3) {
+  const position2 = resolveTestPosition(root, map, result, cache3);
+  if (position2 !== null) {
+    return `${position2.path}:${position2.line}:${position2.column}`;
+  }
+  return result.file === null || result.line === null ? "unknown position" : `${result.file}:${result.line}`;
+}
+function countResults(runs) {
+  const results = runs.flatMap((run) => run.results);
+  const passed = results.filter((result) => result.passed).length;
+  return { passed, failed: results.length - passed };
+}
+function reportTestResults(reporter, runs, root, map, durationMs) {
+  const cache3 = /* @__PURE__ */ new Map();
+  const marker = (name) => reporter.style.marker(name);
+  for (const run of runs) {
+    for (const line2 of run.output) {
+      reporter.detail(`  ${line2}`);
+    }
+    for (const result of run.results) {
+      const tone = result.passed ? "success" : "error";
+      const label2 = `${result.environment} \xB7 ${result.name}`;
+      reporter.raw(`  ${reporter.style.paint(tone, marker(result.passed ? "success" : "failure"))} ${label2}`);
+      if (!result.passed) {
+        reporter.rawError(`      ${formatLocation(root, map, result, cache3)} ${result.message}`);
+      }
+    }
+    if (run.failure !== null) {
+      reporter.error(`The ${run.environment} test run did not complete: ${run.failure}`);
+    }
+  }
+  const totals = countResults(runs);
+  const summary = `${pluralize(totals.passed, "test")} passed, ${totals.failed} failed in ${formatDuration(durationMs)}.`;
+  const crashed = runs.some((run) => run.failure !== null);
+  if (totals.failed === 0 && !crashed) {
+    reporter.success(`Tests passed: ${summary}`);
+    return true;
+  }
+  reporter.error(`Tests failed: ${summary}`);
+  return false;
+}
+
+// src/testing/test-discovery.ts
+import { readFileSync as readFileSync12 } from "node:fs";
+import { resolve as resolve20 } from "node:path";
+var DEFAULT_TEST_ENVIRONMENT = "shared";
+var SIDE_CONFLICT2 = "test-source-side-conflict";
+var UNREADABLE_TEST = "test-source-unreadable";
+function readTest(root, path, diagnostics) {
+  try {
+    return readFileSync12(resolve20(root, path), "utf8");
+  } catch (error) {
+    diagnostics.push(cliError(UNREADABLE_TEST, `The test file "${path}" could not be read: ${error instanceof Error ? error.message : String(error)}`));
+    return null;
+  }
+}
+function discoverTests(root, sources, excluded = []) {
+  const resolver = createSourceResolver(sources);
+  const tree = listProjectFiles(root, ["."], excluded);
+  const diagnostics = tree.errors.map((message) => cliError(UNREADABLE_TEST, message));
+  const files = [];
+  for (const path of tree.files.filter(isTestPath)) {
+    const resolution = resolver.resolve(path);
+    if (resolution.matches.length > 1) {
+      diagnostics.push(cliError(SIDE_CONFLICT2, `"${path}" is matched by more than one side: ${describeMatches(resolution.matches)}. Narrow the patterns.`));
+      continue;
+    }
+    const source = readTest(root, path, diagnostics);
+    if (source !== null) {
+      files.push({ path, source, environment: resolution.environment ?? DEFAULT_TEST_ENVIRONMENT });
+    }
+  }
+  return { files: files.sort((left, right) => left.path.localeCompare(right.path)), diagnostics };
+}
+
+// src/testing/test-runner.ts
+import { spawnSync as spawnSync3 } from "node:child_process";
+import { mkdirSync as mkdirSync7, mkdtempSync as mkdtempSync2, rmSync as rmSync2, writeFileSync as writeFileSync8 } from "node:fs";
+import { tmpdir as tmpdir2 } from "node:os";
+import { dirname as dirname7, join as join6 } from "node:path";
+
+// src/testing/harness-assertions.ts
+var ASSERTIONS_SOURCE = String.raw`local SENTINEL = '##luam:test'
+local HARNESS = debug.getinfo(1, 'S').short_src
+
+local tests = {}
+local groups = {}
+local beforeHooks = {}
+local afterHooks = {}
+local callLog = {}
+local behaviour = {}
+local stubNames = rawget(_G, '__luamTestNames') or {}
+
+local function escape(value)
+    local text = tostring(value)
+    text = text:gsub('\\', '\\\\')
+    text = text:gsub('\t', '\\t')
+    text = text:gsub('\r', '\\r')
+    text = text:gsub('\n', '\\n')
+    return text
+end
+
+local function emit(kind, ...)
+    local parts = { SENTINEL, kind }
+    for index = 1, select('#', ...) do
+        parts[#parts + 1] = escape(select(index, ...))
+    end
+    io.write(table.concat(parts, '\t'))
+    io.write('\n')
+    io.stdout:flush()
+end
+
+local function origin()
+    local index = 1
+    while true do
+        local info = debug.getinfo(index, 'Sl')
+        if info == nil then
+            return '', ''
+        end
+        if info.what ~= 'C' and info.short_src ~= HARNESS then
+            return info.short_src, info.currentline
+        end
+        index = index + 1
+    end
+end
+
+local function failure(message)
+    local file, line = origin()
+    return { luamTestFailure = true, message = message, file = file, line = line }
+end
+
+local function fail(message)
+    error(failure(message), 0)
+end
+
+local function handler(err)
+    if type(err) == 'table' and err.luamTestFailure then
+        return err
+    end
+    return failure(tostring(err))
+end
+
+local function attempt(body)
+    local ok, err = xpcall(body, handler)
+    if ok then
+        return nil
+    end
+    return err
+end
+
+local function describeValue(value)
+    if type(value) == 'string' then
+        return string.format('%q', value)
+    end
+    return tostring(value)
+end
+
+local function deepEqual(left, right)
+    if left == right then
+        return true
+    end
+    if type(left) ~= 'table' or type(right) ~= 'table' then
+        return false
+    end
+    for key, value in pairs(left) do
+        if not deepEqual(value, right[key]) then
+            return false
+        end
+    end
+    for key in pairs(right) do
+        if left[key] == nil then
+            return false
+        end
+    end
+    return true
+end
+
+local function expect(value)
+    local matchers = {}
+
+    function matchers.toBe(expected)
+        if value ~= expected then
+            fail('expected ' .. describeValue(expected) .. ', got ' .. describeValue(value))
+        end
+    end
+
+    function matchers.toNotBe(expected)
+        if value == expected then
+            fail('expected a value other than ' .. describeValue(expected))
+        end
+    end
+
+    function matchers.toEqual(expected)
+        if not deepEqual(value, expected) then
+            fail('expected ' .. describeValue(expected) .. ', got ' .. describeValue(value))
+        end
+    end
+
+    function matchers.toNotEqual(expected)
+        if deepEqual(value, expected) then
+            fail('expected a value other than ' .. describeValue(expected))
+        end
+    end
+
+    function matchers.toBeNil()
+        if value ~= nil then
+            fail('expected nil, got ' .. describeValue(value))
+        end
+    end
+
+    function matchers.toBeTruthy()
+        if not value then
+            fail('expected a truthy value, got ' .. describeValue(value))
+        end
+    end
+
+    function matchers.toBeFalsy()
+        if value then
+            fail('expected a falsy value, got ' .. describeValue(value))
+        end
+    end
+
+    function matchers.toContain(entry)
+        if type(value) == 'string' then
+            if string.find(value, tostring(entry), 1, true) == nil then
+                fail('expected ' .. describeValue(value) .. ' to contain ' .. describeValue(entry))
+            end
+            return
+        end
+        if type(value) ~= 'table' then
+            fail('expected a string or a table, got ' .. type(value))
+            return
+        end
+        for _, candidate in pairs(value) do
+            if deepEqual(candidate, entry) then
+                return
+            end
+        end
+        fail('expected the table to contain ' .. describeValue(entry))
+    end
+
+    function matchers.toThrow(message)
+        if type(value) ~= 'function' then
+            fail('expected a function, got ' .. type(value))
+            return
+        end
+        local ok, err = pcall(value)
+        if ok then
+            fail('expected the function to throw')
+            return
+        end
+        if message ~= nil and string.find(tostring(err), message, 1, true) == nil then
+            fail('expected the error to contain ' .. describeValue(message) .. ', got ' .. describeValue(tostring(err)))
+        end
+    end
+
+    return matchers
+end
+`;
+
+// src/testing/harness-runner.ts
+var RUNNER_SOURCE = String.raw`local function fullName(name)
+    if #groups == 0 then
+        return name
+    end
+    return table.concat(groups, ' > ') .. ' > ' .. name
+end
+
+local function snapshot(list)
+    local copy = {}
+    for index = 1, #list do
+        copy[index] = list[index]
+    end
+    return copy
+end
+
+local function describe(name, body)
+    groups[#groups + 1] = name
+    local beforeDepth = #beforeHooks
+    local afterDepth = #afterHooks
+    body()
+    for index = #beforeHooks, beforeDepth + 1, -1 do
+        beforeHooks[index] = nil
+    end
+    for index = #afterHooks, afterDepth + 1, -1 do
+        afterHooks[index] = nil
+    end
+    groups[#groups] = nil
+end
+
+local function test(name, body)
+    tests[#tests + 1] = { name = fullName(name), body = body, before = snapshot(beforeHooks), after = snapshot(afterHooks) }
+end
+
+local function beforeEach(body)
+    beforeHooks[#beforeHooks + 1] = body
+end
+
+local function afterEach(body)
+    afterHooks[#afterHooks + 1] = body
+end
+
+local function resetStubs()
+    callLog = {}
+    behaviour = {}
+end
+
+local function record(name, ...)
+    local entries = callLog[name]
+    if entries == nil then
+        entries = {}
+        callLog[name] = entries
+    end
+    entries[#entries + 1] = { n = select('#', ...), ... }
+end
+
+local function makeStub(name)
+    return function(...)
+        record(name, ...)
+        local configured = behaviour[name]
+        if configured == nil then
+            return nil
+        end
+        if configured.kind == 'function' then
+            return configured.body(...)
+        end
+        return configured.value
+    end
+end
+
+local mta = {}
+
+function mta.stub(name, implementation)
+    behaviour[name] = { kind = 'function', body = implementation }
+end
+
+function mta.returns(name, value)
+    behaviour[name] = { kind = 'value', value = value }
+end
+
+function mta.calls(name)
+    return callLog[name] or {}
+end
+
+function mta.reset()
+    resetStubs()
+end
+
+local function runAll()
+    local passed = 0
+    local failed = 0
+    for _, entry in ipairs(tests) do
+        resetStubs()
+        local result = nil
+        for _, hook in ipairs(entry.before) do
+            if result == nil then
+                result = attempt(hook)
+            end
+        end
+        if result == nil then
+            result = attempt(entry.body)
+        end
+        for _, hook in ipairs(entry.after) do
+            local hookResult = attempt(hook)
+            if result == nil then
+                result = hookResult
+            end
+        end
+        if result == nil then
+            passed = passed + 1
+            emit('pass', entry.name)
+        else
+            failed = failed + 1
+            emit('fail', entry.name, result.file, result.line, result.message)
+        end
+    end
+    emit('done', passed, failed)
+    return failed
+end
+
+rawset(_G, 'describe', describe)
+rawset(_G, 'test', test)
+rawset(_G, 'beforeEach', beforeEach)
+rawset(_G, 'afterEach', afterEach)
+rawset(_G, 'expect', expect)
+rawset(_G, 'mta', mta)
+
+setmetatable(_G, {
+    __index = function(_, key)
+        if stubNames[key] == nil then
+            return nil
+        end
+        local stub = makeStub(key)
+        rawset(_G, key, stub)
+        return stub
+    end,
+})
+
+rawset(_G, '__luamTest', {
+    discard = function()
+        tests = {}
+        groups = {}
+        beforeHooks = {}
+        afterHooks = {}
+    end,
+    run = runAll,
+})
+`;
+
+// src/testing/harness-source.ts
+var HARNESS_FILE = "harness.lua";
+var ENTRY_PREFIX = "main-";
+var SENTINEL = "##luam:test";
+var HARNESS_SOURCE = `${ASSERTIONS_SOURCE}
+${RUNNER_SOURCE}`;
+function entryFile(environment) {
+  return `${ENTRY_PREFIX}${environment}.lua`;
+}
+function stubbedGlobals(environment) {
+  return globalsFor(environment).filter((declaration) => declaration.source === "mta" && declaration.type.kind === "function").map((declaration) => declaration.name).sort();
+}
+function entrySource(environment, preload, target) {
+  const names = stubbedGlobals(environment).map((name) => `    ['${name}'] = true,`);
+  const discard = preload.length === 0 ? [] : ["__luamTest.discard()"];
+  const lines = [
+    "__luamTestNames = {",
+    ...names,
+    "}",
+    `dofile('${HARNESS_FILE}')`,
+    ...preload.map((path) => `dofile('${path}')`),
+    ...discard,
+    ...target.map((path) => `dofile('${path}')`),
+    "local failed = __luamTest.run()",
+    "os.exit(failed == 0 and 0 or 1)"
+  ];
+  return `${lines.join("\n")}
+`;
+}
+
+// src/testing/test-runner.ts
+function runLua(executable, args, cwd) {
+  const result = spawnSync3(executable, [...args], { cwd, encoding: "utf8", shell: false, windowsHide: true });
+  return {
+    status: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    failure: result.error === void 0 ? null : result.error.message
+  };
+}
+function unescape(value) {
+  return value.replace(/\\(.)/g, (match, character) => {
+    if (character === "n") {
+      return "\n";
+    }
+    if (character === "r") {
+      return "\r";
+    }
+    return character === "t" ? "	" : character;
+  });
+}
+function parseLine(environment, line2) {
+  const parts = line2.split("	");
+  if (parts[0] !== SENTINEL || parts[1] !== "pass" && parts[1] !== "fail") {
+    return null;
+  }
+  const passed = parts[1] === "pass";
+  const file = unescape(parts[3] ?? "");
+  const parsedLine = Number(parts[4] ?? "");
+  return {
+    environment,
+    name: unescape(parts[2] ?? ""),
+    passed,
+    file: file.length === 0 ? null : file,
+    line: Number.isSafeInteger(parsedLine) && parsedLine > 0 ? parsedLine : null,
+    message: unescape(parts[5] ?? "")
+  };
+}
+function parseRunOutput(environment, stdout) {
+  const results = [];
+  const output = [];
+  for (const line2 of stdout.split(/\r?\n/)) {
+    const result = parseLine(environment, line2);
+    if (result !== null) {
+      results.push(result);
+      continue;
+    }
+    if (line2.startsWith(SENTINEL) || line2.length === 0) {
+      continue;
+    }
+    output.push(line2);
+  }
+  return { results, output };
+}
+function writeWorkspace(directory, scripts) {
+  writeFileSync8(join6(directory, HARNESS_FILE), HARNESS_SOURCE, "utf8");
+  for (const script of scripts) {
+    const target = join6(directory, script.path);
+    mkdirSync7(dirname7(target), { recursive: true });
+    writeFileSync8(target, script.content, "utf8");
+  }
+}
+function loadOrder(available, environment) {
+  const shared = bundlePath("shared");
+  const own = bundlePath(environment);
+  const target = available.has(own) ? [own] : [];
+  if (environment === "shared") {
+    return { preload: [], target };
+  }
+  return { preload: available.has(shared) ? [shared] : [], target };
+}
+function runTests(request) {
+  const spawn2 = request.spawn ?? runLua;
+  const directory = mkdtempSync2(join6(tmpdir2(), "luam-test-"));
+  const available = new Set(request.scripts.map((script) => script.path));
+  try {
+    writeWorkspace(directory, request.scripts);
+    return ALL_ENVIRONMENTS.filter((environment) => request.environments.includes(environment)).map((environment) => {
+      const { preload, target } = loadOrder(available, environment);
+      const entry = entryFile(environment);
+      writeFileSync8(join6(directory, entry), entrySource(environment, preload, target), "utf8");
+      const execution = spawn2(request.executable, [entry], directory);
+      const parsed = parseRunOutput(environment, execution.stdout);
+      const failure3 = execution.failure ?? (parsed.results.length === 0 && execution.stderr.length > 0 ? execution.stderr.trim() : null);
+      return { environment, results: parsed.results, output: parsed.output, failure: failure3 };
+    });
+  } finally {
+    rmSync2(directory, { recursive: true, force: true });
+  }
+}
+
+// src/commands/test-command.ts
+function testEnvironments(build, paths) {
+  const found = build.bundles.flatMap(
+    (bundle) => bundle.members.flatMap((member) => member.kind === "module" && paths.has(member.module.source) ? [member.module.environment] : [])
+  );
+  return [...new Set(found)];
+}
+function runTestCommand(context, options = {}) {
+  const reporter = commandReporter(context);
+  const excluded = [context.config.outDir, context.config.contracts];
+  const discovered = discoverTests(context.root, context.config.sources, excluded);
+  reportCliDiagnostics(reporter, discovered.diagnostics);
+  if (hasCliErrors(discovered.diagnostics)) {
+    return EXIT_DIAGNOSTICS;
+  }
+  if (discovered.files.length === 0) {
+    reporter.warn(`No "${TEST_EXTENSION}" files were found. Write one next to the module it covers.`);
+    return EXIT_OK;
+  }
+  const request = { explicit: options.lua ?? null, env: options.env ?? null, ...options.probe === void 0 ? {} : { probe: options.probe } };
+  const interpreter = findLuaInterpreter(request);
+  if (interpreter === null) {
+    reporter.error(describeMissingInterpreter(request));
+    reporter.detail(INSTALL_HINT);
+    return EXIT_USAGE;
+  }
+  const started = performance.now();
+  const outcome = runCompile(context.root, context.config, { additionalFiles: discovered.files, development: true, layout: "bundle", map: true });
+  reportCliDiagnostics(reporter, outcome.diagnostics);
+  reportFileDiagnostics(reporter, outcome.fileDiagnostics, outcome.sources);
+  if (outcome.build === null) {
+    reporter.error("Tests failed: the project did not compile.");
+    return EXIT_DIAGNOSTICS;
+  }
+  const paths = new Set(discovered.files.map((file) => file.path));
+  const environments = testEnvironments(outcome.build, paths);
+  const runs = runTests({
+    executable: interpreter.executable,
+    scripts: outcome.build.scripts,
+    environments,
+    ...options.spawn === void 0 ? {} : { spawn: options.spawn }
+  });
+  return reportTestResults(reporter, runs, context.root, outcome.map, performance.now() - started) ? EXIT_OK : EXIT_DIAGNOSTICS;
+}
+
+// src/cli/registry/test-registration.ts
+function registerTestCommand(program2, runtime) {
+  const command = program2.command("test").description("Compile the project with its test files and run them on a Lua 5.1 interpreter.");
+  addProjectOptions(command);
+  command.option("--lua <path>", "Path to the Lua 5.1 interpreter that runs the tests.");
+  command.action((options) => {
+    const project = createProjectContext(runtime, "test", options);
+    if (project.context === null) {
+      runtime.exitCode = project.error;
+      return;
+    }
+    runtime.exitCode = runTestCommand(project.context, { lua: options.lua ?? null, env: runtime.env[LUA_ENV_VARIABLE] ?? null });
+  });
+}
+
 // src/commands/trace-command.ts
-import { existsSync as existsSync12, readFileSync as readFileSync9 } from "node:fs";
+import { existsSync as existsSync13, readFileSync as readFileSync13 } from "node:fs";
 function defaultMapPath(root, options, reporter) {
   const loaded = loadManifest(root, { path: options.manifestPath, mode: manifestMode("trace"), env: options.env });
   if (loaded.config !== null) {
     const configured = resourceMapPath(root, loaded.config);
-    if (existsSync12(configured)) {
+    if (existsSync13(configured)) {
       return configured;
     }
   }
@@ -23100,7 +25305,7 @@ function readStandardInput() {
     return "";
   }
   try {
-    return readFileSync9(0, "utf8");
+    return readFileSync13(0, "utf8");
   } catch {
     return "";
   }
@@ -23134,30 +25339,30 @@ function runTraceCommand(root, reporter, options) {
     reporter.detail('A generated line cannot be resolved there. Reproduce the error under "luam dev" or "luam ensure" for a source position.');
     return EXIT_DIAGNOSTICS;
   }
-  let failed2 = false;
+  let failed3 = false;
   for (const line2 of lines) {
     const generated = parseTracePosition(line2);
     if (generated === null) {
       reporter.error(`Trace could not find a file and line in "${line2}".`);
-      failed2 = true;
+      failed3 = true;
       continue;
     }
     const file = generatedFile(loaded.map.resource, generated.file);
     const resolution = resolveResourcePosition(loaded.map, file, generated.line);
     if (resolution.status === "unknown-version") {
       reporter.error(`Resource map version ${resolution.version} is not supported.`);
-      failed2 = true;
+      failed3 = true;
       continue;
     }
     if (resolution.status === "uncovered") {
       reporter.error(`Resource map does not cover "${generated.file}:${generated.line}".`);
-      failed2 = true;
+      failed3 = true;
       continue;
     }
     const symbol = resolution.position.symbol === void 0 ? "" : ` (${resolution.position.symbol})`;
     reporter.raw(`${resolution.position.file}:${resolution.position.line}${symbol}`);
   }
-  return failed2 ? EXIT_DIAGNOSTICS : EXIT_OK;
+  return failed3 ? EXIT_DIAGNOSTICS : EXIT_OK;
 }
 
 // src/cli/registry/trace-registration.ts
@@ -23178,12 +25383,14 @@ function registerTraceCommand(program2, runtime) {
 var COMMAND_REGISTRARS = [
   registerBuildCommand,
   registerCheckCommand,
+  registerConfigCommand,
   registerDevCommand,
   registerDoctorCommand,
   registerEnsureCommand,
   registerInitCommand,
   registerServerCommand,
   registerSetupCommand,
+  registerTestCommand,
   registerTraceCommand
 ];