@qmilab/lodestar-core 0.1.5 → 0.2.0

package/dist/schemas/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/schemas/policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAUvB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,kDAAgD,CAAA;AAC/E,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAE7D;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiB5B,CAAA;AACF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAE3D;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWlC,CAAA;AACF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAEvE;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAIpC,CAAA;AACF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAE3E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoBzB,CAAA;AACJ,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAEzD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2CrB,CAAA;AACJ,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAA"}

package/dist/schemas/policy.js

@@ -0,0 +1,200 @@
+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"]);
+/**
+ * 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"),
+});
+/**
+ * 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"),
+});
+/**
+ * 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"),
+});
+/**
+ * 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'",
+        });
+    }
+});
+/**
+ * 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)",
+        });
+    }
+});
+//# sourceMappingURL=policy.js.map

package/dist/schemas/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/schemas/policy.ts"],"names":[],"mappings":"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"}

package/dist/schemas/probe-pack.d.ts

@@ -0,0 +1,152 @@
+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 declare const PROBE_PACK_SPEC_VERSION: "1";
+/**
+ * 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 declare const ProbePackSourceTypeSchema: z.ZodEnum<["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 declare const ProbeEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    file: z.ZodEffects<z.ZodString, string, string>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    file: string;
+}, {
+    name: string;
+    file: string;
+}>;
+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 declare const SentinelEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+}, {
+    id: string;
+}>;
+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 declare const ProbePackManifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    spec_version: z.ZodLiteral<"1">;
+    source_type: z.ZodEnum<["local", "npm"]>;
+    description: z.ZodOptional<z.ZodString>;
+    coverage_areas: z.ZodArray<z.ZodString, "many">;
+    invariants: z.ZodArray<z.ZodString, "many">;
+    probes: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        file: z.ZodEffects<z.ZodString, string, string>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        file: string;
+    }, {
+        name: string;
+        file: string;
+    }>, "many">;
+    sentinels: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+    }, {
+        id: string;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    version: string;
+    spec_version: "1";
+    source_type: "local" | "npm";
+    coverage_areas: string[];
+    invariants: string[];
+    probes: {
+        name: string;
+        file: string;
+    }[];
+    description?: string | undefined;
+    sentinels?: {
+        id: string;
+    }[] | undefined;
+}, {
+    name: string;
+    version: string;
+    spec_version: "1";
+    source_type: "local" | "npm";
+    coverage_areas: string[];
+    invariants: string[];
+    probes: {
+        name: string;
+        file: string;
+    }[];
+    description?: string | undefined;
+    sentinels?: {
+        id: string;
+    }[] | undefined;
+}>;
+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 declare const PROBE_PACK_MANIFEST_FILENAME: "lodestar.probe-pack.json";
+//# sourceMappingURL=probe-pack.d.ts.map

package/dist/schemas/probe-pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe-pack.d.ts","sourceRoot":"","sources":["../../src/schemas/probe-pack.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,KAAe,CAAA;AAEnD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,6BAA2B,CAAA;AACjE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAE3E;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;EAuB3B,CAAA;AACF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,mBAAmB;;;;;;EAW9B,CAAA;AACF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAE/D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgDlC,CAAA;AACF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAEvE;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,4BAAsC,CAAA"}

package/dist/schemas/probe-pack.js

@@ -0,0 +1,140 @@
+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";
+/**
+ * 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"]);
+/**
+ * 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)."),
+});
+/**
+ * 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`."),
+});
+/**
+ * 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."),
+});
+/**
+ * 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";
+//# sourceMappingURL=probe-pack.js.map

package/dist/schemas/probe-pack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe-pack.js","sourceRoot":"","sources":["../../src/schemas/probe-pack.ts"],"names":[],"mappings":"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"}