semantifold 0.12.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/README.md +2 -0
  2. package/build/src/backends/effects.js +5 -2
  3. package/build/src/backends/java.js +33 -14
  4. package/build/src/backends/javascript.js +83 -18
  5. package/build/src/backends/php.d.ts.map +1 -1
  6. package/build/src/backends/php.js +88 -16
  7. package/build/src/backends/ruby.js +37 -12
  8. package/build/src/backends/scalars.js +2 -2
  9. package/build/src/backends/shared.d.ts +2 -1
  10. package/build/src/backends/shared.d.ts.map +1 -1
  11. package/build/src/backends/shared.js +299 -42
  12. package/build/src/backends/typescript.js +83 -18
  13. package/build/src/backends/writer.d.ts +18 -4
  14. package/build/src/backends/writer.d.ts.map +1 -1
  15. package/build/src/backends/writer.js +40 -4
  16. package/build/src/frontends/java.d.ts +9 -1
  17. package/build/src/frontends/java.d.ts.map +1 -1
  18. package/build/src/frontends/java.js +90 -43
  19. package/build/src/frontends/javascript-typescript.d.ts +3 -1
  20. package/build/src/frontends/javascript-typescript.d.ts.map +1 -1
  21. package/build/src/frontends/javascript-typescript.js +133 -52
  22. package/build/src/frontends/php.d.ts +13 -1
  23. package/build/src/frontends/php.d.ts.map +1 -1
  24. package/build/src/frontends/php.js +226 -59
  25. package/build/src/frontends/ruby.d.ts +4 -1
  26. package/build/src/frontends/ruby.d.ts.map +1 -1
  27. package/build/src/frontends/ruby.js +113 -37
  28. package/build/src/frontends/types.d.ts +9 -2
  29. package/build/src/frontends/types.d.ts.map +1 -1
  30. package/build/src/frontends/types.js +26 -9
  31. package/build/src/language-registry.d.ts.map +1 -1
  32. package/build/src/language-registry.js +14 -6
  33. package/build/src/mapping.d.ts.map +1 -1
  34. package/build/src/mapping.js +4 -2
  35. package/build/src/semantic/effects.d.ts.map +1 -1
  36. package/build/src/semantic/effects.js +20 -6
  37. package/build/src/semantic/lifetime.js +28 -4
  38. package/build/src/semantic/provenance.d.ts.map +1 -1
  39. package/build/src/semantic/provenance.js +61 -9
  40. package/build/src/semantic/types.d.ts +214 -23
  41. package/build/src/semantic/types.d.ts.map +1 -1
  42. package/build/src/semantic/types.js +58 -11
  43. package/build/src/semantic/validate.d.ts +31 -2
  44. package/build/src/semantic/validate.d.ts.map +1 -1
  45. package/build/src/semantic/validate.js +450 -60
  46. package/docs/adr/20261026-typed-error-handling-extension.md +55 -0
  47. package/docs/adr-bounded-subtyping.md +180 -0
  48. package/docs/adr-numeric-tower.md +156 -0
  49. package/docs/architecture.md +1 -1
  50. package/docs/language-support.md +8 -8
  51. package/docs/testing.md +5 -3
  52. package/package.json +1 -1
  53. package/src/backends/effects.js +3 -1
  54. package/src/backends/java.js +33 -14
  55. package/src/backends/javascript.js +83 -18
  56. package/src/backends/php.js +89 -16
  57. package/src/backends/ruby.js +36 -12
  58. package/src/backends/scalars.js +1 -1
  59. package/src/backends/shared.js +298 -47
  60. package/src/backends/typescript.js +83 -18
  61. package/src/backends/writer.js +41 -3
  62. package/src/frontends/java.js +95 -43
  63. package/src/frontends/javascript-typescript.js +145 -53
  64. package/src/frontends/php.js +243 -58
  65. package/src/frontends/ruby.js +117 -35
  66. package/src/frontends/types.js +26 -8
  67. package/src/language-registry.js +13 -5
  68. package/src/mapping.js +3 -1
  69. package/src/semantic/effects.js +18 -5
  70. package/src/semantic/lifetime.js +29 -3
  71. package/src/semantic/provenance.js +60 -14
  72. package/src/semantic/types.js +62 -10
  73. package/src/semantic/validate.js +481 -61
