semantifold 0.3.0 → 0.4.0

package/src/semantic/types.js

@@ -1,14 +1,63 @@
 // @ts-check
 
-/** @typedef {"php" | "ruby" | "javascript" | "typescript" | "java" | "python" | "csharp" | "go" | "c" | "cpp"} SemanticLanguage */
+/** @typedef {"php" | "ruby" | "javascript" | "typescript" | "java" | "kotlin" | "python" | "csharp" | "go" | "c" | "cpp" | "rust" | "swift" | "dart"} SemanticLanguage */
+/** @typedef {SemanticLanguage} TextBackendLanguage */
+/** @typedef {TextBackendLanguage | "wasm" | "ios"} BackendLanguage */
+/** @typedef {SemanticLanguage | "html"} GeneratedTextLanguage */
 /** @typedef {"integer" | "boolean" | "string"} SemanticTypeName */
+/** @typedef {SemanticTypeName | "void"} FunctionReturnTypeName */
 /** @typedef {"IntegerNegate" | "BooleanNot"} SemanticUnaryOperation */
 /** @typedef {"IntegerAdd" | "IntegerSubtract" | "IntegerMultiply" | "BooleanAnd" | "BooleanOr" | "IntegerEqual" | "IntegerNotEqual" | "BooleanEqual" | "BooleanNotEqual" | "StringEqual" | "StringNotEqual" | "IntegerLessThan" | "IntegerLessThanOrEqual" | "IntegerGreaterThan" | "IntegerGreaterThanOrEqual" | "StringConcat"} SemanticBinaryOperation */
-/** @typedef {"function" | "parameter" | "local"} SemanticSymbolKind */
-/** @typedef {"declaration" | "read" | "write" | "call"} SemanticSymbolRole */
+/** @typedef {"capability" | "resource" | "failure" | "operation" | "record" | "class" | "error" | "field" | "constructor" | "method" | "function" | "typeParameter" | "parameter" | "local" | "iteration" | "catch"} SemanticSymbolKind */
+/** @typedef {"record" | "class" | "error" | "function"} SemanticDeclarationKind */
+/** @typedef {"declaration" | "type" | "construct" | "member" | "read" | "write" | "call"} SemanticSymbolRole */
 /** @typedef {"parse" | "generate" | "restore" | "compile" | "link" | "validate" | "instantiate" | "execute"} AcceptanceStage */
 /** @typedef {"entry" | "source" | "manifest" | "support" | "mapping" | "resource" | "loader"} GeneratedArtifactRole */
 
+/**
+ * @typedef IosApplicationConfigurationInput
+ * @property {string} productName - Safe Xcode product/path identity.
+ * @property {string} moduleName - Safe Swift module identity.
+ * @property {string} organizationPrefix - Caller-supplied reverse-DNS organization prefix.
+ * @property {string} bundleIdentifier - Caller-supplied reverse-DNS application bundle identity.
+ * @property {string} deploymentTarget - Caller-supplied major.minor iOS deployment target; never inferred.
+ * @property {string} displayName - User-visible application name.
+ * @property {"Sources"} [sourceRoot] - Fixed generated-source root.
+ * @property {"Assets.xcassets"} [resourceRoot] - Fixed caller-resource root.
+ * @property {"swiftui"} [lifecycle] - Sole supported lifecycle.
+ * @property {Record<string, never>} [infoPlist] - Closed baseline caller plist extension; currently empty.
+ * @property {unknown[]} [permissions] - Validated as the closed empty baseline permissions.
+ * @property {unknown[]} [entitlements] - Validated as the closed empty baseline entitlements.
+ * @property {unknown[]} [privacyDeclarations] - Validated as the closed empty baseline privacy declarations.
+ * @property {unknown[]} [capabilities] - Validated as the closed empty baseline Apple capabilities.
+ */
+
+/**
+ * @typedef IosApplicationConfiguration
+ * @property {string} productName - Validated Xcode product/path identity.
+ * @property {string} moduleName - Validated Swift module identity.
+ * @property {string} organizationPrefix - Validated reverse-DNS organization prefix.
+ * @property {string} bundleIdentifier - Validated reverse-DNS application bundle identity.
+ * @property {string} deploymentTarget - Validated caller-supplied deployment target.
+ * @property {string} displayName - Validated display name.
+ * @property {"Sources"} sourceRoot - Generated-source root.
+ * @property {"Assets.xcassets"} resourceRoot - Caller-resource root.
+ * @property {"swiftui"} lifecycle - Sole supported lifecycle.
+ * @property {Readonly<Record<string, never>>} infoPlist - Empty caller plist extension.
+ * @property {readonly never[]} permissions - Empty baseline permissions.
+ * @property {readonly never[]} entitlements - Empty baseline entitlements.
+ * @property {readonly never[]} privacyDeclarations - Empty baseline privacy declarations.
+ * @property {readonly never[]} capabilities - Empty baseline Apple capabilities.
+ */
+
+/**
+ * @typedef IosApplicationAssetInput
+ * @property {string} path - Full safe destination below Assets.xcassets.
+ * @property {string | Uint8Array} content - Exact caller-provided text or bytes.
+ * @property {string} mediaType - Explicit artifact media type.
+ * @property {string} sha256 - Lowercase SHA-256 of exact UTF-8 text or bytes.
+ */
+
 /**
  * @typedef LanguageRoleCapabilities
  * @property {boolean} frontend - Parser adapter availability.
@@ -16,6 +65,7 @@
  * @property {boolean} binaryBackend - Binary backend availability.
  * @property {boolean} applicationBackend - Application-artifact backend availability.
  * @property {boolean} interoperability - Interoperability bridge availability.
+ * @property {boolean} provider - Target host stdlib provider/native-binding availability.
  */
 
 /**
@@ -31,12 +81,28 @@
  * @property {readonly string[]} toolchains - Required canonical toolchain IDs.
  */
 
