@qmilab/lodestar-core 0.1.4 → 0.2.0

package/src/schemas/probe-pack.ts

@@ -0,0 +1,169 @@
+import { z } from "zod"
+
+/**
+ * The probe-pack format spec version. This is the version of the
+ * *manifest schema itself*, not of any given pack. A loader declares
+ * which spec versions it understands; a manifest declares which one it
+ * was written against. v0 of the harness understands spec "1" only.
+ *
+ * Bump this when the manifest shape changes in a way older loaders
+ * cannot read. Adding an optional field is not a bump; removing or
+ * re-typing a field is.
+ */
+export const PROBE_PACK_SPEC_VERSION = "1" as const
+
+/**
+ * Where a pack's probe files come from.
+ *
+ * `local` — the pack lives on the filesystem; probe `file` paths are
+ *   resolved relative to the directory containing the manifest.
+ * `npm` — the pack ships as a published package; the loader reads the
+ *   manifest from the package's `./lodestar.probe-pack.json` export and
+ *   resolves probe files relative to the package root.
+ *
+ * Both source types are part of the spec from day one so external
+ * authors can target a stable schema. The v0 loader resolves `local`
+ * only; `npm` resolution follows the first external pack that needs it
+ * (see docs/architecture/reflection-pass.md Q6).
+ */
+export const ProbePackSourceTypeSchema = z.enum(["local", "npm"])
+export type ProbePackSourceType = z.infer<typeof ProbePackSourceTypeSchema>
+
+/**
+ * One probe entry in a pack manifest.
+ *
+ * `name` is the probe's stable identifier, unique within the pack — the
+ * harness runner reports results under it and external references
+ * address probes by `<pack>/<name>`. `file` is the probe source,
+ * relative to the pack root.
+ */
+export const ProbeEntrySchema = z.object({
+  name: z
+    .string()
+    .min(1)
+    .regex(
+      /^[a-z0-9]+(?:-[a-z0-9]+)*$/,
+      "probe name must be kebab-case (lowercase alphanumerics separated by single hyphens)",
+    )
+    .describe("Stable probe identifier, unique within the pack."),
+  file: z
+    .string()
+    .min(1)
+    // Must be relative to the pack root: a pack that names an absolute
+    // path loads on its author's machine but breaks once moved or
+    // published. Reject POSIX (`/`), UNC/Windows-root (`\`), and
+    // drive-letter (`C:`) prefixes so the contract holds cross-platform.
+    .refine((f) => !/^([/\\]|[A-Za-z]:)/.test(f), {
+      message:
+        "probe file must be a relative path inside the pack (absolute paths are not allowed)",
+    })
+    .describe(
+      "Probe source file, relative to the pack root (the directory containing the manifest).",
+    ),
+})
+export type ProbeEntry = z.infer<typeof ProbeEntrySchema>
+
+/**
+ * One sentinel entry in a pack manifest.
+ *
+ * Unlike a probe — a `bun run`-able script the pack carries as a `file` —
+ * a sentinel is a stateful in-process class the harness instantiates and
+ * feeds the event stream. There is no subprocess contract for it, so the
+ * manifest references a sentinel by a stable `id` and the harness resolves
+ * that id against its built-in registry of first-party sentinels
+ * (`FIRST_PARTY_SENTINELS` in `@qmilab/lodestar-harness`). A pack thus
+ * *declares* which built-in sentinels it ships rather than carrying their
+ * source.
+ *
+ * Per-pack construction-option overrides and third-party (file-referenced)
+ * sentinels are a deliberate later refinement — see the harness loader and
+ * `docs/architecture/sentinels.md`. v0 resolves first-party ids only.
+ */
+export const SentinelEntrySchema = z.object({
+  id: z
+    .string()
+    .min(1)
+    .regex(
+      /^[a-z0-9]+(?:-[a-z0-9]+)*$/,
+      "sentinel id must be kebab-case (lowercase alphanumerics separated by single hyphens)",
+    )
+    .describe(
+      "Stable id of a first-party sentinel, resolved by the harness against its built-in registry. Matches the sentinel's own `name`.",
+    ),
+})
+export type SentinelEntry = z.infer<typeof SentinelEntrySchema>
+
+/**
+ * A `lodestar.probe-pack.json` manifest.
+ *
+ * This is the on-disk / on-wire contract every probe pack — first-party
+ * and external — is written against. It is deliberately declarative:
+ * the manifest names probes and their files but contains no executable
+ * logic. The harness loader (in `@qmilab/lodestar-harness`) reads it,
+ * validates it against this schema, and resolves the probe files; the
+ * runner (Batch 4 step 5) executes them.
+ *
+ * `coverage_areas` and `invariants` are free-form taxonomy tags the
+ * pack author declares. They are not validated against a closed list —
+ * the harness uses them for `lodestar harness list` grouping and for
+ * answering "which pack exercises invariant X?", not for gating. Keeping
+ * them open lets external packs name coverage the core taxonomy has not
+ * yet enumerated.
+ */
+export const ProbePackManifestSchema = z.object({
+  name: z
+    .string()
+    .min(1)
+    .regex(
+      /^[a-z0-9]+(?:-[a-z0-9]+)*$/,
+      "pack name must be kebab-case (lowercase alphanumerics separated by single hyphens)",
+    )
+    .describe("Pack identifier, e.g. 'lodestar-core'."),
+  version: z
+    .string()
+    .min(1)
+    .describe("Pack version (the author's, not the spec version). Conventionally semver."),
+  spec_version: z
+    .literal(PROBE_PACK_SPEC_VERSION)
+    .describe(
+      "Manifest-schema spec version. v0 loaders accept only '1' and reject unknown versions with a clear error rather than guessing.",
+    ),
+  source_type: ProbePackSourceTypeSchema.describe(
+    "How the loader resolves probe files. The v0 loader resolves 'local' only.",
+  ),
+  description: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Human-readable one-liner shown by `lodestar harness list`."),
+  coverage_areas: z
+    .array(z.string().min(1))
+    .describe("Free-form tags naming the threat-model / subsystem areas this pack covers."),
+  invariants: z
+    .array(z.string().min(1))
+    .describe("Free-form tags naming the Lodestar invariants this pack's probes exercise."),
+  probes: z
+    .array(ProbeEntrySchema)
+    .min(1, "a pack must declare at least one probe")
+    .describe("The probes this pack ships."),
+  // `.optional()` rather than `.default([])` on purpose: a default makes the
+  // field REQUIRED in the `z.infer` *output* type, so external TS code that
+  // constructs a manifest without `sentinels` would fail to compile — breaking
+  // the "additive optional field is free" promise. Keeping it optional leaves
+  // the public type backward-compatible; the loader treats an absent value as
+  // "no sentinels". Do not reintroduce `.default([])`.
+  sentinels: z
+    .array(SentinelEntrySchema)
+    .optional()
+    .describe(
+      "The sentinels this pack ships, referenced by stable id and resolved by the harness against its built-in registry. Optional; an absent field means the pack ships no sentinels. Additive since spec '1' — a manifest without it still loads.",
+    ),
+})
+export type ProbePackManifest = z.infer<typeof ProbePackManifestSchema>
+
+/**
+ * The manifest filename a `local` pack carries at its root, and the
+ * export key an `npm` pack exposes it under. Defined as a constant so
+ * loaders and pack authors agree on the spelling.
+ */
+export const PROBE_PACK_MANIFEST_FILENAME = "lodestar.probe-pack.json" as const

