@qmilab/lodestar-core 0.1.5 → 0.2.0

package/src/schemas/calibration.ts

@@ -0,0 +1,212 @@
+import { z } from "zod"
+import { TimestampSchema } from "./common.js"
+
+/**
+ * Calibration wire format.
+ *
+ * These schemas describe what the harness `Calibrator` measures —
+ * per-class ECE / Brier / calibration-gap tables and the flagged classes.
+ * They lived in `@qmilab/lodestar-harness` while the calibrator was a
+ * return-value-only surface; they **graduated to `@qmilab/lodestar-core`**
+ * when the durable `calibration.computed@1` event landed (ADR-0011), so
+ * the event payload can embed the report (core is the dependency root and
+ * cannot import the harness). The harness re-exports them unchanged, so
+ * harness consumers are unaffected.
+ *
+ * The Calibrator stays measure-only: it returns a {@link CalibrationReport}
+ * and never writes. Recording a report as a `calibration.computed@1` event
+ * is a separate publish step (`lodestar harness calibrate` / the harness
+ * `eventLogCalibrationSink`), the same measure/record split the sentinels
+ * follow (a `Sentinel` returns findings; `eventLogAlertSink` writes them).
+ *
+ * Everything here is validated at the calibrator and event-sink boundaries,
+ * the same discipline the probe-run observation and sentinel-alert builders
+ * hold.
+ */
+
+/**
+ * Which signal in the event log produced a calibration sample.
+ * - `action_outcome`: a belief → decision → action chain where the
+ *   action's realised result (terminal phase or an explicit Outcome) is
+ *   the label.
+ * - `truth_status`: the firewall transitioned the belief's `truth_status`
+ *   to `supported` / `contradicted` — the world adjudicating the belief.
+ */
+export const SampleSourceSchema = z.enum(["action_outcome", "truth_status"])
+export type SampleSource = z.infer<typeof SampleSourceSchema>
+
+/** The scored metrics for a set of samples (one class, or the pool). */
+export const CalibrationMetricsSchema = z.object({
+  n: z.number().int().nonnegative(),
+  /** mean of stated confidence */
+  mean_confidence: z.number().min(0).max(1),
+  /** realised positive rate, mean(correct) */
+  empirical_accuracy: z.number().min(0).max(1),
+  /** mean((p - y)^2); 0 is perfect, lower is better */
+  brier_score: z.number().min(0).max(1),
+  /** expected calibration error over equal-width confidence bins */
+  ece: z.number().min(0).max(1),
+  /** signed mean_confidence - empirical_accuracy; > 0 is overconfident */
+  calibration_gap: z.number().min(-1).max(1),
+  overconfident: z.boolean(),
+})
+export type CalibrationMetrics = z.infer<typeof CalibrationMetricsSchema>
+
+/** One non-empty bin of a reliability diagram. */
+export const ReliabilityBinSchema = z.object({
+  lower: z.number().min(0).max(1),
+  upper: z.number().min(0).max(1),
+  n: z.number().int().positive(),
+  mean_confidence: z.number().min(0).max(1),
+  empirical_accuracy: z.number().min(0).max(1),
+})
+export type ReliabilityBin = z.infer<typeof ReliabilityBinSchema>
+
+/** Per-class result: metrics, the reliability bins, and the verdict. */
+export const CalibrationClassResultSchema = z.object({
+  calibration_class: z.string(),
+  metrics: CalibrationMetricsSchema,
+  /** non-empty bins only, ascending by `lower` */
+  reliability_bins: z.array(ReliabilityBinSchema),
+  flagged: z.boolean(),
+  /** human-legible reason when flagged; `null` when not */
+  flag_reason: z.string().nullable(),
+})
+export type CalibrationClassResult = z.infer<typeof CalibrationClassResultSchema>
+
+/** The thresholds and toggles actually applied, echoed for reproducibility. */
+export const ResolvedCalibratorConfigSchema = z.object({
+  bins: z.number().int().positive(),
+  min_samples: z.number().int().positive(),
+  ece_threshold: z.number().min(0).max(1),
+  gap_threshold: z.number().min(0).max(1),
+  outcome_sources: z.array(SampleSourceSchema).min(1),
+  include_synthetic_authority: z.boolean(),
+})
+export type ResolvedCalibratorConfig = z.infer<typeof ResolvedCalibratorConfigSchema>
+
+/**
+ * The calibrator's output: per-class tables, a pooled `overall` block,
+ * the flagged class names, and the config that produced it. A pure
+ * function of `(events, config)` — no clock, no scope inference — so it
+ * is deterministic and testable, and re-running it over the same event
+ * window reproduces the report (the property the `cursor` on
+ * {@link CalibrationComputedPayloadSchema} makes auditable).
+ */
+export const CalibrationReportSchema = z.object({
+  /** total samples resolved and included (after exclusions) */
+  sample_count: z.number().int().nonnegative(),
+  classes: z.array(CalibrationClassResultSchema),
+  overall: CalibrationMetricsSchema,
+  flagged_classes: z.array(z.string()),
+  config: ResolvedCalibratorConfigSchema,
+})
+export type CalibrationReport = z.infer<typeof CalibrationReportSchema>
+
+// ── The calibration.computed@1 governed event (ADR-0011) ─────────────────
+
+/**
+ * What invoked a calibration pass.
+ *
+ * `cli` — a human ran `lodestar harness calibrate --session <id>`.
+ * `programmatic` — a host computed and recorded calibration from its own
+ *   code (e.g. a guarded loop at a deliberate checkpoint).
+ */
+export const CalibrationTriggerSchema = z.enum(["cli", "programmatic"])
+export type CalibrationTrigger = z.infer<typeof CalibrationTriggerSchema>
+
+/**
+ * The seq window a calibration pass measured.
+ *
+ * Replayability is by cursor: re-running `calibrate` over the same events
+ * in this window — those with `seq` strictly greater than `from_seq` and
+ * less than or equal to `to_seq`, within the event's own session slice —
+ * reproduces the embedded `report` (the calibrator is a pure function of
+ * `(events, config)`). This is what makes calibration drift auditable
+ * across time — two `calibration.computed@1` events with overlapping
+ * windows can be diffed, and either can be recomputed from the log to
+ * verify it was not tampered with. (`seq` is per-project, so the session
+ * slice is the natural replay scope; a v0 calibration pass reads one
+ * session.)
+ */
+export const CalibrationCursorSchema = z
+  .object({
+    from_seq: z
+      .number()
+      .int()
+      .min(-1)
+      .describe(
+        "Exclusive lower bound. The pass measured events with seq strictly greater than this; " +
+          "-1 means from the start of the partition.",
+      ),
+    to_seq: z
+      .number()
+      .int()
+      .min(-1)
+      .describe(
+        "Inclusive upper bound: the highest event seq included. Equal to from_seq when the " +
+          "window is empty (the pass ran but observed no events).",
+      ),
+  })
+  // An inverted window `(from_seq, to_seq]` with `to_seq < from_seq` selects
+  // no events and cannot reproduce a non-empty report — it would persist a
+  // `calibration.computed@1` whose replay guarantee is a lie. Reject it at the
+  // boundary; the empty window `from_seq === to_seq` is the only equality case
+  // (the pass ran but observed nothing), and it satisfies this.
+  .refine((c) => c.to_seq >= c.from_seq, {
+    message: "to_seq must be >= from_seq (an inverted cursor selects no events)",
+    path: ["to_seq"],
+  })
+export type CalibrationCursor = z.infer<typeof CalibrationCursorSchema>
+
+/**
+ * The payload of a `calibration.computed@1` event.
+ *
+ * The durable record of one calibration pass: the verdict (`report`), the
+ * window it measured (`cursor`, for replay), and provenance (`computed_at`,
+ * `triggered_by`, `computation_id`). It does NOT enforce anything — the
+ * Policy Kernel's arbitrate hook reads an in-process `CalibrationReport`
+ * snapshot, not this event (see `docs/architecture/calibrator.md` and
+ * ADR-0011). This event exists so calibration drift is auditable and
+ * replayable, the way a probe run or a sentinel finding already is.
+ *
+ * Not signed in v0: the event inherits the log's canonical-hash
+ * tamper-evidence, and nothing un-parks a held action on the strength of a
+ * calibration *event* (the gate only ever escalates — the conservative
+ * direction). If a future slice makes the gate consume persisted
+ * calibration events as an authority, signing graduates then, the same
+ * staged path the approval resolution followed (ADR-0010).
+ */
+export const CalibrationComputedPayloadSchema = z
+  .object({
+    /** Stable id for this pass, so the audit chain can reference it. */
+    computation_id: z.string().min(1),
+    triggered_by: CalibrationTriggerSchema,
+    /** The seq window measured — re-running `calibrate` over it reproduces `report`. */
+    cursor: CalibrationCursorSchema,
+    /** The verdict: the full report this pass produced. */
+    report: CalibrationReportSchema,
+    computed_at: TimestampSchema,
+  })
+  // The cursor is only an honest replay key if it is *consistent* with the
+  // report. An empty window `(n, n]` selects zero events, so it can reproduce
+  // only a zero-sample report — and a zero-sample report can only have come
+  // from an empty window. Enforce the biconditional: empty window ⟺
+  // `sample_count === 0`. This rejects the two non-replayable shapes a
+  // programmatic caller could otherwise persist — an empty window carrying a
+  // populated report (replaying it yields nothing), and a populated window
+  // carrying a zero-sample report (the window's events would yield samples).
+  .refine((p) => (p.cursor.to_seq === p.cursor.from_seq) === (p.report.sample_count === 0), {
+    message:
+      "an empty cursor window (to_seq === from_seq) must accompany a zero-sample report and vice " +
+      "versa — otherwise the recorded window cannot reproduce the report it claims as its replay key",
+    path: ["cursor", "to_seq"],
+  })
+export type CalibrationComputedPayload = z.infer<typeof CalibrationComputedPayloadSchema>
+
+/**
+ * Event-type literal. Use this constant rather than the bare string so a
+ * future rename is grep-safe. Mirrors `reflection.completed@1`.
+ */
+export const CALIBRATION_COMPUTED_EVENT_TYPE = "calibration.computed" as const
+export const CALIBRATION_COMPUTED_SCHEMA_VERSION = "1" as const