@@ -492,6 +492,7 @@ export function semanticEntries(module) {
492
492
  node.imports.forEach((child, index) => visit(child, `/imports/${index}`, location))
493
493
  }
494
494
  ;(node.records ?? []).forEach((child, index) => visit(child, `/records/${index}`, location))
495
+ ;(node.interfaces ?? []).forEach((child, index) => visit(child, `/interfaces/${index}`, location))
495
496
  if (!("sourceFilename" in node) || Reflect.get(node, "stdlibFacade") !== undefined) {
496
497
  ;(node.classes ?? []).forEach((child, index) => visit(child, `/classes/${index}`, location))
497
498
  }
@@ -512,7 +513,14 @@ export function semanticEntries(module) {
512
513
  } else if (node.kind == "EffectOperationDeclaration") {
513
514
  node.parameters.forEach((child, index) => visit(child.type, `${path}/parameters/${index}/type`, location))
514
515
  visit(node.returnType, `${path}/returnType`, location)
516
+ } else if (node.kind == "InterfaceDeclaration") {
517
+ (node.extends ?? []).forEach((child, index) => visit(child, `${path}/extends/${index}`, location))
518
+ node.methods.forEach((child, index) => visit(child, `${path}/methods/${index}`, location))
519
+ } else if (node.kind == "InterfaceMethodDeclaration") {
520
+ node.parameters.forEach((child, index) => visit(child.type, `${path}/parameters/${index}/type`, location))
521
+ visit(node.returnType, `${path}/returnType`, location)
515
522
  } else if (node.kind == "ClassDeclaration") {
523
+ (node.implements ?? []).forEach((child, index) => visit(child, `${path}/implements/${index}`, location))
516
524
  node.fields.forEach((child, index) => visit(child, `${path}/fields/${index}`, location))
517
525
  visit(node.constructor, `${path}/constructor`, location)
518
526
  node.methods.forEach((child, index) => visit(child, `${path}/methods/${index}`, location))
@@ -580,8 +588,14 @@ export function semanticEntries(module) {
580
588
  visit(node.body, `${path}/body`, location)
581
589
  } else if (node.kind == "RaiseStatement") {
582
590
  visit(node.error, `${path}/error`, location)
591
+ } else if (node.kind == "RethrowStatement") {
592
+ visit(node.bindingNode, `${path}/bindingNode`, location)
593
+ visit(node.bindingNode, `${path}/bindingNode/name`, location)
583
594
  } else if (node.kind == "TryStatement") {
584
595
  visit(node.body, `${path}/body`, location)
596
+ node.handlers.forEach((child, index) => visit(child, `${path}/handlers/${index}`, location))
597
+ if (node.finallyBody) visit(node.finallyBody, `${path}/finallyBody`, location)
598
+ } else if (node.kind == "CatchHandler") {
585
599
  visit(node.catchType, `${path}/catchType`, location)
586
600
  visit(node.catchBinding, `${path}/catchBinding`, location)
587
601
  visit(node.catchBody, `${path}/catchBody`, location)
@@ -659,6 +673,10 @@ function resolveSymbols(module, records) {
659
673
  /** @type {Map<string, string>} */
660
674
  const fieldSymbols = new Map()
661
675
  /** @type {Map<string, string>} */
676
+ const interfaceSymbols = new Map()
677
+ /** @type {Map<string, string>} */
678
+ const interfaceMethodSymbols = new Map()
679
+ /** @type {Map<string, string>} */
662
680
  const classSymbols = new Map()
663
681
  /** @type {Map<string, string>} */
664
682
  const constructorSymbols = new Map()
@@ -718,11 +736,29 @@ function resolveSymbols(module, records) {
718
736
  if (declaration.id) errorSymbols.set(declaration.id, symbol)
719
737
  }
720
738
 
739
+ for (const [index, declaration] of (module.interfaces ?? []).entries()) {
740
+ const declarationPath = `/interfaces/${index}`
741
+ const interfaceSymbol = declare(declaration, declaration.name, "interface", declarationPath)
742
+
743
+ if (declaration.id) interfaceSymbols.set(declaration.id, interfaceSymbol)
744
+ for (const [extendsIndex, parent] of (declaration.extends ?? []).entries()) {
745
+ visitType(parent, `${declarationPath}/extends/${extendsIndex}`)
746
+ }
747
+ for (const [methodIndex, method] of declaration.methods.entries()) {
748
+ const symbol = declare(method, method.name, "interfaceMethod", `${declarationPath}/methods/${methodIndex}`)
749
+
750
+ if (method.id) interfaceMethodSymbols.set(method.id, symbol)
751
+ }
752
+ }
753
+
721
754
  for (const [index, declaration] of (module.classes ?? []).entries()) {
722
755
  const declarationPath = `/classes/${index}`
723
756
  const classSymbol = declare(declaration, declaration.name, "class", declarationPath)
724
757
 
725
758
  if (declaration.id) classSymbols.set(declaration.id, classSymbol)
759
+ for (const [implementsIndex, implemented] of (declaration.implements ?? []).entries()) {
760
+ visitType(implemented, `${declarationPath}/implements/${implementsIndex}`)
761
+ }
726
762
  for (const [fieldIndex, field] of declaration.fields.entries()) {
727
763
  const symbol = declare(field, field.name, "field", `${declarationPath}/fields/${fieldIndex}`)
728
764
 
@@ -800,7 +836,7 @@ function resolveSymbols(module, records) {
800
836
 
801
837
  /**
802
838
  * Declares one canonical symbol.
803
- * @param {import("./types.js").EffectCapabilityDeclaration | import("./types.js").EffectResourceDeclaration | import("./types.js").EffectFailureDeclaration | import("./types.js").EffectOperationDeclaration | import("./types.js").RecordDeclaration | import("./types.js").ClassDeclaration | import("./types.js").ErrorDeclaration | import("./types.js").RecordField | import("./types.js").PrivateField | import("./types.js").ConstructorDeclaration | import("./types.js").MethodDeclaration | import("./types.js").FunctionDeclaration | import("./types.js").TypeParameter | import("./types.js").Parameter | import("./types.js").LocalDeclaration | import("./types.js").ValueBinding | import("./types.js").CatchBinding} node - Declaration.
839
+ * @param {import("./types.js").EffectCapabilityDeclaration | import("./types.js").EffectResourceDeclaration | import("./types.js").EffectFailureDeclaration | import("./types.js").EffectOperationDeclaration | import("./types.js").RecordDeclaration | import("./types.js").ClassDeclaration | import("./types.js").InterfaceDeclaration | import("./types.js").InterfaceMethodDeclaration | import("./types.js").ErrorDeclaration | import("./types.js").RecordField | import("./types.js").PrivateField | import("./types.js").ConstructorDeclaration | import("./types.js").MethodDeclaration | import("./types.js").FunctionDeclaration | import("./types.js").TypeParameter | import("./types.js").Parameter | import("./types.js").LocalDeclaration | import("./types.js").ValueBinding | import("./types.js").CatchBinding} node - Declaration.
804
840
  * @param {string} name - Symbol name.
805
841
  * @param {import("./types.js").SemanticSymbolKind} kind - Symbol kind.
806
842
  * @param {string} path - Declaration occurrence path.
@@ -822,7 +858,7 @@ function resolveSymbols(module, records) {
822
858
  location,
823
859
  name,
824
860
  references: [],
825
- ...(["capability", "resource", "failure", "operation", "record", "class", "error", "field", "constructor", "method", "function", "typeParameter"].includes(kind)
861
+ ...(["capability", "resource", "failure", "operation", "record", "interface", "interfaceMethod", "class", "error", "field", "constructor", "method", "function", "typeParameter"].includes(kind)
826
862
  ? {semanticDeclarationId: /** @type {{id?: string}} */ (node).id}
827
863
  : {})
828
864
  })
@@ -895,19 +931,28 @@ function resolveSymbols(module, records) {
895
931
  visitType(statement.error.error, `${statementPath}/error/error`)
896
932
  reference(statement.error, errorSymbols.get(statement.error.error.declarationId), "construct", `${statementPath}/error`)
897
933
  visitExpression(statement.error.message, scope, `${statementPath}/error/message`)
934
+ } else if (statement.kind == "RethrowStatement") {
935
+ const symbol = scope.get(statement.binding)
936
+
937
+ if (symbol) reference(statement, symbol, "read", statementPath)
898
938
  } else if (statement.kind == "TryStatement") {
899
939
  visitBlock(statement.body, scope, `${statementPath}/body`)
900
- visitType(statement.catchType, `${statementPath}/catchType`)
901
- visitType(statement.catchBinding.type, `${statementPath}/catchBinding/type`)
902
- const catchScope = new Map(scope)
903
-
904
- catchScope.set(statement.catchBinding.name, declare(
905
- statement.catchBinding,
906
- statement.catchBinding.name,
907
- "catch",
908
- `${statementPath}/catchBinding`
909
- ))
910
- visitBlock(statement.catchBody, catchScope, `${statementPath}/catchBody`)
940
+ for (const [index, handler] of statement.handlers.entries()) {
941
+ const handlerPath = `${statementPath}/handlers/${index}`
942
+
943
+ visitType(handler.catchType, `${handlerPath}/catchType`)
944
+ visitType(handler.catchBinding.type, `${handlerPath}/catchBinding/type`)
945
+ const catchScope = new Map(scope)
946
+
947
+ catchScope.set(handler.catchBinding.name, declare(
948
+ handler.catchBinding,
949
+ handler.catchBinding.name,
950
+ "catch",
951
+ `${handlerPath}/catchBinding`
952
+ ))
953
+ visitBlock(handler.catchBody, catchScope, `${handlerPath}/catchBody`)
954
+ }
955
+ if (statement.finallyBody) visitBlock(statement.finallyBody, scope, `${statementPath}/finallyBody`)
911
956
  }
912
957
  }
913
958
  }