package/src/schemas/reflection.ts

@@ -0,0 +1,166 @@
+import { z } from "zod"
+import { TruthStatusSchema } from "./belief.js"
+import { TimestampSchema } from "./common.js"
+
+/**
+ * What triggered a reflection pass.
+ *
+ * `cli` — invoked by `lodestar reflect` from a human operator.
+ * `programmatic` — invoked from host code (e.g. runGuarded, the MCP
+ *   proxy) at a deliberate point.
+ * `tail_cascade` — a `belief.transitioned` event recorded a transition
+ *   to `truth_status: contradicted`; the tail watcher dispatched a
+ *   pass to look for dependent fall-out.
+ * `tail_batch` — N `belief.adopted` events have accrued since the
+ *   last pass for the partition (configurable batch size).
+ * `sentinel` — a `sentinel.alerted` event named a `belief_id` as
+ *   subject; the sentinel asked reflection to follow up.
+ */
+export const ReflectionTriggerSchema = z.enum([
+  "cli",
+  "programmatic",
+  "tail_cascade",
+  "tail_batch",
+  "sentinel",
+])
+export type ReflectionTrigger = z.infer<typeof ReflectionTriggerSchema>
+
+/**
+ * The lifecycle axes a reflection proposal can target. Mirrors
+ * `LifecycleAxis` in `@qmilab/lodestar-memory-firewall` deliberately —
+ * the core package cannot import from downstream packages, so the
+ * literal union is duplicated here. Keep these in sync.
+ */
+export const ReflectionLifecycleAxisSchema = z.enum([
+  "truth_status",
+  "retrieval_status",
+  "security_status",
+  "freshness_status",
+])
+export type ReflectionLifecycleAxis = z.infer<typeof ReflectionLifecycleAxisSchema>
+
+/**
+ * Subject of a `no_op` proposal — reflection looked at this thing
+ * and decided no change. Recorded so the audit trail distinguishes
+ * "reflection considered X and did nothing" from "reflection did
+ * not consider X."
+ */
+export const ReflectionSubjectSchema = z.object({
+  kind: z.enum(["belief", "claim", "decision"]),
+  id: z.string(),
+})
+export type ReflectionSubject = z.infer<typeof ReflectionSubjectSchema>
+
+/**
+ * One typed proposal from a reflection pass.
+ *
+ * Proposals are *suggestions*. They do not mutate state. When a
+ * proposal is acted on, the runner calls the existing MemoryFirewall
+ * API with `by_authority: "reflection"`, and the firewall emits its
+ * own normal `belief.adopted` / `belief.transitioned` event whose
+ * `causal_parent_ids` includes the reflection pass's event id.
+ *
+ * The `rationale_id` on every variant points to an Explanation the
+ * runner generated alongside the proposal — same shape as the
+ * Explanations the firewall consumes for transitions.
+ */
+export const ReflectionProposalSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("claim_promotion"),
+    claim_id: z.string(),
+    target_truth_status: TruthStatusSchema,
+    evidence_id: z.string(),
+    rationale_id: z.string(),
+  }),
+  z.object({
+    kind: z.literal("belief_transition"),
+    belief_id: z.string(),
+    axis: ReflectionLifecycleAxisSchema,
+    from_value: z.string(),
+    to_value: z.string(),
+    evidence_id: z.string().optional(),
+    rationale_id: z.string(),
+  }),
+  z.object({
+    kind: z.literal("belief_supersession"),
+    old_belief_id: z.string(),
+    new_belief_id: z.string(),
+    rationale_id: z.string(),
+  }),
+  /**
+   * The decision-dependency cascade. When a belief that a past
+   * Decision depended on transitions to `truth_status: contradicted`,
+   * reflection proposes flagging that Decision as having a contradicted
+   * dependency. Applying the proposal emits a Revision event with
+   * `target_type: "decision"` so the decision's epistemic status
+   * change is recorded in the audit chain. (Closes the Batch-2-deferred
+   * "contradicted belief flags dependent decisions" invariant.)
+   */
+  z.object({
+    kind: z.literal("decision_dependency_flagged"),
+    decision_id: z.string(),
+    contradicted_belief_id: z.string(),
+    /**
+     * The contradicted belief's truth_status BEFORE the transition.
+     * Captured from the firing `belief.transitioned` payload's
+     * `from_value` (defensively a TruthStatus, but stored as the raw
+     * string the transition emitted). Used by the application step
+     * to record an accurate `old_value` in the dependent Decision's
+     * Revision — a belief can transition `unverified → contradicted`
+     * directly, not only from `supported`.
+     */
+    previous_truth_status: TruthStatusSchema,
+    rationale_id: z.string(),
+  }),
+  z.object({
+    kind: z.literal("no_op"),
+    subject: ReflectionSubjectSchema,
+    rationale_id: z.string(),
+  }),
+])
+export type ReflectionProposal = z.infer<typeof ReflectionProposalSchema>
+
+/**
+ * The payload of a `reflection.completed@1` event.
+ *
+ * Idempotence is by cursor: a pass over events with `seq` strictly
+ * greater than `cursor.from_seq` and less than or equal to
+ * `cursor.to_seq` produces the same proposals on re-run. Re-running
+ * is safe — proposals are typed, no state has been mutated, and the
+ * harness can compare proposal sets across runs.
+ *
+ * `observed_event_ids` lists every event the pass actually read.
+ * `proposals` is non-empty in v0 — a pass that found nothing to act
+ * on emits a `no_op` proposal for at least one subject it inspected,
+ * so the harness can distinguish "ran and silent" from "did not run."
+ */
+export const ReflectionCompletedPayloadSchema = z.object({
+  pass_id: z.string(),
+  triggered_by: ReflectionTriggerSchema,
+  cursor: z.object({
+    from_seq: z.number().int().min(-1).describe("-1 if this is the first pass for the partition"),
+    to_seq: z
+      .number()
+      .int()
+      .min(-1)
+      .describe(
+        "Equal to from_seq when the window is empty — the pass ran but observed no new events. " +
+          "Encoded explicitly (rather than skipping emission) so the audit chain can distinguish " +
+          "'reflection ran and was silent' from 'reflection did not run.'",
+      ),
+  }),
+  observed_event_ids: z.array(z.string()),
+  proposals: z
+    .array(ReflectionProposalSchema)
+    .min(1, "every reflection pass emits at least one proposal (no_op counts)"),
+  started_at: TimestampSchema,
+  finished_at: TimestampSchema,
+})
+export type ReflectionCompletedPayload = z.infer<typeof ReflectionCompletedPayloadSchema>
+
+/**
+ * Event-type literal. Use this constant rather than the bare string
+ * so a future rename is grep-safe.
+ */
+export const REFLECTION_COMPLETED_EVENT_TYPE = "reflection.completed" as const
+export const REFLECTION_COMPLETED_SCHEMA_VERSION = "1" as const