+/**
+ * @typedef LanguageFeatureCapabilities
+ * @property {boolean} generalFunctionsAndCalls - Task 005 arbitrary required signatures, resolved direct calls, and void functions.
+ * @property {boolean} immutableCollections - Task 006 recursive immutable lists/maps, total access, and size.
+ * @property {boolean} optionalValues - Task 007 explicit optional values, presence tests, and guarded unwrap.
+ * @property {boolean} orderedListIteration - Task 008 ordered immutable-list iteration and nearest-loop control.
+ * @property {boolean} orderedMapIteration - Task 014 insertion-ordered immutable-map pair iteration.
+ * @property {boolean} conditionControlledLoops - Task 032 strict-Boolean pre-condition loops and resolved control.
+ * @property {boolean} closedRecords - Task 009 nominal closed immutable records, construction, and member reads.
+ * @property {boolean} typedErrors - Task 011 nominal unchecked errors, raises, and exact typed catches.
+ * @property {boolean} typeParametersAndGenerics - Task 012 invariant unbounded type parameters and closed generic applications.
+ * @property {boolean} referenceClasses - Task 033 nominal reference classes, private instance state, exact constructors, and receiver methods.
+ * @property {boolean} effectfulCapabilitiesAndResources - Task 034 authorized host effects, typed failures, and owned resources.
+ */
+
 /**
  * @typedef LanguageCapabilities
  * @property {string} id - Stable registry identity.
  * @property {Readonly<LanguageRoleCapabilities>} roles - Independently registered roles.
  * @property {"single" | "multiple"} artifactMultiplicity - Target artifact multiplicity.
  * @property {boolean} roundTrip - Whether frontend/backend round-trip acceptance is declared.
+ * @property {Readonly<LanguageFeatureCapabilities>} features - Semantic feature capabilities.
  * @property {Readonly<LanguageMappingCapabilities>} mapping - Mapping forms.
  * @property {Readonly<LanguageAcceptanceCapabilities>} acceptance - Stages and toolchains.
  */
@@ -61,6 +127,7 @@
  * @property {string} filename - Original filename, preserved verbatim.
  * @property {string | null} content - Original source content, preserved verbatim when available.
  * @property {SemanticLanguage | null} language - Parser language when known.
+ * @property {"application" | "facade"} [ownership] - Caller or compiler-owned source role for semantic programs.
  */
 
 /**
@@ -143,6 +210,7 @@
  * @property {string} name - Semantic symbol name.
  * @property {SemanticSymbolKind} kind - Symbol category.
  * @property {string} declarationNodeId - Declaring node identity.
+ * @property {string} [semanticDeclarationId] - Stable semantic declaration identity for record, field, and function symbols.
  * @property {SourceLocation} location - Exact declaration-name range.
  * @property {SemanticSymbolReference[]} references - Ordered resolved references.
  */
@@ -173,7 +241,7 @@
 /**
  * @typedef GeneratedSource
  * @property {string} filename - Output filename.
- * @property {SemanticLanguage} language - Output language.
+ * @property {GeneratedTextLanguage} language - Output text language.
  * @property {string} content - Exact generated LF source.
  */
 
@@ -240,6 +308,7 @@
  * @property {string} target - Stable language or target ID.
  * @property {string} entry - Path of the sole declared entry artifact.
  * @property {readonly GeneratedSetArtifact[]} artifacts - Deterministic artifact order.
+ * @property {Readonly<Record<string, unknown>>} [metadata] - Detached target-specific JSON metadata.
  */
 
 /**
@@ -248,8 +317,8 @@
  * @property {string} command - Documented canonical command.
  * @property {string} executable - Exact absolute executable path.
  * @property {"override" | "canonical"} source - Resolution route.
- * @property {string} version - First captured version line.
- * @property {string} versionOutput - Complete captured version output.
+ * @property {string} version - First selected-stream version line.
+ * @property {string} versionOutput - Complete normalized stdout, or normalized stderr when stdout is empty.
  * @property {readonly string[]} versionArguments - Exact version argument array.
  */
 
@@ -273,15 +342,291 @@
 /**
  * @typedef TypeReference
  * @property {"TypeReference"} kind - Node discriminator.
- * @property {SemanticTypeName} name - Normalized type name.
+ * @property {SemanticTypeName} name - Normalized scalar value type name.
  * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance that survives semantic transforms.
  */
 
