code wiki / (root) / nx_object_spec_match.nx
`nx_object_spec_match.nx` source

↩ module page · 335 lines · 11771 B
1// nx_object_spec_match.nx -- spec-compliance verification.
2//
3// CAPABILITY_COMPLETENESS: FULL
4//
5// Composes:
6//   nx_object_spec (the catalog primitive)
7//   caller-provided observed_parts list (upstream: nx_part_
8//     classifier, queued)
9//
10// Algorithm:
11//   1. For each REQUIRED part in spec: check if in observed list
12//   2. For each NEGATION in spec: check if in observed list
13//   3. Classify:
14//        all required present + no negations    -> MATCHES_SPEC
15//        any negation present                   -> WRONG_CLASS
16//        some required missing + no negations   -> PART_MISSING
17//        both required missing + negations      -> PARTIAL_MATCH
18//   4. If WRONG_CLASS or PARTIAL_MATCH: scan all other specs for
19//      the best-matching alternative (highest required-presence
20//      score + no negations violated)
21//
22// genealogy_id: substrate_object_spec_match_2026_05_16
23// lineage_id:   nx_object_spec_match_v1
24
25import "nx_syscalls.nx"
26import "nx_runtime.nx"
27import "nx_tier.nx"
28import "nx_object_spec.nx"
29const NX_MAGIC_1024: i64 = 1024
30
31// ===== sealed-verdict outcomes ===================================
32
33const NX_OSM_VERDICT_MATCHES_SPEC:   nx_int = 0
34const NX_OSM_VERDICT_PART_MISSING:   nx_int = 1
35const NX_OSM_VERDICT_WRONG_CLASS:    nx_int = 2
36const NX_OSM_VERDICT_PARTIAL_MATCH:  nx_int = 3
37const NX_OSM_VERDICT_NO_OBSERVATION: nx_int = 4
38
39const NX_OSM_NO_ALTERNATIVE: nx_int = -1
40
41// ===== match result struct =======================================
42
43struct NxObjectMatchResult {
  spec_id:                nx_int,
  verdict:                nx_int,
  n_required_matched:     nx_int,
  n_required_missing:     nx_int,
  n_negations_violated:   nx_int,
  missing_parts:          *nx_int,
  n_missing:              nx_int,
  violated_negations:     *nx_int,
  n_violated:             nx_int,
  suggested_alternative:  nx_int,   // spec_id of closest match if WRONG_CLASS
  match_confidence_q10:   nx_int,   // n_matched / n_required (Q10)
55}
56
57const NX_OSM_RESULT_BYTES: nx_size = 96
58
59// ===== helpers ====================================================
60
61func _osm_in_list(list: *nx_int, n: nx_int, val: nx_int) -> nx_int {
  var i: nx_int = 0
  while i < n {
      if list[i] == val { return 1 }
      i = i + 1
  }
  return 0
68}
69
70// ===== best-alternative finder ===================================
71//
72// Score for each candidate spec:
73//   +1 per required-part observed
74//   -2 per negation observed (heavy penalty if candidate spec
75//      forbids one of the observed parts)
76//   alternative is candidate with highest score above 0 +
77//     zero negations violated
78//
79// Returns spec_id of best alternative, or NO_ALTERNATIVE if
80// no candidate scores positive.
81
82func _osm_find_alternative(
  excluded_spec_id: nx_int,
  observed_parts: *nx_int, n_observed: nx_int) -> nx_int {
85
  var best_spec: nx_int = NX_OSM_NO_ALTERNATIVE
  var best_score: nx_int = 0
  var s: nx_int = 0
  while s < NX_SPEC_N_SPECS {
      if s != excluded_spec_id {
          let candidate: *NxObjectSpec = nx_object_spec_get(s)
          if candidate != (0 as *NxObjectSpec) {
              // Count required matches.
              var score: nx_int = 0
              var has_violation: nx_int = 0
              var i: nx_int = 0
              while i < candidate.n_required {
                  let pid: nx_int = candidate.required_parts[i]
                  if _osm_in_list(observed_parts, n_observed, pid) == 1 {
                      score = score + 1
                  }
                  i = i + 1
              }
              var j: nx_int = 0
              while j < candidate.n_negations {
                  let neg_pid: nx_int = candidate.negation_parts[j]
                  if _osm_in_list(observed_parts, n_observed, neg_pid) == 1 {
                      has_violation = 1
                  }
                  j = j + 1
              }
              if has_violation == 0 {
                  if score > best_score {
                      best_score = score
                      best_spec = s
                  }
              }
          }
      }
      s = s + 1
  }
  return best_spec
123}
124
125// ===== top-level match ===========================================
126
127func nx_object_spec_match(
  spec_id: nx_int,
  observed_parts: *nx_int, n_observed: nx_int) -> *NxObjectMatchResult {
130
  let r_ptr: *u8 = sys_mmap(NX_OSM_RESULT_BYTES)
  let r: *NxObjectMatchResult = r_ptr as *NxObjectMatchResult
  r.spec_id = spec_id
  r.n_required_matched = 0
  r.n_required_missing = 0
  r.n_negations_violated = 0
  r.n_missing = 0
  r.n_violated = 0
  r.suggested_alternative = NX_OSM_NO_ALTERNATIVE
  r.match_confidence_q10 = 0
141
  let spec: *NxObjectSpec = nx_object_spec_get(spec_id)
  if spec == (0 as *NxObjectSpec) {
      r.verdict = NX_OSM_VERDICT_NO_OBSERVATION
      return r
  }
  if n_observed <= 0 {
      r.verdict = NX_OSM_VERDICT_NO_OBSERVATION
      return r
  }
151
  // Allocate output lists.
  let missing_bytes: nx_size = (spec.n_required as nx_size) * 8
  let missing: *nx_int = (sys_mmap(missing_bytes)) as *nx_int
  var miss_n: nx_int = 0
  let violated_bytes: nx_size = (spec.n_negations as nx_size) * 8
  let violated: *nx_int = (sys_mmap(violated_bytes)) as *nx_int
  var viol_n: nx_int = 0
159
  // 1. Required-part scan.
  var n_matched: nx_int = 0
  var i: nx_int = 0
  while i < spec.n_required {
      let pid: nx_int = spec.required_parts[i]
      if _osm_in_list(observed_parts, n_observed, pid) == 1 {
          n_matched = n_matched + 1
      } else {
          missing[miss_n] = pid
          miss_n = miss_n + 1
      }
      i = i + 1
  }
173
  // 2. Negation scan.
  var j: nx_int = 0
  while j < spec.n_negations {
      let neg_pid: nx_int = spec.negation_parts[j]
      if _osm_in_list(observed_parts, n_observed, neg_pid) == 1 {
          violated[viol_n] = neg_pid
          viol_n = viol_n + 1
      }
      j = j + 1
  }
184
  r.n_required_matched = n_matched
  r.n_required_missing = miss_n
  r.n_negations_violated = viol_n
  r.missing_parts = missing
  r.n_missing = miss_n
  r.violated_negations = violated
  r.n_violated = viol_n
  if spec.n_required > 0 {
      r.match_confidence_q10 = (n_matched * NX_MAGIC_1024) / spec.n_required
  } else {
      r.match_confidence_q10 = NX_MAGIC_1024
  }
197
  // 3. Classify.
  if viol_n == 0 {
      if miss_n == 0 {
          r.verdict = NX_OSM_VERDICT_MATCHES_SPEC
          return r
      }
      r.verdict = NX_OSM_VERDICT_PART_MISSING
      return r
  }
  if miss_n == 0 {
      r.verdict = NX_OSM_VERDICT_WRONG_CLASS
  } else {
      r.verdict = NX_OSM_VERDICT_PARTIAL_MATCH
  }
212
  // 4. Find best alternative for WRONG_CLASS / PARTIAL_MATCH.
  let alt: nx_int = _osm_find_alternative(spec_id, observed_parts, n_observed)
  r.suggested_alternative = alt
  return r
217}
218
219// ===== self-test =================================================
220
221func main() -> nx_int {
  // ---- CASE 1: D&D sword that IS a sword
  //
  // Observed: BLADE, EDGE, CROSSGUARD, GRIP, POMMEL, POINT
  // Spec: SWORD_LONG (requires BLADE/EDGE/CROSSGUARD/GRIP/POMMEL)
  // Expected: MATCHES_SPEC
  let obs1: *nx_int = (sys_mmap(64)) as *nx_int
  obs1[0] = NX_PT_BLADE
  obs1[1] = NX_PT_EDGE
  obs1[2] = NX_PT_CROSSGUARD
  obs1[3] = NX_PT_GRIP
  obs1[4] = NX_PT_POMMEL
  obs1[5] = NX_PT_POINT
  let r1: *NxObjectMatchResult = nx_object_spec_match(
      NX_SPEC_SWORD_LONG, obs1, 6)
  if r1 == (0 as *NxObjectMatchResult) { return 1 }
  if r1.verdict != NX_OSM_VERDICT_MATCHES_SPEC { return 2 }
  if r1.n_required_matched != 5 { return 3 }
  if r1.n_negations_violated != 0 { return 4 }
  if r1.match_confidence_q10 != NX_MAGIC_1024 { return 5 }
241
  // ---- CASE 2: "DnD sword" that's actually a bubble wand
  //
  // Observed: HANDLE_STICK, LOOP, FILM
  // Spec: SWORD_LONG
  // Expected: WRONG_CLASS (LOOP + FILM are sword negations) +
  //           PARTIAL_MATCH actually since required parts are
  //           also missing.  Both negations violated AND
  //           required missing -> PARTIAL_MATCH.
  let obs2: *nx_int = (sys_mmap(64)) as *nx_int
  obs2[0] = NX_PT_HANDLE_STICK
  obs2[1] = NX_PT_LOOP
  obs2[2] = NX_PT_FILM
  let r2: *NxObjectMatchResult = nx_object_spec_match(
      NX_SPEC_SWORD_LONG, obs2, 3)
  if r2.verdict != NX_OSM_VERDICT_PARTIAL_MATCH { return 10 }
  if r2.n_negations_violated < 2 { return 11 }
  if r2.n_required_missing != 5 { return 12 }
  // The suggested alternative should be BUBBLE_WAND (it has
  // HANDLE_STICK + LOOP required and FILM optional, no violations).
  if r2.suggested_alternative != NX_SPEC_BUBBLE_WAND { return 13 }
262
  // ---- CASE 3: ORC that IS an orc
  //
  // Observed: HEAD, TUSK, FANG
  // Spec: ORC_STANDARD
  // Expected: MATCHES_SPEC
  let obs3: *nx_int = (sys_mmap(64)) as *nx_int
  obs3[0] = NX_PT_HEAD
  obs3[1] = NX_PT_TUSK
  obs3[2] = NX_PT_FANG
  let r3: *NxObjectMatchResult = nx_object_spec_match(
      NX_SPEC_ORC_STANDARD, obs3, 3)
  if r3.verdict != NX_OSM_VERDICT_MATCHES_SPEC { return 20 }
275
  // ---- CASE 4: ORC prompt got an ELF (pointed ear instead of tusks)
  //
  // Observed: HEAD, POINTED_EAR
  // Spec: ORC_STANDARD (negates POINTED_EAR)
  // Expected: WRONG_CLASS (negation hit + required TUSK missing)
  //           Wait: with TUSK missing AND POINTED_EAR negation
  //           hit, that's PARTIAL_MATCH (both miss + violate).
  //           Suggested alternative: ELF_HIGH
  let obs4: *nx_int = (sys_mmap(64)) as *nx_int
  obs4[0] = NX_PT_HEAD
  obs4[1] = NX_PT_POINTED_EAR
  let r4: *NxObjectMatchResult = nx_object_spec_match(
      NX_SPEC_ORC_STANDARD, obs4, 2)
  if r4.verdict != NX_OSM_VERDICT_PARTIAL_MATCH { return 30 }
  if r4.suggested_alternative != NX_SPEC_ELF_HIGH { return 31 }
291
  // ---- CASE 5: PART_MISSING case (required missing, no violation)
  //
  // Observed: BLADE, GRIP, POMMEL  (no CROSSGUARD, no EDGE)
  // Spec: SWORD_LONG
  // Expected: PART_MISSING (no negations hit; some required absent)
  let obs5: *nx_int = (sys_mmap(64)) as *nx_int
  obs5[0] = NX_PT_BLADE
  obs5[1] = NX_PT_GRIP
  obs5[2] = NX_PT_POMMEL
  let r5: *NxObjectMatchResult = nx_object_spec_match(
      NX_SPEC_SWORD_LONG, obs5, 3)
  if r5.verdict != NX_OSM_VERDICT_PART_MISSING { return 40 }
  if r5.n_required_missing != 2 { return 41 }   // EDGE + CROSSGUARD
305
  // ---- CASE 6: WRONG_CLASS pure (all required present + negation hit)
  //
  // Observed: BLADE, EDGE, CROSSGUARD, GRIP, POMMEL, LOOP
  // Spec: SWORD_LONG
  // Expected: WRONG_CLASS (required all present BUT LOOP violates)
  let obs6: *nx_int = (sys_mmap(64)) as *nx_int
  obs6[0] = NX_PT_BLADE
  obs6[1] = NX_PT_EDGE
  obs6[2] = NX_PT_CROSSGUARD
  obs6[3] = NX_PT_GRIP
  obs6[4] = NX_PT_POMMEL
  obs6[5] = NX_PT_LOOP
  let r6: *NxObjectMatchResult = nx_object_spec_match(
      NX_SPEC_SWORD_LONG, obs6, 6)
  if r6.verdict != NX_OSM_VERDICT_WRONG_CLASS { return 50 }
  if r6.n_negations_violated < 1 { return 51 }
322
  // ---- CASE 7: NO_OBSERVATION (empty observed list)
  let obs7: *nx_int = (sys_mmap(8)) as *nx_int
  let r7: *NxObjectMatchResult = nx_object_spec_match(
      NX_SPEC_SWORD_LONG, obs7, 0)
  if r7.verdict != NX_OSM_VERDICT_NO_OBSERVATION { return 60 }
328
  // ---- CASE 8: invalid spec_id
  let r8: *NxObjectMatchResult = nx_object_spec_match(
      NX_SPEC_N_SPECS, obs1, 5)
  if r8.verdict != NX_OSM_VERDICT_NO_OBSERVATION { return 70 }
333
  return 0
335}
nx_object_spec_match.nx source

`nx_object_spec_match.nx` source