package/src/schemas/claim.ts

@@ -1,5 +1,10 @@
 import { z } from "zod"
-import { PredicateSchema, ResourceScopeSchema, SensitivitySchema, TimestampSchema } from "./common.js"
+import {
+  PredicateSchema,
+  ResourceScopeSchema,
+  SensitivitySchema,
+  TimestampSchema,
+} from "./common.js"
 
 /**
  * How a claim was extracted from observation(s).
@@ -36,7 +41,9 @@ export const ClaimSchema = z.object({
   id: z.string(),
   statement: z.string().describe("human-readable claim"),
   structured_predicate: PredicateSchema.optional().describe("for queryable claims"),
-  source_observation_ids: z.array(z.string()).min(1, "a claim must reference at least one observation"),
+  source_observation_ids: z
+    .array(z.string())
+    .min(1, "a claim must reference at least one observation"),
   extraction_method: ExtractionMethodSchema,
   extracted_by: z.string().describe("actor_id of the extractor"),
   status: ClaimStatusSchema,
@@ -60,12 +67,12 @@ export type Claim = z.infer<typeof ClaimSchema>
  * a scoring function.
  */
 export const EvidenceQualitySchema = z.enum([
-  "direct_observation",   // tool output describing world state
-  "tool_result",          // computed result from a tool
-  "human_assertion",      // user said so
-  "model_inference",      // an LLM concluded so from other context
-  "external_document",    // file, webpage, email — high risk for poisoning
-  "synthetic_probe",      // from a Harness probe; never affects real beliefs
+  "direct_observation", // tool output describing world state
+  "tool_result", // computed result from a tool
+  "human_assertion", // user said so
+  "model_inference", // an LLM concluded so from other context
+  "external_document", // file, webpage, email — high risk for poisoning
+  "synthetic_probe", // from a Harness probe; never affects real beliefs
 ])
 export type EvidenceQuality = z.infer<typeof EvidenceQualitySchema>
 