+/**
+ * @typedef TypeParameter
+ * @property {"TypeParameter"} kind - Declaration-scoped invariant unbounded type parameter.
+ * @property {string} [id] - Stable declaration-scoped identity, required after validation.
+ * @property {string} name - Source-visible type parameter name.
+ * @property {SourceLocation} location - Parser-owned declaration location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned declaration-name range.
+ */
+
+/**
+ * @typedef TypeVariableReference
+ * @property {"TypeVariableReference"} kind - Reference to one declaration-scoped type parameter.
+ * @property {string} parameterId - Stable referenced type-parameter identity.
+ * @property {SourceLocation} location - Parser-owned reference location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned type-name range.
+ */
+
+/**
+ * @typedef ListType
+ * @property {"ListType"} kind - Recursive list-type discriminator.
+ * @property {SemanticValueType} elementType - Homogeneous element type.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned outer and argument ranges.
+ */
+
+/**
+ * @typedef MapType
+ * @property {"MapType"} kind - Recursive map-type discriminator.
+ * @property {TypeReference} keyType - Exact string key type.
+ * @property {SemanticValueType} valueType - Homogeneous value type.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned outer and argument ranges.
+ */
+
+/**
+ * @typedef OrderedMapType
+ * @property {"OrderedMapType"} kind - Distinct insertion-ordered map-type discriminator.
+ * @property {TypeReference} keyType - Exact supported string key type.
+ * @property {SemanticValueType} valueType - Homogeneous value type.
+ * @property {"insertion"} order - Canonical first-insertion encounter order.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned outer and argument ranges.
+ */
+
+/**
+ * @typedef OptionalType
+ * @property {"OptionalType"} kind - Explicit presence/absence type discriminator.
+ * @property {SemanticValueType} valueType - Exact present-value type.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned outer and constituent ranges.
+ */
+
+/**
+ * @typedef RecordType
+ * @property {"RecordType"} kind - Nominal record-type discriminator.
+ * @property {string} declarationId - Stable module-local record declaration identity.
+ * @property {SemanticValueType[]} [arguments] - Exact invariant type arguments; required for generic declarations and absent for non-generic declarations.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned type-name range.
+ */
+
+/**
+ * @typedef ErrorType
+ * @property {"ErrorType"} kind - Nominal unchecked-error type discriminator.
+ * @property {string} declarationId - Stable error declaration identity.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned type-name range.
+ */
+
+/**
+ * @typedef ReferenceType
+ * @property {"ReferenceType"} kind - Nominal reference-class type discriminator.
+ * @property {string} declarationId - Stable module-local class declaration identity.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned type-name range.
+ */
+
+/**
+ * @typedef OwnedResourceType
+ * @property {"OwnedResourceType"} kind - Compiler-owned linear resource type.
+ * @property {string} resourceId - Exact authority resource declaration identity.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned type-name range.
+ */
+
+/**
+ * @typedef OwnedReferenceType
+ * @property {"OwnedReferenceType"} kind - Linear reference that owns one protected resource.
+ * @property {string} declarationId - Exact owned class declaration identity.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned type-name range.
+ */
+
+/** @typedef {TypeReference | TypeVariableReference | ListType | MapType | OrderedMapType | OptionalType | RecordType | ReferenceType | OwnedResourceType | OwnedReferenceType} SemanticValueType */
+/** @typedef {SemanticValueType | ErrorType} SemanticBindingType */
+
+/**
+ * @typedef FunctionReturnTypeReference
+ * @property {"TypeReference"} kind - Void return discriminator.
+ * @property {"void"} name - Normalized non-value function return.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance that survives semantic transforms.
+ */
+
+/** @typedef {SemanticValueType | FunctionReturnTypeReference} SemanticFunctionReturnType */
+
+/** @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 */
+/** @typedef {SemanticTypeIdentity | "void"} FunctionReturnTypeIdentity */
+
+/**
+ * @typedef ResolvedFunctionSignature
+ * @property {"ResolvedFunctionSignature"} kind - Resolution discriminator.
+ * @property {string} declarationId - Deterministic module-local declaration identity.
+ * @property {SemanticTypeIdentity[]} parameterTypes - Exact required positional parameter types.
+ * @property {FunctionReturnTypeIdentity} returnType - Exact resolved return type.
+ * @property {SemanticTypeIdentity[]} [typeArguments] - Inferred declaration-order type arguments for a generic call.
+ */
+
 /**
  * @typedef Parameter
  * @property {"Parameter"} kind - Node discriminator.
  * @property {string} name - Parameter name.
- * @property {TypeReference} type - Parameter type.
+ * @property {SemanticValueType} type - Parameter type.
+ * @property {SourceLocation} location - Source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
+ */
+
+/**
+ * @typedef ResolvedEffectOperationSignature
+ * @property {"ResolvedEffectOperationSignature"} kind - Resolution discriminator.
+ * @property {string} capabilityId - Exact capability declaration identity.
+ * @property {string} operationId - Exact operation declaration identity.
+ * @property {SemanticTypeIdentity[]} parameterTypes - Exact ordered parameter types.
+ * @property {FunctionReturnTypeIdentity} returnType - Exact operation result.
+ * @property {readonly ["host"]} effects - Closed initial effect set.
+ * @property {string[]} failureIds - Exact ordered declared failures.
+ * @property {EffectResourceFlow} resourceFlow - Exact ownership transition.
+ */
+
+/**
+ * @typedef OwnedMoveExpression
+ * @property {"OwnedMoveExpression"} kind - Explicit linear ownership transfer.
+ * @property {IdentifierExpression} expression - Moved owner.
+ * @property {OwnedResourceType | OwnedReferenceType} type - Exact owned type.
+ * @property {SourceLocation} location - Exact transfer location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Derived source provenance.
+ */
+
+/**
+ * @typedef OwnedBorrowExpression
+ * @property {"OwnedBorrowExpression"} kind - Immediate nonescaping resource borrow.
+ * @property {"shared" | "exclusive"} mode - Borrow mode.
+ * @property {IdentifierExpression | ReceiverExpression | PrivateFieldRead} expression - Borrowed place.
+ * @property {OwnedResourceType | OwnedReferenceType} type - Exact owned type.
+ * @property {SourceLocation} location - Exact borrow location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Derived source provenance.
+ */
+
+/**
+ * @typedef EffectCallExpression
+ * @property {"EffectCallExpression"} kind - Compiler-authorized effect invocation.
+ * @property {string} operation - Exact operation declaration identity.
+ * @property {Expression[]} arguments - Source-ordered arguments.
+ * @property {string} effectSiteId - Deterministic semantic evaluation identity.
+ * @property {ResolvedEffectOperationSignature} resolution - Complete authority resolution.
+ * @property {SourceLocation} location - Complete call location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned operation-name range.
+ */
+
+/**
+ * @typedef EffectParameter
+ * @property {string} name - Stable parameter name.
+ * @property {SemanticValueType} type - Exact ordered parameter type.
+ */
+
+/** @typedef {{kind: "none"} | {kind: "acquire", resourceId: string} | {kind: "borrow" | "close", parameterIndex: number, terminalFailureId: string}} EffectResourceFlow */
+
+/**
+ * @typedef EffectResourceDeclaration
+ * @property {"EffectResourceDeclaration"} kind - Capability resource declaration.
+ * @property {string} id - Deterministic authority-local identity.
+ * @property {string} name - Source-visible nominal resource name.
+ */
+
+/**
+ * @typedef EffectFailureDeclaration
+ * @property {"EffectFailureDeclaration"} kind - Capability failure declaration.
+ * @property {string} id - Deterministic authority-local identity.
+ * @property {string} name - Source-visible nominal failure name.
+ */
+
+/**
+ * @typedef EffectOperationDeclaration
+ * @property {"EffectOperationDeclaration"} kind - Compiler-authorized operation declaration.
+ * @property {string} id - Deterministic authority-local identity.
+ * @property {string} name - Source-visible operation name.
+ * @property {EffectParameter[]} parameters - Exact positional parameters.
+ * @property {SemanticFunctionReturnType} returnType - Exact result type.
+ * @property {readonly ["host"]} effects - Closed initial effect set.
+ * @property {string[]} failureIds - Ordered nominal failure identities.
+ * @property {EffectResourceFlow} resourceFlow - Exact ownership transition.
+ */
+
+/**
+ * @typedef EffectCapabilityDeclaration
+ * @property {"EffectCapabilityDeclaration"} kind - Authorized capability declaration.
+ * @property {string} id - Deterministic module-local identity.
+ * @property {string} authorityId - Opaque authority identity.
+ * @property {string} name - Capability name.
+ * @property {EffectResourceDeclaration[]} resources - Ordered resources.
+ * @property {EffectFailureDeclaration[]} failures - Ordered failures.
+ * @property {EffectOperationDeclaration[]} operations - Ordered operations.
+ */
+
+/**
+ * @typedef CapabilityAuthority
+ * @property {"SemantifoldCapabilityAuthority"} schema - Authority schema discriminator.
+ * @property {1 | 2} schemaVersion - Authority payload version, not a standard-library contract version.
+ * @property {string} id - Opaque caller-supplied authority identity.
+ * @property {EffectCapabilityDeclaration[]} capabilities - Normalized declarations.
+ * @property {string} [contractVersion] - Declared standard-library contract version, present only when the caller supplied one.
+ * @property {{identity: string, contractVersion: string, capabilities: EffectCapabilityDeclaration[]}[]} [modules] - Schema-v2 canonical module authorities.
+ */
+
+/** @typedef {{module: string, name: string}} CapabilityDeclarationReferenceInput */
+/** @typedef {{name: string, type: SemanticTypeName | {kind: "OwnedResourceType", resource: string | CapabilityDeclarationReferenceInput} | {kind: "OptionalType", valueType: SemanticTypeName}}} CapabilityParameterInput */
+/** @typedef {{name: string}} CapabilityNamedInput */
+/** @typedef {{kind: "none"} | {kind: "acquire", resource: string | CapabilityDeclarationReferenceInput} | {kind: "borrow" | "close", parameterIndex: number, terminalFailure: string | CapabilityDeclarationReferenceInput}} CapabilityResourceFlowInput */
+/** @typedef {{name: string, parameters: CapabilityParameterInput[], returnType: FunctionReturnTypeName | {kind: "OwnedResourceType", resource: string | CapabilityDeclarationReferenceInput} | {kind: "OptionalType", valueType: SemanticTypeName}, effects: ["host"], failures: (string | CapabilityDeclarationReferenceInput)[], resourceFlow: CapabilityResourceFlowInput}} CapabilityOperationInput */
+/** @typedef {{name: string, resources: CapabilityNamedInput[], failures: CapabilityNamedInput[], operations: CapabilityOperationInput[]}} CapabilityDeclarationInput */
+/** @typedef {{identity: string, contractVersion: string, capabilities: CapabilityDeclarationInput[]}} CapabilityAuthorityModuleInput */
+/** @typedef {{schema: "SemantifoldCapabilityAuthority", schemaVersion: 1, id: string, capabilities: CapabilityDeclarationInput[], contractVersion?: string} | {schema: "SemantifoldCapabilityAuthority", schemaVersion: 2, id: string, modules: CapabilityAuthorityModuleInput[]}} CapabilityAuthorityInput */
+
+/**
+ * @typedef ListLiteral
+ * @property {"ListLiteral"} kind - Ordered immutable list literal.
+ * @property {Expression[]} elements - Source-ordered, duplicate-preserving elements.
+ * @property {SourceLocation} location - Source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
+ */
+
+/**
+ * @typedef MapEntry
+ * @property {"MapEntry"} kind - Source-ordered map initializer entry.
+ * @property {StringLiteral} key - Literal nonnumeric string key.
+ * @property {Expression} value - Entry value.
+ * @property {SourceLocation} location - Source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
+ */
+
+/**
+ * @typedef MapLiteral
+ * @property {"MapLiteral"} kind - Immutable map literal; entry order is diagnostic-only.
+ * @property {MapEntry[]} entries - Source initializer order.
+ * @property {SourceLocation} location - Source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
+ */
+
+/**
+ * @typedef OrderedMapLiteral
+ * @property {"OrderedMapLiteral"} kind - Immutable map literal with observable first-insertion order.
+ * @property {MapEntry[]} entries - Source-ordered unique entries.
+ * @property {SourceLocation} location - Complete ordered construction boundary.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
+ */
+
+/**
+ * @typedef ListIndexExpression
+ * @property {"ListIndexExpression"} kind - Total zero-based list index.
+ * @property {Expression} collection - List-valued receiver.
+ * @property {Expression} index - Integer index.
+ * @property {"proven" | "fail-on-absence"} totality - Admission basis; never optional.
+ * @property {SourceLocation} location - Source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
+ */
+
+/**
+ * @typedef MapLookupExpression
+ * @property {"MapLookupExpression"} kind - Total string-key map lookup.
+ * @property {Expression} collection - Map-valued receiver.
+ * @property {Expression} key - String key expression.
+ * @property {"proven" | "fail-on-absence"} totality - Admission basis; never optional.
+ * @property {SourceLocation} location - Source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
+ */
+
+/**
+ * @typedef CollectionSizeExpression
+ * @property {"CollectionSizeExpression"} kind - Finite collection size.
+ * @property {Expression} collection - List- or map-valued receiver.
+ * @property {"list" | "map"} [collectionKind] - Validated receiver kind for target spelling.
  * @property {SourceLocation} location - Source location.
  * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
  */
