engine: add a direct-constraint input channel for computed bounds

A component can now emit a bound on a named quantity (>=, <=) that it
computed but cannot state as a located address, via a new OBS_CONSTRAINT
record and `C <quantity> <op> value=` wire line. It is not an address, so
the anchor rules never read it and a below-region bound can no longer be
misread as a text or page-offset witness.

- text_pin_from_observation no longer widens a sub-floor base into a slot
  window; a witness pins the one slot it names, so exact offset-table pins
  (kernfs, bpf) are no longer smeared into two slots.
- perf and mmap_brute_vmsplit emit their floors as lower bounds through
  the new channel instead of below-region positional records; perf's
  interior sample still supplies the upper bound, bracketing the base.
- Gate range_from_interior and riscv64_fdt_kaslr_seed on OBS_ADDRESS so
  the new kind is invisible to every anchor reader by construction.
- Fold constraint-op token lookup into one table; replace the ineffective
  wire-table completeness typedef with a runtime test.

Author: bcoles

src/components/mmap_brute_vmsplit.c

@@ -55,6 +55,7 @@
 #define _GNU_SOURCE
 #include "include/kasld/api.h"
 #include "include/kasld/cli.h"
+#include "include/kasld/constraint.h"
 #include "include/kasld/task_size.h"
 #include <limits.h>
 #include <stdio.h>
@@ -169,11 +170,15 @@ int main(void) {
     /* Everywhere else the split sits BELOW PAGE_OFFSET by a distance the
      * architecture fixes and this probe cannot see (arm32 reserves 16 MiB for
      * modules, ppc32 a smaller gap, riscv32 the fixmap, PCI-IO and vmemmap
-     * regions). The measurement is then a lower bound on the base, emitted as
-     * the window it proves; the upper edge is the highest base the architecture
-     * admits, which holds against any target. */
-    kasld_result_range(KASLD_TYPE_VIRT, REGION_PAGE_OFFSET, addr,
-                       (unsigned long)PAGE_OFFSET_MAX, NULL, CONF_INFERRED);
+     * regions). So the measurement is a pure LOWER BOUND on the base. Emit it
+     * on the constraint channel rather than as a positional range: the value
+     * sits below the linear-map region, which the anchor and coupling rules
+     * (reading a page-offset witness as a located address) would misread; a
+     * constraint is not an address, so they never see it. The range form's
+     * upper edge was PAGE_OFFSET_MAX, which is exactly Q_PAGE_OFFSET's own top,
+     * so stating only the lower bound loses nothing. Sound (gated on `exact`),
+     * hence CONF_INFERRED: it holds in the guaranteed window. */
+    kasld_emit_constraint(Q_PAGE_OFFSET, C_LOWER_BOUND, addr, CONF_INFERRED);
 #endif
   }
 

src/components/perf_amd_branch_user.c

@@ -63,6 +63,7 @@
 #define _GNU_SOURCE
 #include "include/kasld/api.h"
 #include "include/kasld/cli.h"
+#include "include/kasld/constraint.h"
 #include "include/kasld/perf_branch.h"
 #include <errno.h>
 #include <linux/perf_event.h>
@@ -192,12 +193,16 @@ int main(int argc, char *argv[]) {
                       CONF_PARSED);
 
   /* Entry-text branch-from sites sit in the base's own slot, so flooring the
-   * lowest to the base grid is a within-one-slot GUESS: emit it as a
-   * CONF_HEURISTIC base pin shaping only the LIKELY window, never the
-   * guaranteed one. Gated on the 2 MiB grid (x86 only), as in the sibling. */
+   * lowest to the base grid is a within-one-slot GUESS: the base is that slot
+   * or one below it. Emit the lower bound (floor - one slot) on the constraint
+   * channel, at CONF_HEURISTIC so it shapes only the LIKELY window; a below-
+   * _text bound is not an address and so is invisible to the anchor rules. The
+   * interior sample supplies the sound upper bound. Gated on the 2 MiB grid
+   * (x86 only), as in the sibling. */
 #if KASLR_VIRT_ALIGN >= 2 * MB
-  kasld_result_base(KASLD_TYPE_VIRT, REGION_KERNEL_IMAGE,
-                    kasld_floor_text_base(acc.min_addr), NULL, CONF_HEURISTIC);
+  kasld_emit_constraint(Q_VIRT_IMAGE_BASE, C_LOWER_BOUND,
+                        kasld_floor_text_base(acc.min_addr) - KASLR_VIRT_ALIGN,
+                        CONF_HEURISTIC);
 #endif
   return 0;
 }

