refactor: add DesignIR distillation pipeline

2026-07-27 17:24:04 +08:00
parent 0adaac2b2a
commit 550b339bcc
1128 changed files with 10248 additions and 426666 deletions
@@ -0,0 +1,81 @@
+# Case JSON input contract
+
+Case JSON is private evidence used only during induction. It may contain exact
+parameters, but the inducer never copies those fields into published experience.
+Store source STEP files in `workspace/teacher/inbox` and generated private
+evidence in `workspace/teacher/evidence`.
+
+Do not pass either folder or a case JSON to cad-router or a CAD backend.
+Creation, modification, and reconstruction may consume only the promoted public
+experience library.
+
+Supported fields:
+
+```json
+{
+  "provenance": {"source_sha256": "..."},
+  "design_ir": {
+    "part_family": "flanged_hub_adapter",
+    "features": [{"type": "base_flange"}, {"type": "hollow_sleeve"}],
+    "constraints": [{"id": "coaxial_stack", "type": "coaxial"}],
+    "reconstruction_evidence": {
+      "parameter_roles": ["overall_long_span", "coaxial_diameter_roles"],
+      "datum_roles": ["part_center", "primary_axis"],
+      "feature_roles": ["rotational_body", "coaxial_cylindrical_stack"],
+      "relation_roles": ["coaxial_stack"],
+      "canonical_stages": [
+        {
+          "id": "establish_reference_frame",
+          "operation": "define_datums",
+          "feature_roles": [],
+          "reference_roles": ["part_center", "primary_axis"]
+        }
+      ],
+      "private_cardinality_evidence": {
+        "feature_role_count": 5,
+        "feature_role_count_class": "repeated"
+      },
+      "validation_roles": ["closed_solid", "coaxial_stack"]
+    },
+    "normalized_observations": [
+      {
+        "name": "sleeve_od_to_base_od",
+        "value": 0.35,
+        "numerator_role": "sleeve_outer_diameter",
+        "denominator_role": "base_outer_diameter"
+      }
+    ]
+  },
+  "experience": {
+    "rules": [
+      {
+        "id": "bound_counterbore_to_host",
+        "scope": ["counterbore"],
+        "statement": "Terminate a counterbore at its host boundary.",
+        "repair": "Bind the cutter extent to the host feature."
+      }
+    ],
+    "validation_targets": [
+      {
+        "id": "counterbore_host_boundary",
+        "check": "A counterbore does not cross an unrelated adjacent feature."
+      }
+    ]
+  }
+}
+```
+
+Rules and checks containing numeric literals are rejected because they are
+likely instance answers. Ratios are accepted only through
+`normalized_observations`, with an explicit numerator and denominator role.
+
+Legacy distilled JSON can be used when it contains the fields above. Exact
+`parameters`, `evidence`, centers, axes, and surface references are ignored.
+
+V3 extractor output should also provide several independent semantic signals
+per case: body-aspect class, topology-complexity role, analytic feature
+networks, part family, relationship candidates, and role-named dimensionless
+observations. It additionally provides symbolic reconstruction roles, canonical
+reconstruction stages, and private exact cardinality evidence. Sanitization
+converts exact counts into qualitative classes before LLM review. Do not encode
+an absolute source dimension as a feature token.
@@ -0,0 +1,84 @@
+# Published experience library
+
+The published library uses schema version `2.0` and contains only promoted,
+generalized experience:
+
+```json
+{
+  "schema_version": "2.0",
+  "library_kind": "generalized_cad_experience",
+  "induction_mode": "llm_proposals_with_deterministic_evidence_verification",
+  "policy": {
+    "instance_parameters_allowed": false,
+    "absolute_coordinates_allowed": false,
+    "llm_semantic_review_required": true,
+    "draft_evidence_verified": true,
+    "router_consumable": true,
+    "minimum_support": 20
+  },
+  "corpus_summary": {
+    "accepted_case_count": 1000,
+    "duplicate_case_count": 12
+  },
+  "experience_summary": {
+    "llm_proposal_count": 24,
+    "promoted_experience_count": 18,
+    "candidate_experience_count": 6,
+    "by_kind": [{"kind": "feature_motif", "count": 7}],
+    "by_scope": [{"scope": "flanged_hub_adapter", "count": 5}]
+  },
+  "experiences": [
+    {
+      "id": "motif.base_flange+hollow_sleeve",
+      "kind": "feature_motif",
+      "scope": ["flanged_hub_adapter"],
+      "when": {"features": ["base_flange", "hollow_sleeve"]},
+      "guidance": "Treat these feature roles as a reusable composition.",
+      "support": 243,
+      "confidence": 0.91
+    }
+  ],
+  "candidate_experiences": [
+    {
+      "id": "motif.flanged_hub_adapter.base_flange+hollow_sleeve",
+      "kind": "feature_motif",
+      "scope": ["flanged_hub_adapter"],
+      "when": {"features": ["base_flange", "hollow_sleeve"]},
+      "support": 7,
+      "required_support": 20,
+      "remaining_support": 13,
+      "promotion_state": "candidate",
+      "consumer_policy": "visible_for_review_but_not_available_to_cad_router"
+    }
+  ]
+}
+```
+
+Allowed numeric values describe evidence strength or dimensionless
+distributions: support counts, confidence, frequency, percentiles, and sample
+counts. Absolute lengths, diameters, heights, radii, angles tied to a single
+case, positions, and coordinates are forbidden.
+
+Consumers query this library by requested family and feature vocabulary. They
+must not receive the induction corpus, private case JSON, or
+`candidate_experiences`. Only `experiences` is executable guidance.
+
+## Reconstruction grammar
+
+`reconstruction_grammar` is the executable bridge between generalized
+experience and a backend-neutral design plan. It may contain only:
+
+- symbolic `parameter_roles`;
+- symbolic `datum_roles`;
+- required or optional semantic feature and relation roles;
+- canonical stages with tokenized operation, feature, and reference roles;
+- qualitative cardinality classes such as `single`, `paired`, `repeated`, or
+  `dense`;
+- validation roles.
+
+It must not contain parameter values, exact member counts, absolute
+coordinates, source identifiers, face references, or executable teacher
+geometry. The publisher verifies that every promoted role and stage is present
+in enough independent private cases. A consumer instantiates the grammar using
+the user's dimensions, inferred dimensionless distributions, and backend
+operations.
@@ -0,0 +1,97 @@
+# LLM semantic review contract
+
+Read the sanitized `work/review/semantic-batch.json`, not raw STEP geometry.
+Maintain stable proposal identifiers when an existing candidate expresses the
+same method.
+
+Write `work/review/experience-draft.json` with this shape:
+
+```json
+{
+  "schema_version": "1.0",
+  "draft_kind": "llm_generalized_experience_proposals",
+  "proposals": [
+    {
+      "id": "constraint.part_family.shared_axis",
+      "kind": "constraint",
+      "scope": ["part_family"],
+      "evidence_query": {
+        "required_features": ["rotational_body", "central_passage"],
+        "required_relations": ["dominant_axis_alignment"],
+        "context_features": ["rotational_body", "central_passage"]
+      },
+      "guidance": "Preserve a shared axis across the participating feature roles.",
+      "semantic_rationale": "The relationship remains meaningful when individual dimensions change.",
+      "check": "Confirm that participating features retain their intended common axis."
+    }
+  ]
+}
+```
+
+Allowed kinds are `feature_motif`, `constraint`, `design_rule`,
+`validation_rule`, `failure_repair`, `dimensionless_distribution`, and
+`reconstruction_grammar`.
+Distribution proposals also provide `observation_name`; the publisher computes
+the distribution from private evidence and never accepts values from the draft.
+
+A `reconstruction_grammar` proposal must additionally contain symbolic,
+number-free reconstruction content:
+
+```json
+{
+  "id": "reconstruction.patterned_prismatic_part.primary",
+  "kind": "reconstruction_grammar",
+  "scope": ["patterned_prismatic_part"],
+  "evidence_query": {
+    "required_features": ["planar_dominant_body", "cylindrical_feature_network"],
+    "required_relations": [],
+    "context_features": ["planar_dominant_body"]
+  },
+  "guidance": "Build a datum-driven envelope before adding the passage network and repeated features.",
+  "semantic_rationale": "The staged method transfers across dimensional variants while preserving feature relationships.",
+  "reconstruction_grammar": {
+    "parameter_roles": ["overall_long_span", "overall_middle_span", "overall_short_span"],
+    "datum_roles": ["part_center", "primary_axis", "primary_transverse_plane"],
+    "feature_roles": ["planar_dominant_body", "cylindrical_feature_network"],
+    "relation_roles": [],
+    "canonical_stages": [
+      {
+        "id": "establish_reference_frame",
+        "operation": "define_datums",
+        "feature_roles": [],
+        "reference_roles": ["part_center", "primary_axis"]
+      },
+      {
+        "id": "construct_primary_envelope",
+        "operation": "extrude_profile",
+        "feature_roles": ["planar_dominant_body"],
+        "reference_roles": ["part_center", "primary_axis"]
+      }
+    ],
+    "cardinality_classes": ["plane_dense", "cylinder_dense"],
+    "validation_roles": ["closed_solid", "surface_mix_consistency"]
+  }
+}
+```
+
+Follow these rules:
+
+- Require an evidence query composed only of semantic feature and relation
+  tokens present in the sanitized batch.
+- Use scopes to prevent unrelated part families from supporting a proposal.
+- Use `context_features` to define the conditional population used for
+  confidence, so a valid subtype method is not diluted by unrelated variants
+  in the same broad family.
+- Explain why a proposal transfers across dimensions and variants.
+- Avoid dimensions, coordinates, source identifiers, face references, and
+  numeric literals in prose.
+- Do not infer build order or causal failure mechanisms from final geometry.
+- Treat `canonical_stages` as a recommended reconstruction order, never as a
+  claim about the source CAD history.
+- For reconstruction grammars, retain only roles and stages repeated by the
+  scoped evidence. Do not insert family knowledge that the sanitized batch
+  does not support.
+- Prefer a small set of meaningful methods over every possible feature pair.
+- Preserve earlier proposal IDs when evidence still supports the same meaning.
+- Let the publisher calculate support and confidence; never claim them in the
+  draft.