@@ -318,6 +663,37 @@
  * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
  */
 
+/**
+ * @typedef OptionalNone
+ * @property {"OptionalNone"} kind - Contextually typed absence value.
+ * @property {SourceLocation} location - Source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
+ */
+
+/**
+ * @typedef OptionalSome
+ * @property {"OptionalSome"} kind - Explicit present optional value.
+ * @property {Expression} value - Exact non-optional present value.
+ * @property {SourceLocation} location - Source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
+ */
+
+/**
+ * @typedef OptionalIsPresent
+ * @property {"OptionalIsPresent"} kind - Presence test for one simple identifier.
+ * @property {IdentifierExpression} operand - Tested optional binding.
+ * @property {SourceLocation} location - Source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
+ */
+
+/**
+ * @typedef OptionalUnwrap
+ * @property {"OptionalUnwrap"} kind - Guarded unwrap of one simple identifier.
+ * @property {IdentifierExpression} operand - Proven-present optional binding.
+ * @property {SourceLocation} location - Source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
+ */
+
 /**
  * @typedef UnaryExpression
  * @property {"UnaryExpression"} kind - Node discriminator.
@@ -344,17 +720,107 @@
  * @property {"CallExpression"} kind - Node discriminator.
  * @property {string} callee - Function name.
  * @property {Expression[]} arguments - Positional arguments.
+ * @property {ResolvedFunctionSignature} [resolution] - Deterministic declaration and signature binding, required after frontend validation.
+ * @property {string} [effectSiteId] - Deterministic site identity when the resolved function reaches a host effect.
+ * @property {readonly ["host"]} [effects] - Inferred checked host-effect fact.
+ * @property {string[]} [failureIds] - Ordered capability failures reachable through this call.
  * @property {SourceLocation} location - Source location.
  * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
  */
 