package/src/schemas/revision.ts

@@ -13,11 +13,13 @@ export const RevisionSchema = z.object({
   id: z.string(),
   target_type: z.enum(["claim", "belief", "decision"]),
   target_id: z.string(),
-  changes: z.array(z.object({
-    field: z.string(),
-    old_value: z.unknown(),
-    new_value: z.unknown(),
-  })),
+  changes: z.array(
+    z.object({
+      field: z.string(),
+      old_value: z.unknown(),
+      new_value: z.unknown(),
+    }),
+  ),
   triggered_by: z.string().describe("actor_id or event_id"),
   rationale_id: z.string().describe("Explanation id"),
   at: TimestampSchema,

package/src/schemas/sentinel.ts

@@ -0,0 +1,104 @@
+import { z } from "zod"
+import { TimestampSchema } from "./common.js"
+
+/**
+ * Sentinel alerts — the wire format a Sentinel emits when it pattern-matches
+ * a suspicious shape in the event stream.
+ *
+ * Design lock: `docs/architecture/sentinels.md` (and Q7 of
+ * `docs/architecture/reflection-pass.md`, which settled the execution model).
+ * The short version:
+ *
+ * - Sentinels are an async tail of the event stream. They never block the
+ *   Action Kernel; they emit `sentinel.alerted@1` events and a future
+ *   (additive) `arbitrate` hook honours them on the *next* action that
+ *   depends on a flagged subject.
+ * - This is a governance event, not an Observation. Like
+ *   `reflection.completed@1`, the payload is the event payload directly and
+ *   is NOT registered in the observation schema registry.
+ *
+ * Core owns the wire format only. The base class, the runner, and the
+ * concrete sentinels live in `@qmilab/lodestar-harness`.
+ */
+
+/**
+ * What a sentinel alert is *about*. Kept deliberately small — the four
+ * epistemic-chain nouns a v0 sentinel can point at.
+ *
+ * `belief` is the load-bearing kind for the eventual kernel hook: the
+ * `arbitrate` lookup scopes recent alerts to a candidate action's
+ * `belief_dependencies`, so a sentinel that names a belief gates the next
+ * action that leans on it. `tool_sequence` is a synthetic subject — its
+ * `id` identifies the *completion* of a matched sequence (the id of the
+ * final action in the run), since no single chain-noun owns the pattern.
+ */
+export const SentinelSubjectSchema = z.object({
+  kind: z.enum(["belief", "action", "decision", "tool_sequence"]),
+  id: z.string().min(1),
+})
+export type SentinelSubject = z.infer<typeof SentinelSubjectSchema>
+
+/**
+ * Triage weight. `critical` is reserved for patterns that, left unflagged,
+ * map onto a concrete attack (e.g. the read → external-egress → write
+ * exfiltration shape). `warning` is the default for "under-supported but
+ * not obviously hostile". `info` is for advisory signal a calibrator may
+ * later promote or demote.
+ */
+export const SentinelSeveritySchema = z.enum(["info", "warning", "critical"])
+export type SentinelSeverity = z.infer<typeof SentinelSeveritySchema>
+
+/**
+ * The payload of a `sentinel.alerted@1` event.
+ *
+ * `observed_event_ids` lists exactly the events the sentinel read to reach
+ * this conclusion; they are also the alert envelope's `causal_parent_ids`,
+ * so `lodestar report` can walk back from an alert to the events that
+ * triggered it.
+ *
+ * `detail` is rule-specific structured context (offending belief ids, the
+ * matched tool run, the confidence that tripped the floor, …). It is a
+ * record rather than a discriminated union so a new sentinel can ship
+ * without a core schema bump; the human-readable `message` is always
+ * present so an alert is legible without decoding `detail`.
+ *
+ * Every field is required (no optionals besides `rationale_id`) so the
+ * event-log writer's canonical hash and `JSON.stringify` never disagree on
+ * a dropped `undefined` key — the same discipline the firewall audit
+ * events follow.
+ */
+export const SentinelAlertPayloadSchema = z.object({
+  alert_id: z.string().min(1),
+  sentinel_name: z.string().min(1).describe("Stable name of the emitting sentinel."),
+  rule: z
+    .string()
+    .min(1)
+    .describe("Stable id of the specific rule/pattern that fired within the sentinel."),
+  severity: SentinelSeveritySchema,
+  subject: SentinelSubjectSchema,
+  message: z.string().min(1).describe("Human-readable account of what tripped the sentinel."),
+  observed_event_ids: z
+    .array(z.string())
+    .min(1)
+    .describe("The events the sentinel read to reach this alert; also the alert's causal parents."),
+  detail: z
+    .record(z.string(), z.unknown())
+    .describe("Rule-specific structured context. May be empty; never undefined."),
+  detected_at: TimestampSchema,
+  /**
+   * Reserved. A sentinel may attach a generated Explanation id here, the
+   * way reflection proposals carry one. v0 sentinels rely on `message` +
+   * `detail` and leave this unset (omitted entirely, not `undefined`, so
+   * the canonical hash stays stable).
+   */
+  rationale_id: z.string().optional(),
+})
+export type SentinelAlertPayload = z.infer<typeof SentinelAlertPayloadSchema>
+
+/**
+ * Event-type literal and version. Use the constants rather than the bare
+ * string so a future rename is grep-safe — same convention as
+ * `REFLECTION_COMPLETED_EVENT_TYPE`.
+ */
+export const SENTINEL_ALERTED_EVENT_TYPE = "sentinel.alerted" as const
+export const SENTINEL_ALERTED_SCHEMA_VERSION = "1" as const