Central-config-driven client actions: daemon action reconciler + backfill-on-join (LLP 0041/0043)

hypaware-core/plugins-workspace/claude/hypaware.plugin.json

@@ -44,6 +44,12 @@
         "name": "claude-and-otel-local",
         "summary": "Capture Claude Code + OTLP locally, export to Parquet under HYP_HOME/exports"
       }
+    ],
+    "config_sections": [
+      {
+        "section": "claude",
+        "summary": "Claude adapter config, including the optional backfill-on-join policy { on_join, window_days }."
+      }
     ]
   }
 }

hypaware-core/plugins-workspace/claude/src/config.js

@@ -0,0 +1,84 @@
+// @ts-check
+
+/**
+ * Config validation for the `@hypaware/claude` plugin's own `config`
+ * block. v1 validates only the optional `backfill` sub-object that drives
+ * backfill-on-join — `{ on_join, window_days }`. Every other key (e.g.
+ * `proxy`) passes through untouched so existing configs keep working;
+ * there is no top-level `backfill` section and nothing new for core to
+ * validate.
+ *
+ * Pure and dependency-free: it returns a `ValidationResult` so it plugs
+ * straight into `ctx.configRegistry.registerSection` and is callable from
+ * tests without spinning up observability.
+ *
+ * @import { ValidationError, ValidationResult } from '../../../../collectivus-plugin-kernel-types.d.ts'
+ */
+
+/** Manifest `config_sections[].section` name this validator backs. */
+export const CLAUDE_CONFIG_SECTION = 'claude'
+
+/**
+ * Validate the `@hypaware/claude` plugin config slice. Only the optional
+ * `backfill` policy block is checked; unknown sibling keys are ignored so
+ * the validator stays additive over the existing config surface.
+ *
+ * @ref LLP 0037#per-plugin-config-kernel-generic-reconciler [implements] —
+ *   backfill policy ({ on_join, window_days }) lives in and is validated
+ *   by the source plugin's own config section; the kernel reconciler adds
+ *   no top-level schema.
+ *
+ * @param {unknown} value
+ * @returns {ValidationResult}
+ */
+export function validateClaudeConfig(value) {
+  if (value === undefined || value === null) return { ok: true }
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    return { ok: false, errors: [{ pointer: '', message: 'claude config must be an object' }] }
+  }
+  const raw = /** @type {Record<string, unknown>} */ (value)
+  const errors = validateBackfillSection(raw.backfill, '/backfill')
+  if (errors.length > 0) return { ok: false, errors }
+  return { ok: true }
+}
+
+/**
+ * Validate the optional `backfill` policy block shared by every
+ * backfill-capable source plugin: `on_join` (whether to import on join,
+ * boolean) and `window_days` (how far back, positive integer). Both are
+ * optional; unknown keys are rejected so a typo (`window_day`) surfaces
+ * instead of being silently ignored. Pure — the caller chooses where the
+ * returned pointers mount.
+ *
+ * @param {unknown} value
+ * @param {string} pointer  JSON-pointer prefix for the `backfill` object
+ * @returns {ValidationError[]}
+ */
+export function validateBackfillSection(value, pointer) {
+  /** @type {ValidationError[]} */
+  const errors = []
+  if (value === undefined) return errors
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    errors.push({ pointer, message: 'backfill must be an object' })
+    return errors
+  }
+  const raw = /** @type {Record<string, unknown>} */ (value)
+  if (raw.on_join !== undefined && typeof raw.on_join !== 'boolean') {
+    errors.push({ pointer: `${pointer}/on_join`, message: 'backfill.on_join must be a boolean' })
+  }
+  if (raw.window_days !== undefined) {
+    const days = raw.window_days
+    if (typeof days !== 'number' || !Number.isInteger(days) || days <= 0) {
+      errors.push({
+        pointer: `${pointer}/window_days`,
+        message: 'backfill.window_days must be a positive integer',
+      })
+    }
+  }
+  for (const key of Object.keys(raw)) {
+    if (key !== 'on_join' && key !== 'window_days') {
+      errors.push({ pointer: `${pointer}/${key}`, message: `unknown backfill key '${key}'` })
+    }
+  }
+  return errors
+}

hypaware-core/plugins-workspace/claude/src/index.js

@@ -7,6 +7,7 @@ import { fileURLToPath } from 'node:url'
 
 import { Attr, getLogger, withSpan } from '../../../../src/core/observability/index.js'
 import { defaultConfigPath } from '../../../../src/core/config/schema.js'