-/** @typedef {IdentifierExpression | IntegerLiteral | BooleanLiteral | StringLiteral | UnaryExpression | BinaryExpression | CallExpression} Expression */
+/**
+ * @typedef ResolvedConstructorSignature
+ * @property {"ResolvedConstructorSignature"} kind - Resolution discriminator.
+ * @property {string} declarationId - Exact constructor declaration identity.
+ * @property {SemanticTypeIdentity[]} parameterTypes - Exact constructor parameter types.
+ */
+
+/**
+ * @typedef ResolvedMethodSignature
+ * @property {"ResolvedMethodSignature"} kind - Resolution discriminator.
+ * @property {string} declarationId - Exact resolved method identity.
+ * @property {SemanticTypeIdentity[]} parameterTypes - Exact method parameter types.
+ * @property {FunctionReturnTypeIdentity} returnType - Exact method return type.
+ * @property {{kind: "preserve" | "terminal", terminalFailureId?: string}} [resourceFlow] - Owned receiver transition and declared terminal-use failure when applicable.
+ */
+
+/**
+ * @typedef ReceiverExpression
+ * @property {"ReceiverExpression"} kind - The declaring class instance receiver.
+ * @property {string} classId - Stable declaring class identity.
+ * @property {SourceLocation} location - Source receiver location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned receiver range.
+ */
+
+/**
+ * @typedef ReferenceConstruction
+ * @property {"ReferenceConstruction"} kind - Fresh nominal reference construction.
+ * @property {ReferenceType | OwnedReferenceType} reference - Exact class type.
+ * @property {Expression[]} arguments - Source-ordered constructor arguments.
+ * @property {ResolvedConstructorSignature} [resolution] - Exact constructor binding, required after validation.
+ * @property {string} [effectSiteId] - Deterministic site identity when construction reaches a host effect.
+ * @property {readonly ["host"]} [effects] - Inferred checked host-effect fact.
+ * @property {string[]} [failureIds] - Ordered capability failures reachable through construction.
+ * @property {SourceLocation} location - Complete construction location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned class-name range.
+ */
+
+/**
+ * @typedef MethodCallExpression
+ * @property {"MethodCallExpression"} kind - Resolved receiver-method invocation.
+ * @property {Expression} receiver - Receiver evaluated once before arguments.
+ * @property {string} method - Stable method identity after validation.
+ * @property {Expression[]} arguments - Source-ordered arguments.
+ * @property {ResolvedMethodSignature} [resolution] - Exact method binding, required after validation.
+ * @property {string} [effectSiteId] - Deterministic site identity when the method reaches a host effect.
+ * @property {readonly ["host"]} [effects] - Inferred checked host-effect fact.
+ * @property {string[]} [failureIds] - Ordered capability failures reachable through the method.
+ * @property {SourceLocation} location - Complete call location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned method-name range.
+ */
+
+/**
+ * @typedef PrivateFieldRead
+ * @property {"PrivateFieldRead"} kind - Declaring-receiver-only private field read.
+ * @property {ReceiverExpression} receiver - Exact declaring receiver.
+ * @property {string} field - Stable private field identity.
+ * @property {SourceLocation} location - Complete read location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned field-name range.
+ */
+
+/**
+ * @typedef RecordConstruction
+ * @property {"RecordConstruction"} kind - Nominal record construction.
+ * @property {RecordType} record - Resolved record declaration identity.
+ * @property {Expression[]} arguments - Complete field-ordered constructor arguments.
+ * @property {SourceLocation} location - Complete construction source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned record-name range.
+ */
+
+/**
+ * @typedef MemberRead
+ * @property {"MemberRead"} kind - Nominal immutable record-field read.
+ * @property {Expression} receiver - Record-valued receiver.
+ * @property {string} field - Stable resolved field identity after frontend validation.
+ * @property {SourceLocation} location - Complete member-read source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned member-name range.
+ */
+
+/**
+ * @typedef ErrorMessageRead
+ * @property {"ErrorMessageRead"} kind - The sole portable error member operation.
+ * @property {IdentifierExpression} receiver - Catch binding whose immutable message is read.
+ * @property {SourceLocation} location - Complete message-read source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned message-member range.
+ */
+
+/** @typedef {IdentifierExpression | ReceiverExpression | IntegerLiteral | BooleanLiteral | StringLiteral | OptionalNone | OptionalSome | OptionalIsPresent | OptionalUnwrap | ListLiteral | MapLiteral | OrderedMapLiteral | ListIndexExpression | MapLookupExpression | CollectionSizeExpression | UnaryExpression | BinaryExpression | CallExpression | EffectCallExpression | OwnedMoveExpression | OwnedBorrowExpression | MethodCallExpression | ReferenceConstruction | RecordConstruction | MemberRead | PrivateFieldRead | ErrorMessageRead} Expression */
 
 /**
  * @typedef LocalDeclaration
  * @property {"LocalDeclaration"} kind - Node discriminator.
  * @property {string} name - Declared local name.
- * @property {TypeReference} type - Explicit local type.
+ * @property {SemanticValueType} type - Explicit local type.
  * @property {boolean} mutable - Whether later assignment is allowed.
  * @property {Expression} initializer - Required initializer expression.
  * @property {SourceLocation} location - Declaration source location.
@@ -370,10 +836,28 @@
  * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
  */
 