@@ -994,6 +1039,7 @@ function resolveSymbols(module, records) {
994
1039
  for (const [index, argument] of (type.arguments ?? []).entries()) visitType(argument, `${path}/arguments/${index}`)
995
1040
  }
996
1041
  else if (type.kind == "ErrorType") reference(type, errorSymbols.get(type.declarationId), "type", path)
1042
+ else if (type.kind == "InterfaceType") reference(type, interfaceSymbols.get(type.declarationId), "type", path)
997
1043
  else if (type.kind == "ReferenceType" || type.kind == "OwnedReferenceType") reference(type, classSymbols.get(type.declarationId), "type", path)
998
1044
  else if (type.kind == "OwnedResourceType") reference(type, resourceSymbols.get(type.resourceId), "type", path)
999
1045
  else if (type.kind == "ListType") visitType(type.elementType, `${path}/elementType`)
@@ -1005,7 +1051,7 @@ function resolveSymbols(module, records) {
1005
1051
 
1006
1052
  /**
1007
1053
  * Attaches one resolved symbol reference.
1008
- * @param {import("./types.js").IdentifierExpression | import("./types.js").ReceiverExpression | import("./types.js").CallExpression | import("./types.js").EffectCallExpression | import("./types.js").MethodCallExpression | import("./types.js").TypeVariableReference | import("./types.js").RecordType | import("./types.js").ReferenceType | import("./types.js").OwnedReferenceType | import("./types.js").OwnedResourceType | import("./types.js").RecordConstruction | import("./types.js").ReferenceConstruction | import("./types.js").MemberRead | import("./types.js").PrivateFieldRead | import("./types.js").PrivateFieldWriteStatement | import("./types.js").ErrorType | import("./types.js").ErrorConstruction} node - Reference node.
1054
+ * @param {import("./types.js").IdentifierExpression | import("./types.js").ReceiverExpression | import("./types.js").CallExpression | import("./types.js").EffectCallExpression | import("./types.js").MethodCallExpression | import("./types.js").TypeVariableReference | import("./types.js").RecordType | import("./types.js").ReferenceType | import("./types.js").InterfaceType | import("./types.js").OwnedReferenceType | import("./types.js").OwnedResourceType | import("./types.js").RecordConstruction | import("./types.js").ReferenceConstruction | import("./types.js").MemberRead | import("./types.js").PrivateFieldRead | import("./types.js").PrivateFieldWriteStatement | import("./types.js").RethrowStatement | import("./types.js").ErrorType | import("./types.js").ErrorConstruction} node - Reference node.
1009
1055
  * @param {string | undefined} symbolId - Resolved symbol.
1010
1056
  * @param {"type" | "construct" | "member" | "read" | "write" | "call"} role - Reference role.
1011
1057
  * @param {string} path - Reference occurrence path.
@@ -8,8 +8,8 @@
8
8
  /** @typedef {SemanticTypeName | "void"} FunctionReturnTypeName */
9
9
  /** @typedef {"IntegerNegate" | "BooleanNot"} SemanticUnaryOperation */
10
10
  /** @typedef {"IntegerAdd" | "IntegerSubtract" | "IntegerMultiply" | "BooleanAnd" | "BooleanOr" | "IntegerEqual" | "IntegerNotEqual" | "BooleanEqual" | "BooleanNotEqual" | "StringEqual" | "StringNotEqual" | "IntegerLessThan" | "IntegerLessThanOrEqual" | "IntegerGreaterThan" | "IntegerGreaterThanOrEqual" | "StringConcat"} SemanticBinaryOperation */
11
- /** @typedef {"capability" | "resource" | "failure" | "operation" | "record" | "class" | "error" | "field" | "constructor" | "method" | "function" | "typeParameter" | "parameter" | "local" | "iteration" | "catch"} SemanticSymbolKind */
12
- /** @typedef {"record" | "class" | "error" | "function"} SemanticDeclarationKind */
11
+ /** @typedef {"capability" | "resource" | "failure" | "operation" | "record" | "interface" | "interfaceMethod" | "class" | "error" | "field" | "constructor" | "method" | "function" | "typeParameter" | "parameter" | "local" | "iteration" | "catch"} SemanticSymbolKind */
12
+ /** @typedef {"record" | "interface" | "class" | "error" | "function"} SemanticDeclarationKind */
13
13
  /** @typedef {"declaration" | "type" | "construct" | "member" | "read" | "write" | "call"} SemanticSymbolRole */
14
14
  /** @typedef {"parse" | "generate" | "restore" | "compile" | "link" | "validate" | "instantiate" | "execute"} AcceptanceStage */
15
15
  /** @typedef {"entry" | "source" | "manifest" | "support" | "mapping" | "resource" | "loader"} GeneratedArtifactRole */
@@ -186,6 +186,7 @@
186
186
  * @property {boolean} typedErrors - Task 011 nominal unchecked errors, raises, and exact typed catches.
187
187
  * @property {boolean} typeParametersAndGenerics - Task 012 invariant unbounded type parameters and closed generic applications.
188
188
  * @property {boolean} referenceClasses - Task 033 nominal reference classes, private instance state, exact constructors, and receiver methods.
189
+ * @property {boolean} boundedSubtyping - Task 048 nominal interfaces with exact implementation contracts and implicit upcast (requires referenceClasses).
189
190
  * @property {boolean} effectfulCapabilitiesAndResources - Task 034 authorized host effects, typed failures, and owned resources.
190
191
  */
191
192
 
@@ -700,7 +701,14 @@
700
701
  * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned type-name range.
701
702
  */
702
703
 
703
- /** @typedef {TypeReference | TypeVariableReference | ListType | MapType | OrderedMapType | OptionalType | RecordType | ReferenceType | OwnedResourceType | OwnedReferenceType} SemanticValueType */
704
+ /**
705
+ * @typedef InterfaceType
706
+ * @property {"InterfaceType"} kind - Nominal bounded-subtyping interface type discriminator.
707
+ * @property {string} declarationId - Stable module-local interface declaration identity.
708
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned type-name range.
709
+ */
710
+
711
+ /** @typedef {TypeReference | TypeVariableReference | ListType | MapType | OrderedMapType | OptionalType | RecordType | ReferenceType | OwnedResourceType | OwnedReferenceType | InterfaceType} SemanticValueType */
704
712
  /** @typedef {SemanticValueType | ErrorType} SemanticBindingType */
705
713
 
706
714
  /**
@@ -712,7 +720,7 @@
712
720
 
713
721
  /** @typedef {SemanticValueType | FunctionReturnTypeReference} SemanticFunctionReturnType */
714
722
 
715
- /** @typedef {SemanticTypeName | {kind: "TypeVariableReference", parameterId: string} | {kind: "ListType", elementType: SemanticTypeIdentity} | {kind: "MapType", keyType: SemanticTypeIdentity, valueType: SemanticTypeIdentity} | {kind: "OrderedMapType", keyType: SemanticTypeIdentity, valueType: SemanticTypeIdentity, order: "insertion"} | {kind: "OptionalType", valueType: SemanticTypeIdentity} | {kind: "RecordType", declarationId: string, arguments?: SemanticTypeIdentity[]} | {kind: "ReferenceType", declarationId: string} | {kind: "OwnedResourceType", resourceId: string} | {kind: "OwnedReferenceType", declarationId: string}} SemanticTypeIdentity */
723
+ /** @typedef {SemanticTypeName | {kind: "TypeVariableReference", parameterId: string} | {kind: "ListType", elementType: SemanticTypeIdentity} | {kind: "MapType", keyType: SemanticTypeIdentity, valueType: SemanticTypeIdentity} | {kind: "OrderedMapType", keyType: SemanticTypeIdentity, valueType: SemanticTypeIdentity, order: "insertion"} | {kind: "OptionalType", valueType: SemanticTypeIdentity} | {kind: "RecordType", declarationId: string, arguments?: SemanticTypeIdentity[]} | {kind: "ReferenceType", declarationId: string} | {kind: "OwnedResourceType", resourceId: string} | {kind: "OwnedReferenceType", declarationId: string} | {kind: "InterfaceType", declarationId: string}} SemanticTypeIdentity */
716
724
  /** @typedef {SemanticTypeIdentity | "void"} FunctionReturnTypeIdentity */
717
725
 
718
726
  /**
@@ -1229,6 +1237,15 @@
1229
1237
  * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned raise range.
1230
1238
  */
1231
1239
 
1240
+ /**
1241
+ * @typedef RethrowStatement
1242
+ * @property {"RethrowStatement"} kind - Re-propagation of the exact caught binding in scope.
1243
+ * @property {string} binding - Name of the lexically visible immutable catch binding being re-raised.
1244
+ * @property {CatchBinding} bindingNode - Exact catch binding node being re-raised.
1245
+ * @property {SourceLocation} location - Complete rethrow source location.
1246
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned rethrow range.
1247
+ */
1248
+
1232
1249
  /**
1233
1250
  * @typedef CatchBinding
1234
1251
  * @property {"CatchBinding"} kind - Exact-handler binding discriminator.
@@ -1240,18 +1257,27 @@
1240
1257
  */
1241
1258
 
1242
1259
  /**
1243
- * @typedef TryStatement
1244
- * @property {"TryStatement"} kind - One body and one exact typed handler.
1245
- * @property {Block} body - Protected body.
1260
+ * @typedef CatchHandler
1261
+ * @property {"CatchHandler"} kind - One exact nominal handler within an ordered handler list.
1246
1262
  * @property {ErrorType} catchType - Exact caught nominal error type.
1247
1263
  * @property {CatchBinding} catchBinding - Immutable handler-local binding.
1248
1264
  * @property {Block} catchBody - Handler body.
1265
+ * @property {SourceLocation} location - Complete handler source location.
1266
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned catch ranges.
1267
+ */
1268
+
1269
+ /**
1270
+ * @typedef TryStatement
1271
+ * @property {"TryStatement"} kind - One body, an ordered list of exact typed handlers, and an optional completion block.
1272
+ * @property {Block} body - Protected body.
1273
+ * @property {CatchHandler[]} handlers - Ordered exact handlers, evaluated top to bottom with exact nominal matching.
1274
+ * @property {Block} [finallyBody] - Completion block executed on every normal and abrupt completion of the try.
1249
1275
  * @property {SourceLocation} location - Complete try/handler source location.
1250
- * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned try/catch ranges.
1276
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned try/catch/finally ranges.
1251
1277
  */
1252
1278
 
1253
1279
  /** @typedef {LocalDeclaration | AssignmentStatement} LocalStatement */
1254
- /** @typedef {LocalStatement | PrivateFieldWriteStatement | ExpressionStatement | IfStatement | ForEachStatement | ForEachMapStatement | WhileStatement | BreakStatement | ContinueStatement | ReturnStatement | PrintStatement | RaiseStatement | TryStatement} Statement */
1280
+ /** @typedef {LocalStatement | PrivateFieldWriteStatement | ExpressionStatement | IfStatement | ForEachStatement | ForEachMapStatement | WhileStatement | BreakStatement | ContinueStatement | ReturnStatement | PrintStatement | RaiseStatement | RethrowStatement | TryStatement} Statement */
1255
1281
 
1256
1282
  /**
1257
1283
  * @typedef Block
@@ -1327,10 +1353,33 @@
1327
1353
  * @property {Block} body - Method body.
1328
1354
  * @property {readonly ["host"]} [effects] - Inferred checked host-effect fact.
1329
1355
  * @property {string[]} [failureIds] - Ordered capability failures reachable through the method.
1356
+ * @property {{interfaceId: string, methodId: string}} [implements] - Exact satisfied interface member, required after validation when the method satisfies an interface contract.
1330
1357
  * @property {SourceLocation} location - Complete method location.
1331
1358
  * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned method-name range.
1332
1359
  */
1333
1360
 
1361
+ /**
1362
+ * @typedef InterfaceMethodDeclaration
1363
+ * @property {"InterfaceMethodDeclaration"} kind - Signature-only interface contract member.
1364
+ * @property {string} [id] - Stable interface-scoped method identity, required after validation.
1365
+ * @property {string} name - Source-visible method name.
1366
+ * @property {Parameter[]} parameters - Exact positional required parameters with explicit types.
1367
+ * @property {SemanticFunctionReturnType} returnType - Exact value or void return.
1368
+ * @property {SourceLocation} location - Complete interface method location.
1369
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned method-name range.
1370
+ */
1371
+
1372
+ /**
1373
+ * @typedef InterfaceDeclaration
1374
+ * @property {"InterfaceDeclaration"} kind - Closed signature-only nominal interface with exact implementation contracts.
1375
+ * @property {string} [id] - Stable module-local interface identity, required after validation.
1376
+ * @property {string} name - Source-visible interface name.
1377
+ * @property {InterfaceType[]} [extends] - Direct interface parents in source order; omitted when empty.
1378
+ * @property {InterfaceMethodDeclaration[]} methods - Ordered closed signature set.
1379
+ * @property {SourceLocation} location - Complete interface location.
1380
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned interface-name range.
1381
+ */
1382
+
1334
1383
  /**
1335
1384
  * @typedef ClassDeclaration
1336
1385
  * @property {"ClassDeclaration"} kind - Nominal reference class with private mutable state.
@@ -1339,6 +1388,7 @@
1339
1388
  * @property {PrivateField[]} fields - Ordered private instance state.
1340
1389
  * @property {ConstructorDeclaration} constructor - Sole exact constructor.
1341
1390
  * @property {MethodDeclaration[]} methods - Ordered receiver methods.
1391
+ * @property {InterfaceType[]} [implements] - Direct interface contracts in source order; omitted when empty.
1342
1392
  * @property {{kind: "ordinary"} | {kind: "ownedResource", fieldId: string, resourceId: string}} [ownership] - Explicit class ownership profile.
1343
1393
  * @property {SourceLocation} location - Complete class location.
1344
1394
  * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned class-name range.
@@ -1373,6 +1423,7 @@
1373
1423
  * @typedef SemanticModule
1374
1424
  * @property {"Module"} kind - Node discriminator.
1375
1425
  * @property {RecordDeclaration[]} [records] - Top-level nominal record declarations in source order; omitted when empty.
1426
+ * @property {InterfaceDeclaration[]} [interfaces] - Top-level nominal interface declarations in source order; omitted when empty.
1376
1427
  * @property {ClassDeclaration[]} [classes] - Top-level nominal reference classes in source order; omitted when empty.
1377
1428
  * @property {ErrorDeclaration[]} [errors] - Top-level nominal unchecked error declarations in source order; omitted when empty.
1378
1429
  * @property {EffectCapabilityDeclaration[]} [capabilities] - Compiler-authorized Task 034 declarations; omission is the legacy empty set.
@@ -1423,6 +1474,7 @@
1423
1474
  * @property {string} id - Stable caller-supplied logical module identity.
1424
1475
  * @property {string} sourceFilename - Explicit source filename; never an implicit read request.
1425
1476
  * @property {RecordDeclaration[]} [records] - Top-level nominal record declarations.
1477
+ * @property {InterfaceDeclaration[]} [interfaces] - Top-level nominal interface declarations.
1426
1478
  * @property {ClassDeclaration[]} [classes] - Compiler-owned facade reference classes.
1427
1479
  * @property {ErrorDeclaration[]} [errors] - Top-level nominal unchecked error declarations.
1428
1480
  * @property {FunctionDeclaration[]} functions - Top-level functions.
@@ -1468,7 +1520,7 @@
1468
1520
  * @property {StdlibFacadeProgramDescriptor} [stdlibFacades] - Complete selected source-language facade closure.
1469
1521
  */
1470
1522
 
1471
- /** @typedef {SemanticModule | SemanticProgramModule | SemanticImport | SemanticExport | RecordDeclaration | ClassDeclaration | ErrorDeclaration | EffectCapabilityDeclaration | EffectResourceDeclaration | EffectFailureDeclaration | EffectOperationDeclaration | RecordField | PrivateField | ConstructorDeclaration | MethodDeclaration | FunctionDeclaration | TypeParameter | Parameter | ValueBinding | CatchBinding | Block | Statement | EntryPoint | Expression | ErrorConstruction | ErrorType | MapEntry | SemanticValueType | FunctionReturnTypeReference} SemanticNode */
1523
+ /** @typedef {SemanticModule | SemanticProgramModule | SemanticImport | SemanticExport | RecordDeclaration | InterfaceDeclaration | InterfaceMethodDeclaration | ClassDeclaration | ErrorDeclaration | EffectCapabilityDeclaration | EffectResourceDeclaration | EffectFailureDeclaration | EffectOperationDeclaration | RecordField | PrivateField | ConstructorDeclaration | MethodDeclaration | FunctionDeclaration | TypeParameter | Parameter | ValueBinding | CatchBinding | CatchHandler | Block | Statement | EntryPoint | Expression | ErrorConstruction | ErrorType | MapEntry | SemanticValueType | FunctionReturnTypeReference} SemanticNode */
1472
1524
  /** @typedef {SemanticNode} SemanticNodeWithoutLocations */
1473
1525
 
1474
1526
  export {}