+import { CLAUDE_CONFIG_SECTION, validateClaudeConfig } from './config.js'
 import { attach, defaultSettingsPath, detach } from './settings.js'
 import { anthropicUpstreamPreset, createClaudeExchangeProjector } from './projector.js'
 import { createClaudeBackfillProvider } from './backfill.js'
@@ -23,6 +24,19 @@ const CLIENT_NAME = 'claude'
 const UPSTREAM_NAME = 'anthropic'
 const FALLBACK_BIN_PATH = fileURLToPath(new URL('../../../../bin/hypaware.js', import.meta.url))
 
+/**
+ * The plugin's `config_sections` validator, surfaced as a side-effect-free
+ * export so the kernel apply path can validate this plugin's `config` block
+ * (the `backfill` policy) *before* the plugin is ever activated — e.g. a
+ * central config that first introduces `@hypaware/claude`. It is the same
+ * registration `activate()` hands `ctx.configRegistry.registerSection`;
+ * importing this module never runs `activate()`, so discovery is safe.
+ *
+ * @ref LLP 0037#per-plugin-config-kernel-generic-reconciler [implements] — the plugin owns + exposes its own `backfill` validator
+ * @type {{ section: string, validate: typeof validateClaudeConfig }}
+ */
+export const configSection = { section: CLAUDE_CONFIG_SECTION, validate: validateClaudeConfig }
+
 /**
  * Resolve the canonical session-context state file the Claude hook
  * appends to and the projector reads from. Centralised so attach()
@@ -54,6 +68,17 @@ export function claudeSessionContextFile(ctx) {
  * @ref LLP 0016#knows-nothing-about-claude-or-codex [implements] — adapter requires the ai-gateway capability; registers client + upstream preset
  */
 export async function activate(ctx) {
+  // Validate the plugin's own `config` block — currently just the
+  // optional `backfill` policy ({ on_join, window_days }) that drives
+  // backfill-on-join. Registered so the kernel runs it via
+  // `runPerPluginSectionValidators`; no top-level core schema change.
+  // @ref LLP 0037#per-plugin-config-kernel-generic-reconciler [implements] — the source plugin owns and validates its `backfill` config
+  ctx.configRegistry.registerSection({
+    plugin: PLUGIN_NAME,
+    section: CLAUDE_CONFIG_SECTION,
+    validate: validateClaudeConfig,
+  })
+
   /** @type {AiGatewayCapability} */
   const gateway = ctx.requireCapability('hypaware.ai-gateway', '^2.0.0')
 

hypaware-core/plugins-workspace/codex/hypaware.plugin.json

@@ -31,6 +31,12 @@
     },
     "skills": [
       { "name": "hypaware-query", "clients": ["codex"] }
+    ],
+    "config_sections": [
+      {
+        "section": "codex",
+        "summary": "Codex adapter config, including the optional backfill-on-join policy { on_join, window_days }."
+      }
     ]
   }
 }

hypaware-core/plugins-workspace/codex/src/config.js