src/components/perf_event_open.c

@@ -31,6 +31,7 @@
 #define _GNU_SOURCE
 #include "include/kasld/api.h"
 #include "include/kasld/cli.h"
+#include "include/kasld/constraint.h"
 #include <errno.h>
 #include <linux/perf_event.h>
 #include <poll.h>
@@ -266,25 +267,30 @@ int main(void) {
   kasld_result_sample(KASLD_TYPE_VIRT, REGION_KERNEL_TEXT, addr, NULL,
                       CONF_PARSED);
 
-  /* On large-page arches the lowest sampled IP also yields a speculative base
-   * GUESS: flooring it to KASLR_VIRT_ALIGN lands on the image base whenever the
-   * lowest sampled function sits in the base's own slot — the common case on a
-   * busy system, where low text executes constantly. It overshoots by one slot
-   * only when the base's slot holds nothing the sampler caught (un-executed
-   * head/entry text on an idle, freshly booted kernel). So emit it as a base
-   * pin, but at CONF_HEURISTIC: "the floored slot is the base" is a heuristic,
-   * so the pin sits BELOW the sound floor and shapes the speculative LIKELY
-   * window only — never the guaranteed one, which keeps the sound interior
-   * upper bound above. Region KERNEL_IMAGE so the value is read as _text
-   * directly, with no _stext head-gap subtraction. kasld_floor_text_base
-   * preserves the sub-alignment residue so the floor never drops below _text.
+  /* On large-page arches the lowest sampled IP also brackets the base from
+   * below. Flooring it to the KASLR grid lands on the base's own slot whenever
+   * the lowest sampled function sits there — the common case on a busy system,
+   * where low text executes constantly — and overshoots by exactly one slot
+   * when the base's slot holds nothing the sampler caught (un-executed
+   * head/entry text on an idle, freshly booted kernel). So the base is the
+   * floored slot or one slot below it: a LOWER bound of floor - one slot.
+   *
+   * Emit it on the constraint channel rather than as a positional base pin.
+   * The bound value sits one slot below _text, which the anchor rules — which
+   * read a base witness as a located address — would misread as text; a
+   * constraint is not an address, so they never see it. At CONF_HEURISTIC the
+   * bound sits below the sound floor and shapes the speculative LIKELY window
+   * only, never the guaranteed one; combined with the interior sample's sound
+   * upper bound (base <= floored, via grid alignment) it brackets the base to
+   * two slots, which an agreeing exact pin collapses to one.
    *
    * Gated to KASLR_VIRT_ALIGN >= 2 MiB: on fine-granule arches the lowest
-   * sampled IP can sit many slots above the base, so flooring it is not a
-   * within-one-slot guess; there the interior upper bound is the only claim. */
+   * sampled IP can sit many slots above the base, so "within one slot" does not
+   * hold; there the interior upper bound is the only claim. */
 #if KASLR_VIRT_ALIGN >= 2 * MB
-  kasld_result_base(KASLD_TYPE_VIRT, REGION_KERNEL_IMAGE,
-                    kasld_floor_text_base(addr), NULL, CONF_HEURISTIC);
+  kasld_emit_constraint(Q_VIRT_IMAGE_BASE, C_LOWER_BOUND,
+                        kasld_floor_text_base(addr) - KASLR_VIRT_ALIGN,
+                        CONF_HEURISTIC);
 #endif
 
   return 0;

src/components/perf_lbr_sampling.c

@@ -53,6 +53,7 @@
 #define _GNU_SOURCE
 #include "include/kasld/api.h"
 #include "include/kasld/cli.h"
+#include "include/kasld/constraint.h"
 #include "include/kasld/perf_branch.h"
 #include <errno.h>
 #include <linux/perf_event.h>
@@ -176,19 +177,21 @@ int main(int argc, char *argv[]) {
   kasld_result_sample(KASLD_TYPE_VIRT, REGION_KERNEL_TEXT, acc.min_addr, NULL,
                       CONF_PARSED);
 
-  /* On large-page arches the lowest sample also yields a speculative base
-   * GUESS: flooring it to the base grid lands on the image base whenever the
-   * lowest sampled branch sits in the base's own slot. Emit it as a base pin at
-   * CONF_HEURISTIC so it shapes only the speculative LIKELY window, never the
-   * guaranteed one (which keeps the sound interior upper bound above). Region
-   * KERNEL_IMAGE so the value is read as _text directly; kasld_floor_text_base
-   * preserves the sub-alignment residue so the floor never drops below _text.
+  /* On large-page arches the lowest sample also brackets the base from below:
+   * flooring it to the base grid lands on the image base whenever the lowest
+   * sampled branch sits in the base's own slot, and one slot high otherwise —
+   * so the base is the floored slot or one below it. Emit the lower bound
+   * (floor - one slot) on the constraint channel at CONF_HEURISTIC so it shapes
+   * only the speculative LIKELY window, never the guaranteed one; the interior
+   * sample keeps the sound upper bound. A below-_text bound is not an address,
+   * so the anchor rules never read it.
    * LBR is x86-only today (KASLR_VIRT_ALIGN = 2 MiB, so the gate always holds);
    * the gate keeps this correct-by-construction should LBR ever gain a finer
    * target, where flooring the lowest sample is not a within-one-slot guess. */
 #if KASLR_VIRT_ALIGN >= 2 * MB
-  kasld_result_base(KASLD_TYPE_VIRT, REGION_KERNEL_IMAGE,
-                    kasld_floor_text_base(acc.min_addr), NULL, CONF_HEURISTIC);
+  kasld_emit_constraint(Q_VIRT_IMAGE_BASE, C_LOWER_BOUND,
+                        kasld_floor_text_base(acc.min_addr) - KASLR_VIRT_ALIGN,
+                        CONF_HEURISTIC);
 #endif
   return 0;
 }

src/engine_rules.c

@@ -93,6 +93,9 @@ static const rule_fn k_rules[] = {
     /* Text-base pin from POS_BASE kernel-image observation */
     rule_text_pin_from_observation,
 
+    /* Direct-constraint channel: fold OBS_CONSTRAINT bounds into the meet */
+    rule_constraint_passthrough,
+
     /* Symmetric phys↔virt text-base coupling synthesizer */
     rule_text_base_coupling_synth,
 

src/include/kasld/constraint.h

@@ -44,6 +44,36 @@ enum constraint_op {
                       *                         CRT combines repeats)     */
 };
 
+/* constraint_op <-> wire token. Total over the enum so the mapping round-trips
+ * both ways (the engine emits every op internally); the direct-constraint input
+ * channel (kasld_emit_constraint) only *carries* the two inequality-bound ops.
+ */
+static const char *const kasld_constraint_op_wire_table[] = {
+    [C_LOWER_BOUND] = ">=",  [C_UPPER_BOUND] = "<=",
+    [C_EQUALS] = "==",       [C_AT_LEAST_ALIGN] = "align>=",
+    [C_EXCLUDE] = "exclude", [C_STRIDE] = "stride",
+};
+
+static inline const char *kasld_constraint_op_wire(enum constraint_op op) {
+  unsigned n = sizeof(kasld_constraint_op_wire_table) / sizeof(char *);
+  if ((unsigned)op >= n)
+    return NULL;
+  return kasld_constraint_op_wire_table[op];
+}
+
+/* Returns 1 and sets *out on a known token; 0 otherwise. */
+static inline int kasld_constraint_op_from_wire(const char *s,
+                                                enum constraint_op *out) {
+  unsigned n = sizeof(kasld_constraint_op_wire_table) / sizeof(char *);
+  for (unsigned i = 0; i < n; i++)
+    if (kasld_constraint_op_wire_table[i] &&
+        strcmp(s, kasld_constraint_op_wire_table[i]) == 0) {
+      *out = (enum constraint_op)i;
+      return 1;
+    }
+  return 0;
+}
+
 struct constraint {
   enum kasld_quantity q;
   enum constraint_op op;
@@ -68,4 +98,48 @@ struct constraint {
   uint32_t id;             /* monotonic, assigned at emission */
 };
 
+/* Emit one direct constraint on a quantity:
+ *   C <quantity> <op> conf=<c> value=0x<hex>
+ *
+ * For a component that has *computed a bound on a known quantity* but cannot
+ * state it as a located address (the motivating case is perf's lowest sampled
+ * IP, a lower bound on the text base that lands below _text). The channel
+ * carries inequality bounds only (>=, <=); the orchestrator turns each into
+ * that C_* constraint for the meet. It is not an address, so the anchor rules
+ * never read it — a below-base bound cannot be misread as a text anchor. An
+ * exact value is deliberately NOT on this channel: a located address uses the
+ * positional emitters (kasld_result_base/sample/...), where it also
+ * corroborates and classifies; an exact non-address measurement uses the scalar
+ * channel. This channel is for a computed bound and nothing else. */
+static inline int kasld_emit_constraint(enum kasld_quantity q,
+                                        enum constraint_op op,
+                                        unsigned long value,
+                                        enum kasld_confidence c) {
+  const char *qw = kasld_quantity_wire(q);
+  const char *ow = kasld_constraint_op_wire(op);
+  if (!qw) {
+    fprintf(stderr,
+            "kasld_emit_constraint: invalid quantity %d; nothing "
+            "emitted\n",
+            (int)q);
+    return 0;
+  }
+  if (op != C_LOWER_BOUND && op != C_UPPER_BOUND) {
+    fprintf(stderr,
+            "kasld_emit_constraint: op %s not carried on this channel "
+            "(inequality bounds only); nothing emitted\n",
+            ow ? ow : "?");
+    return 0;
+  }
+  if (c == CONF_UNKNOWN) {
+    fprintf(stderr,
+            "kasld_emit_constraint: CONF_UNKNOWN for %s; nothing "
+            "emitted\n",
+            qw);
+    return 0;
+  }
+  printf("C %s %s conf=%s value=0x%lx\n", qw, ow, kasld_conf_wire(c), value);
+  return 1;
+}
+
 #endif /* KASLD_CONSTRAINT_H */

src/include/kasld/engine_rules.h

@@ -329,6 +329,7 @@ R(efi_loader_kernel_pick);
 
 /* Text-base pin from POS_BASE kernel-image observation */
 R(text_pin_from_observation);
+R(constraint_passthrough);
 
 /* Symmetric phys↔virt text-base coupling synthesizer */
 R(text_base_coupling_synth);

src/include/kasld/internal.h

@@ -11,6 +11,7 @@
 #define KASLD_INTERNAL_H
 
 #include "api.h"
+#include "constraint.h" /* struct constraint_fact_record enums */
 #include "regions.h" /* canonical is_phys_dram_region / is_kernel_image_region */
 
 #include <stddef.h>
@@ -879,6 +880,23 @@ struct scalar_fact_record {
 extern struct scalar_fact_record scalar_facts[MAX_SCALAR_FACTS];
 extern int num_scalar_facts;
 
+/* Direct constraints collected from components' `C` wire records, parallel to
+ * scalar_facts[]. The engine bridge copies these to OBS_CONSTRAINT
+ * observations, which a passthrough rule folds into the meet as the named C_*
+ * constraint. A component uses this channel for a bound on a known quantity it
+ * cannot state as a located address (see kasld_emit_constraint). */
+struct constraint_fact_record {
+  enum kasld_quantity q;
+  enum constraint_op op;
+  unsigned long value;
+  enum kasld_confidence conf;
+  int origin; /* discovery slot of the producing component; -1 if unattributed
+               */
+};
+#define MAX_CONSTRAINT_FACTS 64
+extern struct constraint_fact_record constraint_facts[MAX_CONSTRAINT_FACTS];
+extern int num_constraint_facts;
+
 /* =========================================================================
  * Shared functions (defined in orchestrator.c)
  * ========================================================================= */

src/include/kasld/observation.h

@@ -16,7 +16,8 @@
 #ifndef KASLD_OBSERVATION_H
 #define KASLD_OBSERVATION_H
 
-#include "api.h" /* NAME_LEN, ORIGIN_LEN wire-field widths */
+#include "api.h"        /* NAME_LEN, ORIGIN_LEN wire-field widths */
+#include "constraint.h" /* enum kasld_quantity, enum constraint_op (OBS_CONSTRAINT) */
 
 #include <stdint.h>
 
@@ -39,18 +40,26 @@ enum kasld_set_bits {
 #define HAS_BASE_ALIGN(r) ((r)->set_mask & BASE_ALIGN_SET)
 #endif
 
-/* An observation carries either an address fact (region + extent — the
- * leak/landmark shape) or a scalar system fact (a bare number with a
- * named meaning). Scalar facts exist because components are the sole
- * inference I/O boundary — a component must be able to emit raw
- * measurements that are NOT addresses (MemTotal, physical-address bits,
- * kernel image size, VA bits). A rule reads these by `scalar_fact` and
- * turns them into constraints; keeping them raw on the observation
- * preserves measure/reason separation (components measure; rules
- * interpret). */
+/* An observation carries one of three input kinds. Components are the sole
+ * inference I/O boundary, so each is something a component must be able to
+ * state:
+ *   - OBS_ADDRESS: a region + extent (the leak/landmark shape).
+ *   - OBS_SCALAR: a bare measurement with a named meaning that is NOT an
+ *     address (MemTotal, physical-address bits, image size, VA bits). A rule
+ *     reads it by `scalar_fact` and turns it into constraints.
+ *   - OBS_CONSTRAINT: an inequality bound on a named quantity the component
+ *     computed but cannot state as a located address (perf's lowest sampled IP
+ *     is a lower bound on the text base that sits below _text). It carries a
+ *     quantity, a bound operator (>= or <=), and a value; a passthrough rule
+ *     emits it as that C_* directly. Because it is not an address, the ~44
+ *     anchor rules (which gate on OBS_ADDRESS) never read it — a below-base
+ *     bound cannot be misread as a text anchor.
+ * Keeping non-address facts raw on the observation preserves measure/reason
+ * separation (components measure; rules interpret). */
 enum obs_value_kind {
   OBS_ADDRESS = 0, /* region + lo/hi/sample (default) */
   OBS_SCALAR,      /* scalar_fact + scalar_value */
+  OBS_CONSTRAINT,  /* c_quantity + c_op + scalar_value (reused as the value) */
 };
 
 /* enum kasld_scalar_fact + its wire table live in api.h (the component-facing
@@ -71,8 +80,12 @@ struct observation {
   enum kasld_position pos;
   /* OBS_SCALAR: */
   enum kasld_scalar_fact scalar_fact;
-  unsigned long scalar_value;
-  /* both: */
+  unsigned long
+      scalar_value; /* OBS_CONSTRAINT reuses this as the bound value */
+  /* OBS_CONSTRAINT: */
+  enum kasld_quantity c_quantity;
+  enum constraint_op c_op;
+  /* all kinds: */
   enum kasld_confidence conf;
   char origin[ORIGIN_LEN]; /* producing component */
 

src/include/kasld/quantity.h

@@ -36,6 +36,43 @@ enum kasld_quantity {
   Q__COUNT,
 };
 
+/* Q_* <-> wire token, single source of truth for both directions. Header-only
+ * (like kasld_scalar_fact_wire_table in api.h) so a component's emit side and
+ * the orchestrator's parse side share one mapping without linking quantities.c
+ * — the tokens match the human `name` field in that table. */
+static const char *const kasld_quantity_wire_table[Q__COUNT] = {
+    [Q_VIRT_IMAGE_BASE] = "virt_image_base",
+    [Q_PHYS_IMAGE_BASE] = "phys_image_base",
+    [Q_PAGE_OFFSET] = "virt_page_offset",
+    [Q_VMALLOC_BASE] = "virt_vmalloc_base",
+    [Q_VMEMMAP_BASE] = "virt_vmemmap_base",
+    [Q_MODULE_BASE] = "virt_module_base",
+    [Q_VIRT_KASLR_ALIGN] = "virt_kaslr_align",
+    [Q_PHYS_KASLR_ALIGN] = "phys_kaslr_align",
+    [Q_VA_BITS] = "va_bits",
+};
+/* The [Q__COUNT] dimension keeps the table indexable for every Q_* (a missing
+ * entry is a NULL hole, not out of bounds); it does NOT make the table
+ * complete. Completeness — every Q_* has a non-NULL token, and tokens
+ * round-trip — is enforced at runtime by test_wire_tables_complete
+ * (tests/test_engine.c), since a sizeof check cannot see a NULL interior
+ * initialiser. */
+
+static inline const char *kasld_quantity_wire(enum kasld_quantity q) {
+  if ((unsigned)q >= Q__COUNT)
+    return NULL;
+  return kasld_quantity_wire_table[q];
+}
+
+/* Returns Q__COUNT when the token names no known quantity. */
+static inline enum kasld_quantity kasld_quantity_from_wire(const char *s) {
+  for (int i = 0; i < Q__COUNT; i++)
+    if (kasld_quantity_wire_table[i] &&
+        strcmp(s, kasld_quantity_wire_table[i]) == 0)
+      return (enum kasld_quantity)i;
+  return Q__COUNT;
+}
+
 /* Lattice kind selects the meet operation and the bottom test.
  *  - LK_INTERVAL: value is [lo, hi]; meet narrows the interval; bottom = lo>hi.
  *  - LK_MAXALIGN: value is the largest known alignment (power of two); meet