+/**
+ * @typedef PrivateFieldWriteStatement
+ * @property {"PrivateFieldWriteStatement"} kind - Declaring-receiver-only private field mutation.
+ * @property {ReceiverExpression} receiver - Exact declaring receiver.
+ * @property {string} field - Stable private field identity.
+ * @property {Expression} expression - New field value.
+ * @property {SourceLocation} location - Assignment source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned field-name range.
+ */
+
 /**
  * @typedef ReturnStatement
  * @property {"ReturnStatement"} kind - Node discriminator.
- * @property {Expression} expression - Returned expression.
+ * @property {Expression} [expression] - Returned expression; absent exactly for a bare void return.
+ * @property {SourceLocation} location - Source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
+ */
+
+/**
+ * @typedef ExpressionStatement
+ * @property {"ExpressionStatement"} kind - Node discriminator.
+ * @property {CallExpression | MethodCallExpression | EffectCallExpression} expression - A direct, receiver, or authorized call whose resolved return type is void.
  * @property {SourceLocation} location - Source location.
  * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
  */
@@ -388,8 +872,105 @@
  * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
  */
 
+/**
+ * @typedef ValueBinding
+ * @property {"ValueBinding"} kind - Iteration-binding discriminator.
+ * @property {string} name - Body-local binding name.
+ * @property {SemanticValueType} type - Exact list element type.
+ * @property {false} mutable - Iteration bindings are always immutable.
+ * @property {SourceLocation} location - Binding source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
+ */
+
+/**
+ * @typedef ForEachStatement
+ * @property {"ForEachStatement"} kind - Ordered list-iteration discriminator.
+ * @property {string} [id] - Deterministic module-local loop identity, required after frontend validation.
+ * @property {Expression} list - List expression evaluated exactly once before traversal.
+ * @property {ValueBinding} valueBinding - Immutable binding scoped to the body.
+ * @property {Block} body - Loop body.
+ * @property {SourceLocation} location - Complete loop source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
+ */
+
+/**
+ * @typedef ForEachMapStatement
+ * @property {"ForEachMapStatement"} kind - Insertion-ordered map pair-iteration discriminator.
+ * @property {string} [id] - Deterministic module-local loop identity, required after frontend validation.
+ * @property {Expression} map - Ordered-map expression evaluated exactly once before traversal.
+ * @property {ValueBinding} keyBinding - Immutable string-key binding scoped to the body.
+ * @property {ValueBinding} valueBinding - Immutable homogeneous value binding scoped to the body.
+ * @property {Block} body - Loop body.
+ * @property {SourceLocation} location - Complete loop source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
+ */
+
+/**
+ * @typedef WhileStatement
+ * @property {"WhileStatement"} kind - Strict-Boolean pre-condition loop discriminator.
+ * @property {string} [id] - Deterministic module-local loop identity, required after frontend validation.
+ * @property {Expression} condition - Boolean expression evaluated before every iteration.
+ * @property {Block} body - Ordered loop body.
+ * @property {SourceLocation} location - Complete loop source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
+ */
+
+/**
+ * @typedef BreakStatement
+ * @property {"BreakStatement"} kind - Nearest-loop break discriminator.
+ * @property {string} [targetLoopId] - Resolved nearest-loop identity, required after frontend validation in loop context.
+ * @property {SourceLocation} location - Keyword source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
+ */
+
+/**
+ * @typedef ContinueStatement
+ * @property {"ContinueStatement"} kind - Nearest-loop continue discriminator.
+ * @property {string} [targetLoopId] - Resolved nearest-loop identity, required after frontend validation in loop context.
+ * @property {SourceLocation} location - Keyword source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
+ */
+
+/**
+ * @typedef ErrorConstruction
+ * @property {"ErrorConstruction"} kind - Construction of one declared unchecked error.
+ * @property {ErrorType} error - Exact nominal error type.
+ * @property {Expression} message - Sole immutable string payload.
+ * @property {SourceLocation} location - Complete construction source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned type and message ranges.
+ */
+
+/**
+ * @typedef RaiseStatement
+ * @property {"RaiseStatement"} kind - Abrupt unchecked-error propagation.
+ * @property {ErrorConstruction} error - Exact constructed semantic error.
+ * @property {SourceLocation} location - Complete raise source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned raise range.
+ */
+
+/**
+ * @typedef CatchBinding
+ * @property {"CatchBinding"} kind - Exact-handler binding discriminator.
+ * @property {string} name - Handler-local binding name.
+ * @property {ErrorType} type - Exact caught nominal error type.
+ * @property {false} mutable - Catch bindings are immutable.
+ * @property {SourceLocation} location - Binding source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned binding range.
+ */
+
+/**
+ * @typedef TryStatement
+ * @property {"TryStatement"} kind - One body and one exact typed handler.
+ * @property {Block} body - Protected body.
+ * @property {ErrorType} catchType - Exact caught nominal error type.
+ * @property {CatchBinding} catchBinding - Immutable handler-local binding.
+ * @property {Block} catchBody - Handler body.
+ * @property {SourceLocation} location - Complete try/handler source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned try/catch ranges.
+ */
+
 /** @typedef {LocalDeclaration | AssignmentStatement} LocalStatement */
