pycforge 0.15.2__py3-none-any.whl

pycforge/converter/records/model.py

@@ -0,0 +1,319 @@
+"""Immutable facts for the Phase 13 bounded static-record profile.
+
+This module deliberately describes source semantics only.  It has no C IR,
+renderer, allocation, or runtime dependency, which keeps the representation
+gate independently testable before lowering is enabled.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+from pycforge.converter.analysis.model import ValueCategory
+
+
+MAX_RECORD_FIELDS = 64
+
+
+class RecordValueCategory(str, Enum):
+    DEFINITION = "immutable-static-record-definition"
+    INSTANCE = "immutable-static-record-like"
+
+
+class RecordAnalysisError(Exception):
+    """Deterministic source rejection raised by static-record analysis."""
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        *,
+        node_id: str,
+        module_id: str,
+        document_id: str,
+        logical_name: str,
+        source_span: dict[str, Any] | None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.node_id = node_id
+        self.module_id = module_id
+        self.document_id = document_id
+        self.logical_name = logical_name
+        self.source_span = source_span
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "code": self.code,
+            "message": self.message,
+            "node_id": self.node_id,
+            "module_id": self.module_id,
+            "document_id": self.document_id,
+            "logical_name": self.logical_name,
+            "source_span": self.source_span,
+        }
+
+
+class RecordAnalysisCanceled(Exception):
+    """Internal cooperative-cancellation signal for static-record analysis."""
+
+
+@dataclass(frozen=True, slots=True)
+class RecordDefinitionFact:
+    record_id: str
+    class_node_id: str
+    class_binding_id: str
+    source_name: str
+    flattened_name: str
+    module_id: str
+    document_id: str
+    logical_name: str
+    field_ids: tuple[str, ...]
+    initializer_id: str
+    category: RecordValueCategory
+    storage_model: str
+    ownership_model: str
+    lifetime_model: str
+    aliasing_model: str
+    cleanup_model: str
+    nullability_model: str
+    mutable: bool
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "record_id": self.record_id,
+            "class_node_id": self.class_node_id,
+            "class_binding_id": self.class_binding_id,
+            "source_name": self.source_name,
+            "flattened_name": self.flattened_name,
+            "module_id": self.module_id,
+            "document_id": self.document_id,
+            "logical_name": self.logical_name,
+            "field_ids": list(self.field_ids),
+            "initializer_id": self.initializer_id,
+            "category": self.category.value,
+            "storage_model": self.storage_model,
+            "ownership_model": self.ownership_model,
+            "lifetime_model": self.lifetime_model,
+            "aliasing_model": self.aliasing_model,
+            "cleanup_model": self.cleanup_model,
+            "nullability_model": self.nullability_model,
+            "mutable": self.mutable,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class RecordFieldFact:
+    field_id: str
+    record_id: str
+    class_node_id: str
+    declaration_node_id: str
+    target_node_id: str
+    annotation_node_id: str
+    source_name: str
+    ordinal: int
+    category: ValueCategory
+    module_id: str
+    document_id: str
+    logical_name: str
+    mutable: bool
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "field_id": self.field_id,
+            "record_id": self.record_id,
+            "class_node_id": self.class_node_id,
+            "declaration_node_id": self.declaration_node_id,
+            "target_node_id": self.target_node_id,
+            "annotation_node_id": self.annotation_node_id,
+            "source_name": self.source_name,
+            "ordinal": self.ordinal,
+            "category": self.category.value,
+            "module_id": self.module_id,
+            "document_id": self.document_id,
+            "logical_name": self.logical_name,
+            "mutable": self.mutable,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class RecordInitializerFact:
+    initializer_id: str
+    record_id: str
+    function_node_id: str
+    arguments_node_id: str
+    self_parameter_node_id: str
+    parameter_node_ids: tuple[str, ...]
+    assignment_node_ids: tuple[str, ...]
+    field_ids: tuple[str, ...]
+    module_id: str
+    document_id: str
+    logical_name: str
+    receiver_model: str
+    evaluation_order: str
+    initialization_completeness: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "initializer_id": self.initializer_id,
+            "record_id": self.record_id,
+            "function_node_id": self.function_node_id,
+            "arguments_node_id": self.arguments_node_id,
+            "self_parameter_node_id": self.self_parameter_node_id,
+            "parameter_node_ids": list(self.parameter_node_ids),
+            "assignment_node_ids": list(self.assignment_node_ids),
+            "field_ids": list(self.field_ids),
+            "module_id": self.module_id,
+            "document_id": self.document_id,
+            "logical_name": self.logical_name,
+            "receiver_model": self.receiver_model,
+            "evaluation_order": self.evaluation_order,
+            "initialization_completeness": self.initialization_completeness,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class RecordInstanceFact:
+    instance_id: str
+    record_id: str
+    class_node_id: str
+    owner_function_node_id: str
+    construction_node_id: str
+    assignment_node_id: str
+    target_node_id: str
+    binding_id: str
+    source_name: str
+    argument_node_ids: tuple[str, ...]
+    module_id: str
+    document_id: str
+    logical_name: str
+    category: RecordValueCategory
+    storage_model: str
+    ownership_model: str
+    lifetime_model: str
+    aliasing_model: str
+    cleanup_model: str
+    nullability_model: str
+    allocation_model: str
+    mutable: bool
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "instance_id": self.instance_id,
+            "record_id": self.record_id,
+            "class_node_id": self.class_node_id,
+            "owner_function_node_id": self.owner_function_node_id,
+            "construction_node_id": self.construction_node_id,
+            "assignment_node_id": self.assignment_node_id,
+            "target_node_id": self.target_node_id,
+            "binding_id": self.binding_id,
+            "source_name": self.source_name,
+            "argument_node_ids": list(self.argument_node_ids),
+            "module_id": self.module_id,
+            "document_id": self.document_id,
+            "logical_name": self.logical_name,
+            "category": self.category.value,
+            "storage_model": self.storage_model,
+            "ownership_model": self.ownership_model,
+            "lifetime_model": self.lifetime_model,
+            "aliasing_model": self.aliasing_model,
+            "cleanup_model": self.cleanup_model,
+            "nullability_model": self.nullability_model,
+            "allocation_model": self.allocation_model,
+            "mutable": self.mutable,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class RecordInstanceBindingFact:
+    binding_id: str
+    instance_id: str
+    record_id: str
+    source_name: str
+    declaration_node_id: str
+    occurrence_node_ids: tuple[str, ...]
+    allowed_field_access_node_ids: tuple[str, ...]
+    owner_function_node_id: str
+    module_id: str
+    document_id: str
+    logical_name: str
+    category: RecordValueCategory
+    single_assignment: bool
+    noalias: bool
+    escapes: bool
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "binding_id": self.binding_id,
+            "instance_id": self.instance_id,
+            "record_id": self.record_id,
+            "source_name": self.source_name,
+            "declaration_node_id": self.declaration_node_id,
+            "occurrence_node_ids": list(self.occurrence_node_ids),
+            "allowed_field_access_node_ids": list(self.allowed_field_access_node_ids),
+            "owner_function_node_id": self.owner_function_node_id,
+            "module_id": self.module_id,
+            "document_id": self.document_id,
+            "logical_name": self.logical_name,
+            "category": self.category.value,
+            "single_assignment": self.single_assignment,
+            "noalias": self.noalias,
+            "escapes": self.escapes,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class RecordFieldAccessFact:
+    access_node_id: str
+    instance_id: str
+    binding_id: str
+    record_id: str
+    field_id: str
+    field_name: str
+    field_category: ValueCategory
+    owner_function_node_id: str
+    module_id: str
+    document_id: str
+    logical_name: str
+    access_mode: str
+    statically_bound: bool
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "access_node_id": self.access_node_id,
+            "instance_id": self.instance_id,
+            "binding_id": self.binding_id,
+            "record_id": self.record_id,
+            "field_id": self.field_id,
+            "field_name": self.field_name,
+            "field_category": self.field_category.value,
+            "owner_function_node_id": self.owner_function_node_id,
+            "module_id": self.module_id,
+            "document_id": self.document_id,
+            "logical_name": self.logical_name,
+            "access_mode": self.access_mode,
+            "statically_bound": self.statically_bound,
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class StaticRecordAnalysis:
+    definitions: tuple[RecordDefinitionFact, ...]
+    fields: tuple[RecordFieldFact, ...]
+    initializers: tuple[RecordInitializerFact, ...]
+    instances: tuple[RecordInstanceFact, ...]
+    bindings: tuple[RecordInstanceBindingFact, ...]
+    accesses: tuple[RecordFieldAccessFact, ...]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "definitions": [item.to_dict() for item in self.definitions],
+            "fields": [item.to_dict() for item in self.fields],
+            "initializers": [item.to_dict() for item in self.initializers],
+            "instances": [item.to_dict() for item in self.instances],
+            "bindings": [item.to_dict() for item in self.bindings],
+            "accesses": [item.to_dict() for item in self.accesses],
+        }

pycforge/converter/rules/__init__.py

@@ -0,0 +1,3 @@
+"""Phase 5 rule-planning contracts. Rules create immutable RulePlans only; lowering begins in Phase 6."""
+from pycforge.converter.analysis.planning import FrozenRuleRegistry, RuleDefinition, RulePlan, default_registry
+__all__ = ["FrozenRuleRegistry", "RuleDefinition", "RulePlan", "default_registry"]

pycforge/converter/support_templates/__init__.py

@@ -0,0 +1,49 @@
+"""Trusted Phase 10 support-template infrastructure."""
+
+from .assembly import assemble_translation_unit
+from .factories import (
+    FLOOR_DIV_REFERENCE,
+    FLOOR_MOD_REFERENCE,
+    builtin_definitions,
+    floor_div_asset,
+    floor_mod_asset,
+)
+from .model import (
+    HELPER_INTERFACE_ID,
+    HELPER_REGISTRY_VERSION,
+    HelperCIRAsset,
+    HelperDefinition,
+    HelperFailureContract,
+    HelperManifestEntry,
+    HelperOwnershipContract,
+    HelperReference,
+    ResolvedHelperPlan,
+)
+from .registry import (
+    FrozenHelperRegistry,
+    HelperRegistryError,
+    HelperResolutionCanceled,
+    default_helper_registry,
+)
+
+__all__ = [
+    "FLOOR_DIV_REFERENCE",
+    "FLOOR_MOD_REFERENCE",
+    "HELPER_INTERFACE_ID",
+    "HELPER_REGISTRY_VERSION",
+    "FrozenHelperRegistry",
+    "HelperCIRAsset",
+    "HelperDefinition",
+    "HelperFailureContract",
+    "HelperManifestEntry",
+    "HelperOwnershipContract",
+    "HelperReference",
+    "HelperRegistryError",
+    "HelperResolutionCanceled",
+    "ResolvedHelperPlan",
+    "assemble_translation_unit",
+    "builtin_definitions",
+    "default_helper_registry",
+    "floor_div_asset",
+    "floor_mod_asset",
+]

pycforge/converter/support_templates/assembly.py

@@ -0,0 +1,106 @@
+"""Deterministic translation-unit assembly for resolved helper plans."""
+
+from __future__ import annotations
+
+from pycforge.converter.ir.c_ir import (
+    CFunctionDefinition,
+    CFunctionPrototype,
+    CRecordDefinition,
+    CTranslationUnit,
+    CTranslationUnitBuilder,
+    CONDITIONAL_SCHEMA_VERSION,
+    CONTAINER_SCHEMA_VERSION,
+    HELPER_SCHEMA_VERSION,
+    MODULE_SCHEMA_VERSION,
+    NUMERIC_SCHEMA_VERSION,
+    RECORD_SCHEMA_VERSION,
+    KEYWORD_CALL_SCHEMA_VERSION,
+    KEYWORD_ONLY_CALL_SCHEMA_VERSION,
+    validate_translation_unit,
+)
+
+from .model import ResolvedHelperPlan
+from .registry import HelperRegistryError
+
+
+def assemble_translation_unit(
+    source_unit: CTranslationUnit,
+    plan: ResolvedHelperPlan,
+) -> CTranslationUnit:
+    """Insert each resolved helper once without changing an empty-plan unit."""
+
+    if source_unit.target_contract != plan.target_contract:
+        raise HelperRegistryError(
+            "PYC3304",
+            "resolved helper target does not match the source translation unit",
+        )
+    if not plan.assets:
+        return source_unit
+
+    includes_by_key = {}
+    for include in sorted(
+        source_unit.includes + tuple(item for asset in plan.assets for item in asset.includes),
+        key=lambda item: (not item.system, item.header, item.node_id),
+    ):
+        includes_by_key.setdefault((include.header, include.system), include)
+
+    source_prototypes = tuple(
+        item for item in source_unit.declarations if isinstance(item, CFunctionPrototype)
+    )
+    source_definitions = tuple(
+        item for item in source_unit.declarations if isinstance(item, CFunctionDefinition)
+    )
+    source_other = tuple(
+        item
+        for item in source_unit.declarations
+        if not isinstance(item, (CFunctionPrototype, CFunctionDefinition))
+    )
+    source_records = tuple(
+        item for item in source_other if isinstance(item, CRecordDefinition)
+    )
+    source_variables = tuple(
+        item for item in source_other if not isinstance(item, CRecordDefinition)
+    )
+    helper_prototypes = tuple(asset.prototype for asset in plan.assets)
+    helper_definitions = tuple(asset.definition for asset in plan.assets)
+
+    builder = CTranslationUnitBuilder(
+        source_unit.target_contract,
+        node_id=source_unit.node_id,
+        provenance=source_unit.provenance,
+        schema_version=(
+            source_unit.schema_version
+            if source_unit.schema_version in {
+                CONTAINER_SCHEMA_VERSION,
+                MODULE_SCHEMA_VERSION,
+                RECORD_SCHEMA_VERSION,
+                NUMERIC_SCHEMA_VERSION,
+                CONDITIONAL_SCHEMA_VERSION,
+                KEYWORD_CALL_SCHEMA_VERSION,
+                KEYWORD_ONLY_CALL_SCHEMA_VERSION,
+            }
+            else HELPER_SCHEMA_VERSION
+        ),
+        module_manifest=source_unit.module_manifest,
+        module_order=source_unit.module_order,
+        module_dependencies=source_unit.module_dependencies,
+    )
+    for include in includes_by_key.values():
+        builder.add_include(include)
+    for declaration in (
+        source_records
+        + helper_prototypes
+        + source_prototypes
+        + source_variables
+        + helper_definitions
+        + source_definitions
+    ):
+        builder.add_declaration(declaration)
+    assembled = builder.build()
+    validation = validate_translation_unit(assembled)
+    if not validation.accepted:
+        raise HelperRegistryError(
+            "PYC3306",
+            "helper assembly produced invalid C IR: " + "; ".join(validation.errors),
+        )
+    return assembled