feat(scheduler-allocator-runner): declare the allocator plugin contract (task 1.2)

xce_sched_allocator_iface_t (optional accepts guard + plan_init/next/fini)
and the sched_allocator_run() entry point in sched/alloc_iter.h; the
plugin's const allocator_iface reference, forward-declared in plugin.h
with the picker_iface ownership rule. No plugin uses them yet.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

src/scheduler/include/plugin.h

@@ -60,6 +60,12 @@ typedef struct {
  * -- same idiom as cluster_t across myconf.h/persist.h/ha.h/cluster_def.h. */
 typedef struct xce_job_picker_iface_s xce_job_picker_iface_t;
 
+/* Forward declaration -- xce_sched_allocator_iface_t (the allocator plugin
+ * contract, scheduler-allocator-runner Req 1.2) is fully defined in
+ * sched/alloc_iter.h, next to the plan-iterator contract it wraps. Only
+ * needed here as a pointer field on xce_sched_plugin_t. */
+typedef struct xce_sched_allocator_iface_s xce_sched_allocator_iface_t;
+
 /* xce_sched_core_t is defined in core.h -- forward-declared here (re-declared
  * again, harmlessly, near plugin_register_core()'s own declaration below)
  * so plugin_begin_session()/plugin_end_session() can be declared against it
@@ -86,6 +92,12 @@ typedef struct {
      * job_elect_fn"). Stays NULL for plugin categories that are neither
      * (allocator/limit plugins never set job_elect_fn). */
     xce_job_picker_iface_t* picker_iface;
+    /* Allocator plugin registration category (scheduler-allocator-runner
+     * Req 1.2 / 1.6): the plugin's allocator contract. Same ownership as
+     * picker_iface -- static storage owned by the plugin file (a `static
+     * const` object there), copied by pointer on registration and never
+     * freed by the registry. NULL for non-allocator plugins. */
+    const xce_sched_allocator_iface_t* allocator_iface;
     /* scheduler-sim-live-allocation spec, task 1.2 ("Plugin Hook
      * Dispatchers" / "Limit Plugin Core-Safe Matching"): an honestly-typed
      * reference to the shared core state, set by BOTH plugin_register()

src/scheduler/include/sched/alloc_iter.h

@@ -154,6 +154,41 @@ struct xce_host_iter_s {
     void* private;
 };
 
+/*
+ * xce_sched_allocator_iface_t - the allocator plugin contract
+ * (scheduler-allocator-runner Req 1.2). An allocator plugin supplies only
+ * its policy -- an optional acceptance guard plus a plan generator -- and
+ * sets job_alloc_fn = sched_allocator_run; the framework runner owns the
+ * rest of the allocation attempt. The typedef is forward-declared in
+ * plugin.h; the object is `static const` in the plugin file and
+ * referenced from xce_sched_plugin_t.allocator_iface.
+ */
+struct xce_sched_allocator_iface_s {
+    /* Optional. Returns 1 when this plugin allocates `primary`, 0 when it
+     * does not (the job stays pending with no reason and no checks run).
+     * NULL accepts every request. */
+    int (*accepts)(const xce_primary_resreq_t* primary);
+
+    /* Required. Same contract as xce_alloc_plan_iter_t init/next/fini
+     * above: plan_init returns 0 and leaves `iter` ready for plan_next, or
+     * nonzero with nothing to release (plan_fini is then not called);
+     * plan_next returns plans most-preferred first, NULL when exhausted;
+     * plan_fini releases the iterator's private state. */
+    int (*plan_init)(xce_alloc_plan_iter_t* iter, xce_primary_resreq_t* resreq,
+                     xce_sched_core_t* core);
+    xce_alloc_plan_t* (*plan_next)(xce_alloc_plan_iter_t* iter);
+    void (*plan_fini)(xce_alloc_plan_iter_t* iter);
+};
+
+/*
+ * sched_allocator_run - the framework allocation entry point, the
+ * job_alloc_fn of every allocator plugin; `plugin` is the
+ * xce_sched_plugin_t* whose allocator_iface drives the attempt. Returns
+ * > 0 when satisfied (ctx->alloc set), 0 when pending, < 0 a negative
+ * errno (-EINVAL for a missing plugin, ctx, core or allocator_iface).
+ */
+extern int sched_allocator_run(void* plugin, xce_sched_ctx_t* ctx);
+
 /*
  * sched_host_iter_init/next/fini - the one shared xce_host_iter_t
  * implementation (host_iter.c, task 2.1, Req 3). Callers wire these onto a