-/** @typedef {LocalStatement | IfStatement | ReturnStatement | PrintStatement} Statement */
+/** @typedef {LocalStatement | PrivateFieldWriteStatement | ExpressionStatement | IfStatement | ForEachStatement | ForEachMapStatement | WhileStatement | BreakStatement | ContinueStatement | ReturnStatement | PrintStatement | RaiseStatement | TryStatement} Statement */
 
 /**
  * @typedef Block
@@ -402,14 +983,95 @@
 /**
  * @typedef FunctionDeclaration
  * @property {"FunctionDeclaration"} kind - Node discriminator.
+ * @property {string} [id] - Deterministic module-local declaration identity, required after frontend validation.
  * @property {string} name - Function name.
+ * @property {TypeParameter[]} [typeParameters] - Ordered declaration-scoped invariant unbounded parameters.
  * @property {Parameter[]} parameters - Function parameters.
- * @property {TypeReference} returnType - Return type.
+ * @property {SemanticFunctionReturnType} returnType - Return type.
  * @property {Block} body - Function body.
  * @property {SourceLocation} location - Source location.
  * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
  */
 
+/**
+ * @typedef RecordField
+ * @property {"RecordField"} kind - Closed record-field discriminator.
+ * @property {string} [id] - Stable module-local field identity, required after frontend validation.
+ * @property {string} name - Field name.
+ * @property {SemanticValueType} type - Exact field type.
+ * @property {SourceLocation} location - Field declaration source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned name/type ranges.
+ */
+
+/**
+ * @typedef RecordDeclaration
+ * @property {"RecordDeclaration"} kind - Nominal closed immutable record declaration.
+ * @property {string} [id] - Stable module-local declaration identity, required after frontend validation.
+ * @property {string} name - Record name.
+ * @property {TypeParameter[]} [typeParameters] - Ordered declaration-scoped invariant unbounded parameters.
+ * @property {RecordField[]} fields - Ordered unique visible fields.
+ * @property {SourceLocation} location - Complete declaration source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned declaration-name range.
+ */
+
+/**
+ * @typedef PrivateField
+ * @property {"PrivateField"} kind - Declaring-class-private mutable instance field.
+ * @property {string} [id] - Stable class-scoped field identity, required after validation.
+ * @property {string} name - Source-visible field name inside the declaring class only.
+ * @property {SemanticValueType} type - Exact field type.
+ * @property {SourceLocation} location - Field declaration location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned name/type ranges.
+ */
+
+/**
+ * @typedef ConstructorDeclaration
+ * @property {"ConstructorDeclaration"} kind - Exact complete private-state initializer.
+ * @property {string} [id] - Stable class-scoped constructor identity, required after validation.
+ * @property {Parameter[]} parameters - Exact positional constructor signature.
+ * @property {Block} body - Field-order initialization body.
+ * @property {readonly ["host"]} [effects] - Inferred checked host-effect fact.
+ * @property {string[]} [failureIds] - Ordered capability failures reachable through construction.
+ * @property {SourceLocation} location - Complete constructor location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned constructor range.
+ */
+
+/**
+ * @typedef MethodDeclaration
+ * @property {"MethodDeclaration"} kind - Receiver-bound class method.
+ * @property {string} [id] - Stable class-scoped method identity, required after validation.
+ * @property {string} name - Source-visible method name.
+ * @property {Parameter[]} parameters - Exact positional method signature.
+ * @property {SemanticFunctionReturnType} returnType - Exact return type.
+ * @property {Block} body - Method body.
+ * @property {readonly ["host"]} [effects] - Inferred checked host-effect fact.
+ * @property {string[]} [failureIds] - Ordered capability failures reachable through the method.
+ * @property {SourceLocation} location - Complete method location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned method-name range.
+ */
+
+/**
+ * @typedef ClassDeclaration
+ * @property {"ClassDeclaration"} kind - Nominal reference class with private mutable state.
+ * @property {string} [id] - Stable module-local class identity, required after validation.
+ * @property {string} name - Source-visible class name.
+ * @property {PrivateField[]} fields - Ordered private instance state.
+ * @property {ConstructorDeclaration} constructor - Sole exact constructor.
+ * @property {MethodDeclaration[]} methods - Ordered receiver methods.
+ * @property {{kind: "ordinary"} | {kind: "ownedResource", fieldId: string, resourceId: string}} [ownership] - Explicit class ownership profile.
+ * @property {SourceLocation} location - Complete class location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned class-name range.
+ */
+
+/**
+ * @typedef ErrorDeclaration
+ * @property {"ErrorDeclaration"} kind - Nominal unchecked error with one immutable string message.
+ * @property {string} [id] - Stable module-local declaration identity, required after frontend validation.
+ * @property {string} name - Error type name.
+ * @property {SourceLocation} location - Complete declaration source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned declaration-name range.
+ */
+
 /**
  * @typedef PrintStatement
  * @property {"PrintStatement"} kind - Node discriminator.
@@ -429,6 +1091,10 @@
 /**
  * @typedef SemanticModule
  * @property {"Module"} kind - Node discriminator.
+ * @property {RecordDeclaration[]} [records] - Top-level nominal record declarations in source order; omitted when empty.
+ * @property {ClassDeclaration[]} [classes] - Top-level nominal reference classes in source order; omitted when empty.
+ * @property {ErrorDeclaration[]} [errors] - Top-level nominal unchecked error declarations in source order; omitted when empty.
+ * @property {EffectCapabilityDeclaration[]} [capabilities] - Compiler-authorized Task 034 declarations; omission is the legacy empty set.
  * @property {FunctionDeclaration[]} functions - Top-level functions.
  * @property {EntryPoint} entryPoint - Executable entry point.
  * @property {SourceLocation} location - Source location.
@@ -436,7 +1102,92 @@
  * @property {SemanticProvenance} [provenance] - Parser-authored source and identity index; optional for legacy caller-authored modules.
  */
 