@@ -0,0 +1,83 @@
+// @ts-check
+
+/**
+ * Config validation for the `@hypaware/codex` plugin's own `config`
+ * block. v1 validates only the optional `backfill` sub-object that drives
+ * backfill-on-join — `{ on_join, window_days }`. Every other key passes
+ * through untouched so existing configs keep working; there is no
+ * top-level `backfill` section and nothing new for core to validate.
+ *
+ * Pure and dependency-free: it returns a `ValidationResult` so it plugs
+ * straight into `ctx.configRegistry.registerSection` and is callable from
+ * tests without spinning up observability.
+ *
+ * @import { ValidationError, ValidationResult } from '../../../../collectivus-plugin-kernel-types.d.ts'
+ */
+
+/** Manifest `config_sections[].section` name this validator backs. */
+export const CODEX_CONFIG_SECTION = 'codex'
+
+/**
+ * Validate the `@hypaware/codex` plugin config slice. Only the optional
+ * `backfill` policy block is checked; unknown sibling keys are ignored so
+ * the validator stays additive over the existing config surface.
+ *
+ * @ref LLP 0037#per-plugin-config-kernel-generic-reconciler [implements] —
+ *   backfill policy ({ on_join, window_days }) lives in and is validated
+ *   by the source plugin's own config section; the kernel reconciler adds
+ *   no top-level schema.
+ *
+ * @param {unknown} value
+ * @returns {ValidationResult}
+ */
+export function validateCodexConfig(value) {
+  if (value === undefined || value === null) return { ok: true }
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    return { ok: false, errors: [{ pointer: '', message: 'codex config must be an object' }] }
+  }
+  const raw = /** @type {Record<string, unknown>} */ (value)
+  const errors = validateBackfillSection(raw.backfill, '/backfill')
+  if (errors.length > 0) return { ok: false, errors }
+  return { ok: true }
+}
+
+/**
+ * Validate the optional `backfill` policy block shared by every
+ * backfill-capable source plugin: `on_join` (whether to import on join,
+ * boolean) and `window_days` (how far back, positive integer). Both are
+ * optional; unknown keys are rejected so a typo (`window_day`) surfaces
+ * instead of being silently ignored. Pure — the caller chooses where the
+ * returned pointers mount.
+ *
+ * @param {unknown} value
+ * @param {string} pointer  JSON-pointer prefix for the `backfill` object
+ * @returns {ValidationError[]}
+ */
+export function validateBackfillSection(value, pointer) {
+  /** @type {ValidationError[]} */
+  const errors = []
+  if (value === undefined) return errors
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    errors.push({ pointer, message: 'backfill must be an object' })
+    return errors
+  }
+  const raw = /** @type {Record<string, unknown>} */ (value)
+  if (raw.on_join !== undefined && typeof raw.on_join !== 'boolean') {
+    errors.push({ pointer: `${pointer}/on_join`, message: 'backfill.on_join must be a boolean' })
+  }
+  if (raw.window_days !== undefined) {
+    const days = raw.window_days
+    if (typeof days !== 'number' || !Number.isInteger(days) || days <= 0) {
+      errors.push({
+        pointer: `${pointer}/window_days`,
+        message: 'backfill.window_days must be a positive integer',
+      })
+    }
+  }
+  for (const key of Object.keys(raw)) {
+    if (key !== 'on_join' && key !== 'window_days') {
+      errors.push({ pointer: `${pointer}/${key}`, message: `unknown backfill key '${key}'` })
+    }
+  }
+  return errors
+}

hypaware-core/plugins-workspace/codex/src/index.js

@@ -7,6 +7,7 @@ import { fileURLToPath } from 'node:url'
 
 import { Attr, getLogger, withSpan } from '../../../../src/core/observability/index.js'
 import { createCodexBackfillProvider } from './backfill.js'
+import { CODEX_CONFIG_SECTION, validateCodexConfig } from './config.js'
 import { createCodexExchangeProjector } from './exchange-projector.js'
 import { attach, defaultConfigPath, detach } from './settings.js'
 
@@ -19,6 +20,19 @@ const CLIENT_NAME = 'codex'
 const UPSTREAM_NAME = 'openai'
 const CHATGPT_UPSTREAM_NAME = 'chatgpt'
 
+/**
+ * The plugin's `config_sections` validator, surfaced as a side-effect-free
+ * export so the kernel apply path can validate this plugin's `config` block
+ * (the `backfill` policy) *before* the plugin is ever activated — e.g. a
+ * central config that first introduces `@hypaware/codex`. It is the same
+ * registration `activate()` hands `ctx.configRegistry.registerSection`;
+ * importing this module never runs `activate()`, so discovery is safe.
+ *
+ * @ref LLP 0037#per-plugin-config-kernel-generic-reconciler [implements] — the plugin owns + exposes its own `backfill` validator
+ * @type {{ section: string, validate: typeof validateCodexConfig }}
+ */
+export const configSection = { section: CODEX_CONFIG_SECTION, validate: validateCodexConfig }
+
 /**
  * Activate the `@hypaware/codex` adapter plugin.
  *
@@ -35,6 +49,17 @@ const CHATGPT_UPSTREAM_NAME = 'chatgpt'
  * @ref LLP 0016#knows-nothing-about-claude-or-codex [implements] — adapter requires the ai-gateway capability; registers client + upstream presets
  */
 export async function activate(ctx) {
+  // Validate the plugin's own `config` block — currently just the
+  // optional `backfill` policy ({ on_join, window_days }) that drives
+  // backfill-on-join. Registered so the kernel runs it via
+  // `runPerPluginSectionValidators`; no top-level core schema change.
+  // @ref LLP 0037#per-plugin-config-kernel-generic-reconciler [implements] — the source plugin owns and validates its `backfill` config
+  ctx.configRegistry.registerSection({
+    plugin: PLUGIN_NAME,
+    section: CODEX_CONFIG_SECTION,
+    validate: validateCodexConfig,
+  })
+
   /** @type {AiGatewayCapability} */
   const gateway = ctx.requireCapability('hypaware.ai-gateway', '^2.0.0')