package/src/schemas/common.ts

@@ -15,21 +15,25 @@ export type Sensitivity = z.infer<typeof SensitivitySchema>
  * Scope a claim, belief, memory, or action applies to. Hierarchical
  * from broadest (global) to narrowest (session).
  */
-export const ResourceScopeSchema = z.object({
-  level: z.enum(["global", "organization", "user", "project", "repo", "session"]),
-  identifier: z.string().describe("identifier within the scope level, e.g. project_id"),
-}).describe("Scope that bounds where a claim, belief, or memory applies")
+export const ResourceScopeSchema = z
+  .object({
+    level: z.enum(["global", "organization", "user", "project", "repo", "session"]),
+    identifier: z.string().describe("identifier within the scope level, e.g. project_id"),
+  })
+  .describe("Scope that bounds where a claim, belief, or memory applies")
 export type ResourceScope = z.infer<typeof ResourceScopeSchema>
 
 /**
  * Structured predicate for queryable claims and beliefs.
  * Free-form for v0; refined in later versions as the planner matures.
  */
-export const PredicateSchema = z.object({
-  subject: z.string(),
-  relation: z.string(),
-  object: z.unknown(),
-}).describe("Structured form of a claim suitable for queries")
+export const PredicateSchema = z
+  .object({
+    subject: z.string(),
+    relation: z.string(),
+    object: z.unknown(),
+  })
+  .describe("Structured form of a claim suitable for queries")
 export type Predicate = z.infer<typeof PredicateSchema>
 
 /**
@@ -41,7 +45,9 @@ export type Timestamp = z.infer<typeof TimestampSchema>
 /**
  * ISO 8601 duration string (e.g. "P30D", "PT1H").
  */