-/** @typedef {SemanticModule | FunctionDeclaration | Parameter | Block | Statement | EntryPoint | Expression | TypeReference} SemanticNode */
+/**
+ * @typedef SemanticImport
+ * @property {"Import"} kind - Node discriminator.
+ * @property {string} moduleId - Stable imported semantic module identity.
+ * @property {string} importedName - Exported declaration name in the source module.
+ * @property {string} localName - Binding name visible in the importing module.
+ * @property {SemanticDeclarationKind} symbolKind - Imported declaration namespace.
+ * @property {string} declarationId - Stable resolved declaration identity.
+ * @property {boolean} typeOnly - Whether source syntax admitted only type-position use.
+ * @property {SourceLocation} location - Complete import declaration/specifier location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned import ranges.
+ * @property {StdlibFacadeResolutionEvidence} [stdlibFacade] - Exact parser-proved native facade identity evidence.
+ */
+
+/**
+ * @typedef StdlibFacadeResolutionEvidence
+ * @property {"SemantifoldStdlibFacadeResolution"} schema - Evidence schema.
+ * @property {1} version - Evidence version.
+ * @property {string} facadeIdentity - Selected facade identity.
+ * @property {string} facadeVersion - Selected exact facade version.
+ * @property {string} nativeModule - Parser-proved source stdlib module identity.
+ * @property {string} nativeSymbol - Parser-proved source stdlib symbol identity.
+ */
+
+/**
+ * @typedef SemanticExport
+ * @property {"Export"} kind - Node discriminator.
+ * @property {string} exportedName - Name visible to importing modules.
+ * @property {SemanticDeclarationKind} symbolKind - Exported declaration namespace.
+ * @property {string} declarationId - Stable exported declaration identity.
+ * @property {SourceLocation} location - Complete export declaration/specifier location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Parser-owned export ranges.
+ */
+
+/**
+ * @typedef SemanticProgramModule
+ * @property {"Module"} kind - Node discriminator.
+ * @property {string} id - Stable caller-supplied logical module identity.
+ * @property {string} sourceFilename - Explicit source filename; never an implicit read request.
+ * @property {RecordDeclaration[]} [records] - Top-level nominal record declarations.
+ * @property {ClassDeclaration[]} [classes] - Compiler-owned facade reference classes.
+ * @property {ErrorDeclaration[]} [errors] - Top-level nominal unchecked error declarations.
+ * @property {FunctionDeclaration[]} functions - Top-level functions.
+ * @property {SemanticImport[]} imports - Resolved imports in source order.
+ * @property {SemanticExport[]} exports - Resolved exports in source order.
+ * @property {EffectCapabilityDeclaration[]} [capabilities] - Authority declarations shared by reference when the program declares a standard-library contract.
+ * @property {EntryPoint} [entryPoint] - Sole executable entry point, present only on the selected module.
+ * @property {SourceLocation} location - Source location.
+ * @property {SemanticNodeSourceProvenance} [sourceProvenance] - Node-associated provenance.
+ * @property {SemanticProvenance} [provenance] - Parser-authored source and identity index.
+ * @property {{identity: string, version: string}} [stdlibFacade] - Selected compiler-owned facade module identity.
+ */
+
+/**
+ * @typedef StdlibFacadeProgramModuleDescriptor
+ * @property {{identity: string, range: string}[]} dependencies - Versioned facade dependencies.
+ * @property {string} identity - Facade identity.
+ * @property {({identity: string, kind: "module", symbols: string[]} | {forms: ("unqualified-call" | "receiver-call")[], identity: string, kind: "builtin", symbols: string[]})[]} nativeModules - Exact native source identities.
+ * @property {({effects: string[], failures: string[], forms: ("direct-call" | "unqualified-call" | "receiver-call")[], kind: "function", name: string, ownership: "not-applicable", parameters: {name: string, type: string}[], returnType: string} | {constructor: {effects: string[], failures: string[], ownership: "acquired", parameters: {name: string, type: string}[]}, forms: ["constructor-call"], kind: "class", methods: {effects: string[], failures: string[], forms: ["receiver-call"], name: string, ownership: "borrowed" | "consumed", parameters: {name: string, type: string}[], returnType: string}[], name: string, ownership: "owned-reference"})[]} publicDeclarations - Public source declarations.
+ * @property {{module: string, operations: string[], range: string}[]} requirements - Canonical capability requirements.
+ * @property {string} runtimeProfile - Exact source runtime profile.
+ * @property {string} sourceModule - Compiler-owned semantic module identity.
+ * @property {string} version - Exact facade version.
+ * @property {"internal" | "public"} visibility - Native-selectable visibility.
+ */
+
+/**
+ * @typedef StdlibFacadeProgramDescriptor
+ * @property {"SemantifoldStdlibFacades"} schema - Facade descriptor schema.
+ * @property {1} version - Facade descriptor version.
+ * @property {SemanticLanguage} language - Source-language compatibility profile.
+ * @property {StdlibFacadeProgramModuleDescriptor[]} modules - Dependency-first selected executable closure.
+ */
+
+/**
+ * @typedef SemanticProgram
+ * @property {"Program"} kind - Node discriminator.
+ * @property {SemanticProgramModule[]} modules - Dependency-first deterministic module order.
+ * @property {string} entryModule - Stable identity of the sole entry module.
+ * @property {RegisteredSource[]} sources - Caller-order complete source registry.
+ * @property {{contractVersion?: string, identity: string}} [stdlibContract] - Declared standard-library contract; plain, never frozen.
+ * @property {{contractVersion?: string, identity: string}[]} [stdlibContracts] - Ordered declared standard-library contracts; plain, never frozen.
+ * @property {StdlibFacadeProgramDescriptor} [stdlibFacades] - Complete selected source-language facade closure.
+ */
+
+/** @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 */
 /** @typedef {SemanticNode} SemanticNodeWithoutLocations */
 
 export {}