-export const DurationSchema = z.string().regex(/^P(?:\d+Y)?(?:\d+M)?(?:\d+W)?(?:\d+D)?(?:T(?:\d+H)?(?:\d+M)?(?:\d+(?:\.\d+)?S)?)?$/)
+export const DurationSchema = z
+  .string()
+  .regex(/^P(?:\d+Y)?(?:\d+M)?(?:\d+W)?(?:\d+D)?(?:T(?:\d+H)?(?:\d+M)?(?:\d+(?:\.\d+)?S)?)?$/)
 export type Duration = z.infer<typeof DurationSchema>
 
 /**

package/src/schemas/policy.ts

@@ -0,0 +1,231 @@
+import { z } from "zod"
+import {
+  BlastRadiusSchema,
+  DataSensitivityForActionSchema,
+  ReversibilitySchema,
+  TrustLevelSchema,
+} from "./action.js"
+import { SignatureSchema } from "./actor.js"
+import { ResourceScopeSchema, SensitivitySchema } from "./common.js"
+
+/**
+ * Action policy — the wire format for what actions may touch the world.
+ *
+ * Design lock: `docs/architecture/policy-kernel.md`. The short version:
+ *
+ * - Policy is a *declarative document*, not a function. Today's enforcement
+ *   is an opaque `PolicyGate` closure (the `autoApprovePolicy` preset). The
+ *   Policy Kernel compiles a `Policy` document into that gate, so the verdict
+ *   becomes data — addressable, hashable, signable, and citable by
+ *   `Decision.policy_dependencies`.
+ * - Rules are evaluated *in order*; the first decisive rule wins, over a
+ *   *structural* deny default. There is deliberately no `default` field and
+ *   no expressible `default: allow` — the safe outcome is structural, not a
+ *   rule someone can forget to add ("no silent defaults for security-relevant
+ *   settings", root CLAUDE.md).
+ * - The *trust-ladder floor* (L5 deny, L4 always require_approval) is a
+ *   non-overridable pre-check applied *before* the rule list, in the engine —
+ *   it is NOT expressed as a rule, so no broad earlier `allow` can lift it.
+ *
+ * Not to be confused with `ContextPolicy` (`belief.ts`), which governs what
+ * beliefs may enter model context. This `Policy` governs what actions may
+ * touch the world — a different gate on a different chain link.
+ *
+ * Core owns the wire format only. The engine — `compile(policy) → PolicyGate`,
+ * the three-valued gate, signature verification, the arbitrate hook — lives in
+ * `@qmilab/lodestar-policy-kernel`.
+ */
+
+/**
+ * The declarative effect of a matched rule.
+ *
+ * `require_approval` is the *declarative* counterpart of the gate's runtime
+ * `hold` verdict: a matched `require_approval` rule causes the engine to park
+ * the action at `pending_approval` and open an `ApprovalRequest`. (The runtime
+ * three-valued verdict `allow | deny | hold` is an engine type and lives in
+ * `@qmilab/lodestar-policy-kernel`, not in the wire format.)
+ */
+export const PolicyEffectSchema = z.enum(["allow", "deny", "require_approval"])
+export type PolicyEffect = z.infer<typeof PolicyEffectSchema>
+
+/**
+ * The match clause of a rule. All present fields must hold (AND); an absent
+ * field is a wildcard. A rule with an empty `match` matches every action.
+ *
+ * The fields constrain an `ActionContract` (`action.ts`):
+ * - `tool` is a glob over the tool registry key (e.g. `"git.*"`).
+ * - `max_blast_radius` matches contracts at or below this radius on the
+ *   ordering self < session < project < external (the comparison is engine
+ *   logic; the schema stores the ceiling).
+ * - `reversibility` is the set the contract's reversibility must be a member
+ *   of (e.g. `["reversible", "compensable"]` excludes `irreversible`).
+ * - `scope` constrains the contract's `ResourceScope`.
+ * - `data_sensitivity` matches the contract's 3-value action sensitivity.
+ * - `required_level_lte` matches contracts whose `required_level` is at or
+ *   below this trust level.
+ */
+export const PolicyMatchSchema = z.object({
+  tool: z.string().min(1).optional().describe("glob over the tool registry key, e.g. 'git.*'"),
+  max_blast_radius: BlastRadiusSchema.optional().describe(
+    "matches contracts at or below this blast radius (self < session < project < external)",
+  ),
+  reversibility: z
+    .array(ReversibilitySchema)
+    .min(1)
+    .optional()
+    .describe("the set the contract's reversibility must be a member of"),
+  scope: ResourceScopeSchema.optional().describe("constrains the contract's ResourceScope"),
+  data_sensitivity: DataSensitivityForActionSchema.optional().describe(
+    "matches the contract's 3-value action sensitivity",
+  ),
+  required_level_lte: TrustLevelSchema.optional().describe(
+    "matches contracts whose required_level is at or below this",
+  ),
+})
+export type PolicyMatch = z.infer<typeof PolicyMatchSchema>
+
+/**
+ * Constraints an approver must satisfy to resolve a held action. *Data, not a
+ * callback* — it says *what* an approver must be, checked against the
+ * resolver's `Actor`. This is what lets a team approval surface route a
+ * request to the right person without the Policy Kernel knowing anything
+ * about people. All fields optional; an empty object means "any actor the
+ * host has configured as a resolver may approve".
+ *
+ * The clearance check spans two alphabets: an action's `data_sensitivity` is
+ * the 3-value `public | private | secret`, an `Actor.sensitivity_clearance`
+ * is the 4-value `Sensitivity`. `sensitivity_clearance` here is the *4-value*
+ * `Sensitivity` — the action's sensitivity *mapped* via the Action Kernel's
+ * `sensitivityForContract` (`public→public`, `private→internal`,
+ * `secret→secret`) — so the approver-side comparison happens in one alphabet.
+ */
+export const RequiredAuthoritySchema = z.object({
+  min_trust_baseline: z
+    .number()
+    .min(0)
+    .max(1)
+    .optional()
+    .describe("floor on an approver's Actor.trust_baseline"),
+  sensitivity_clearance: SensitivitySchema.optional().describe(
+    "4-value clearance the approver must hold; the action's data_sensitivity mapped via sensitivityForContract",
+  ),
+  scope: ResourceScopeSchema.optional().describe("ResourceScope the approver must hold"),
+})
+export type RequiredAuthority = z.infer<typeof RequiredAuthoritySchema>
+
+/**
+ * The approval requirement carried by a `require_approval` rule. When the rule
+ * fires, its `required_authority` becomes the opened `ApprovalRequest`'s
+ * `required_authority`. Omitting `required_authority` (or the whole
+ * `approval` object) means any configured resolver may approve.
+ *
+ * A thin wrapper today; it is the seam where multi-approver / N-of-M
+ * constraints attach when the team approval surface is built (deferred —
+ * `policy-kernel.md`, "a separate team surface").
+ */
+export const ApprovalRequirementSchema = z.object({
+  required_authority: RequiredAuthoritySchema.optional().describe(
+    "constraints an approver must satisfy; omitted means any configured resolver may approve",
+  ),
+})
+export type ApprovalRequirement = z.infer<typeof ApprovalRequirementSchema>
+
+/**
+ * One match → effect rule. Evaluated in document order; the first rule whose
+ * `match` holds is decisive. `reason` is surfaced verbatim in the
+ * `PolicyDecision` (and, for a held action, in the `ApprovalRequest`).
+ *
+ * `approval` may be present only on a `require_approval` rule (enforced
+ * below). It is not *required* there — an absent `approval` means the hold has
+ * no authority constraints (any configured resolver may approve), which is a
+ * meaningful default, so it is left optional rather than forced to an empty
+ * object.
+ */
+export const PolicyRuleSchema = z
+  .object({
+    match: PolicyMatchSchema,
+    effect: PolicyEffectSchema,
+    approval: ApprovalRequirementSchema.optional().describe(
+      "present only on a require_approval rule; carries the authority an approver must hold",
+    ),
+    reason: z
+      .string()
+      .min(1)
+      .describe("surfaced verbatim in the PolicyDecision and ApprovalRequest"),
+  })
+  .superRefine((rule, ctx) => {
+    if (rule.approval !== undefined && rule.effect !== "require_approval") {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["approval"],
+        message: "approval may only be set on a rule whose effect is 'require_approval'",
+      })
+    }
+  })
+export type PolicyRule = z.infer<typeof PolicyRuleSchema>
+
+/**
+ * A signed, packageable action-policy document.
+ *
+ * `version` is the monotonic string that `Decision.policy_dependencies` cites,
+ * so an audit can resolve exactly which policy version arbitrated an action.
+ *
+ * `signature` / `signed_by` are *optional at the schema level* so that
+ * unsigned **drafts** parse, but `v02-delta.md` §5 lists policy versions among
+ * the artifacts that *require* Ed25519 signatures: the Policy Kernel rejects an
+ * unsigned (or invalid-signature) policy at the gate, except under an explicit,
+ * logged `allow_unsigned: true` development opt-in. The signer is
+ * `signature.signer_id`; `signed_by` is a top-level convenience that must
+ * equal it when a signature is present (enforced below) — never a second,
+ * divergeable source of truth.
+ *
+ * The signature is computed over the *canonical document without the
+ * signature* — `{ id, version, rules }` — since a document cannot sign over
+ * its own signature. That canonical hash is what `signature.payload_hash`
+ * carries and what `Decision.policy_dependencies` ultimately pins.
+ */
+export const PolicySchema = z
+  .object({
+    id: z.string().min(1).describe("stable policy id"),
+    version: z
+      .string()
+      .min(1)
+      .describe("monotonic version; this is the string Decision.policy_dependencies cites"),
+    rules: z
+      .array(PolicyRuleSchema)
+      .describe("evaluated in order; first decisive rule wins, over a structural deny default"),
+    signature: SignatureSchema.optional().describe(
+      "Ed25519 over the canonical document { id, version, rules }; required at the gate for an active policy",
+    ),
+    signed_by: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(
+        "actor_id of the signer; present iff signature is present, and equals signature.signer_id",
+      ),
+  })
+  .superRefine((policy, ctx) => {
+    if (policy.signature !== undefined) {
+      if (policy.signed_by === undefined) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["signed_by"],
+          message: "signed_by must be present when signature is present",
+        })
+      } else if (policy.signed_by !== policy.signature.signer_id) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["signed_by"],
+          message: "signed_by must equal signature.signer_id",
+        })
+      }
+    } else if (policy.signed_by !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["signed_by"],
+        message: "signed_by must be omitted when signature is absent (unsigned draft)",
+      })
+    }
+  })
+export type Policy = z.infer<typeof PolicySchema>