failproofai 1.0.8 → 1.0.9-beta.1

package/src/hooks/jev-activity.ts

@@ -57,7 +57,7 @@ export const JEV_ACTIVITY_KEYS = [
 
 const EVALUATORS = new Set(["jev", "jev-fallback"]);
 const DECISIONS = new Set(["allow", "instruct", "deny"]);
-const MODES = new Set(["shadow", "enforce"]);
+const MODES = new Set(["observe", "enforce"]);
 
 /**
  * A reason's leading code — lowercase kebab-case — either alone or followed by
@@ -236,7 +236,12 @@ export function sanitizeJevActivity<T extends JevActivityFields>(entry: T): T {
 
   if (!(typeof out.evaluator === "string" && EVALUATORS.has(out.evaluator))) drop("evaluator");
   if (!(typeof out.jevDecision === "string" && DECISIONS.has(out.jevDecision))) drop("jevDecision");
+  // A mode this build does not know (a row written before the mode was named
+  // `observe`) cannot say whether its clears were enforced, so they are not
+  // counted as anything: dropping only the mode would file them as enforced.
+  const unknownMode = out.jevMode !== undefined && !(typeof out.jevMode === "string" && MODES.has(out.jevMode));
   if (!(typeof out.jevMode === "string" && MODES.has(out.jevMode))) drop("jevMode");
+  if (unknownMode) drop("jevCleared");
 
   if (Array.isArray(out.jevCleared)) {
     const names = [
@@ -374,9 +379,9 @@ export function describeJevActivity(raw: JevActivityFields): string[] | null {
   if (e.jevDecision) facts.push(`Jev verdict: ${e.jevDecision}`);
   const cleared = e.jevCleared ?? [];
   if (cleared.length > 0) {
-    facts.push(`${e.jevMode === "shadow" ? "would have cleared" : "cleared"} ${cleared.join(", ")}`);
+    facts.push(`${e.jevMode === "observe" ? "would have cleared" : "cleared"} ${cleared.join(", ")}`);
   }
-  if (e.jevMode === "shadow") facts.push("shadow mode: the regex result was enforced");
+  if (e.jevMode === "observe") facts.push("observe mode: the regex result was enforced");
   if (e.jevLatencyMs !== undefined) facts.push(`${e.jevLatencyMs} ms`);
   if (e.jevModel) facts.push(e.jevModel);
   // Answered, but nothing this build can show (a verdict in a shape it cannot read).

package/src/hooks/jev-cli.ts

@@ -186,7 +186,7 @@ export const JEV_USAGE = [
   "Usage:",
   "  failproofai jev --url <url> [--key-stdin | --token <token>] [options]",
   "  failproofai jev setup --provider <kind> [--key-stdin | --key-from-env] [options]",
-  "  failproofai jev setup --provider failproofai [--mode off|shadow|enforce]   (FailproofAI Cloud: no key, no URL)",
+  "  failproofai jev setup --provider failproofai [--mode off|observe|enforce]   (FailproofAI Cloud: no key, no URL)",
   "  failproofai jev status [--json]",
   "  failproofai jev test [--json]",
   "  failproofai jev models [--provider <kind>] [--url <base>] [--json]",
@@ -269,7 +269,7 @@ function modeLine(mode: NonNullable<JevConfig["mode"]>): string {
   if (mode === "off") return "off — Jev is not asked at all; the regex policies decide alone";
   return mode === "enforce"
     ? "enforce — Jev's verdicts apply: it may clear a reviewable policy's deny and add its own"
-    : "shadow — Jev is asked and logged; the regex result is what is enforced";
+    : "observe — Jev is asked and logged; the regex result is what is enforced";
 }
 
 /**
@@ -458,12 +458,11 @@ export function jevStatsLines(stats: JevStats | null, opts: RenderOpts = {}): st
       .join(", ");
   const clears = byPolicy(stats.clearsByPolicy);
   // `clearsByPolicy` counts clears that CHANGED an outcome, which only enforce
-  // mode can do; in shadow mode every clear Jev would have made is in
-  // `shadowClearsByPolicy` instead and this one is empty. Printing the first
-  // alone would tell a shadow user "cleared nothing" — the one number they
-  // turned shadow mode on to watch. The field is optional because the stats
-  // module T1 builds against does not have it yet (T8 adds it).
-  const shadowClears = byPolicy((stats as { shadowClearsByPolicy?: Record<string, number> }).shadowClearsByPolicy);
+  // mode can do; in observe mode every clear Jev would have made is in
+  // `observeClearsByPolicy` instead and this one is empty. Printing the first
+  // alone would tell an observe-mode user "cleared nothing" — the one number
+  // they turned observe mode on to watch.
+  const observeClears = byPolicy(stats.observeClearsByPolicy);
   const ms = (v: number | null) => (v === null ? "—" : `${Math.round(v)} ms`);
   return stack(
     heading,
@@ -473,7 +472,7 @@ export function jevStatsLines(stats: JevStats | null, opts: RenderOpts = {}): st
         ["fell back to regex", `${pct(stats.fallbackRate)}${reasons ? ` (${reasons})` : ""}`],
         ["latency", `p50 ${ms(stats.latencyP50Ms)} · p95 ${ms(stats.latencyP95Ms)}`],
         ["cleared", clears || "nothing"],
-        ...(shadowClears ? ([["would have cleared (shadow)", shadowClears]] as Array<[string, string]>) : []),
+        ...(observeClears ? ([["would have cleared (observe)", observeClears]] as Array<[string, string]>) : []),
       ],
       opts,
     ),
@@ -1206,11 +1205,10 @@ async function cloudSetup(values: Map<string, string>, bools: Set<string>, opts:
   delete next.apiKey;
   delete next.accountId;
   if (!sameProvider && existing?.raw.timeoutMs !== undefined) next.timeoutMs = existing.raw.timeoutMs;
-  // Shadow unless told otherwise, as `config --token` starts it: Jev on a new
+  // Observe unless told otherwise, as `config --token` starts it: Jev on a new
   // route is logged before it is allowed to clear anything. A mode already in a
   // Cloud file is kept.
-  const mode = values.get("--mode") ?? (sameProvider && typeof next.mode === "string" ? next.mode : "shadow");
-  next.mode = mode;
+  next.mode = values.get("--mode") ?? (sameProvider && typeof next.mode === "string" ? next.mode : "observe");
   if (values.has("--timeout-ms")) {
     const rawTimeout = values.get("--timeout-ms") as string;
     const n = Number(rawTimeout);
@@ -1247,7 +1245,7 @@ async function cloudSetup(values: Map<string, string>, bools: Set<string>, opts:
           ]
         : [
             "Not saved: this machine is not connected to FailproofAI Cloud with a key that carries jev:evaluate.",
-            "Connect it with one that does (the \"machine\" preset) — that also turns Jev on, in shadow mode, when there is no jev.json yet:",
+            "Connect it with one that does (the \"machine\" preset) — that also turns Jev on, in observe mode, when there is no jev.json yet:",
           ]),
       "  failproofai config --token <key>",
       "",
@@ -1332,7 +1330,7 @@ async function cloudSetup(values: Map<string, string>, bools: Set<string>, opts:
 /**
  * Where a file would send requests, for display, whether or not it loads. Only
  * the routing fields are used — the key and model do not decide where requests
- * go — and shadow mode lets a loopback http URL through validation. Null when
+ * go — and observe mode lets a loopback http URL through validation. Null when
  * it names nothing recognisable.
  */
 /**
@@ -1366,7 +1364,7 @@ function displayOnlyCloudOrigin(routing: { provider?: unknown; baseUrl?: unknown
 
 function namedEndpoint(raw: Record<string, unknown> | null): string | null {
   if (!raw || typeof raw.provider !== "string" || !(JEV_PROVIDER_KINDS as readonly string[]).includes(raw.provider)) return null;
-  const routing: Record<string, unknown> = { provider: raw.provider, apiKey: ENV_KEY_STAND_IN, mode: "shadow", ...displayOnlyCloudOrigin(raw) };
+  const routing: Record<string, unknown> = { provider: raw.provider, apiKey: ENV_KEY_STAND_IN, mode: "observe", ...displayOnlyCloudOrigin(raw) };
   if (raw.baseUrl !== undefined) routing.baseUrl = raw.baseUrl;
   if (raw.accountId !== undefined) routing.accountId = raw.accountId;
   try {
@@ -1499,6 +1497,8 @@ async function status(argv: string[], opts: RenderOpts): Promise<JevCliResult> {
                 enabled: coverage.enabled,
                 reviewable: coverage.reviewable,
                 customPolicyFiles: coverage.customFiles,
+                // Checks an installed pack gives Jev to ask; 0 means Jev is inert.
+                jevChecks: coverage.jevChecks,
                 problem: coverageProblem,
               },
             }
@@ -1599,7 +1599,7 @@ async function status(argv: string[], opts: RenderOpts): Promise<JevCliResult> {
           ],
           opts,
         ),
-        nextStep("failproofai jev setup --mode shadow", "Switch it back on (shadow logs Jev and keeps enforcing regex; enforce lets it clear), here or from the dashboard:", opts),
+        nextStep("failproofai jev setup --mode observe", "Switch it back on (observe logs Jev and keeps enforcing regex; enforce lets it clear), here or from the dashboard:", opts),
         legacyNote,
         jevStatsLines(stats, opts),
       ),
@@ -1786,7 +1786,7 @@ async function test(argv: string[], deps: JevCliDeps, opts: RenderOpts): Promise
       : inspection.status === "key-missing"
         ? "failproofai jev setup --key-stdin < key-file"
         : inspection.status === "off"
-          ? "failproofai jev setup --mode shadow"
+          ? "failproofai jev setup --mode observe"
           : inspection.status === "not-connected" || inspection.status === "key-lacks-jev"
             ? "failproofai config --token <key>"
             : "failproofai jev setup --provider <kind> --key-stdin";

package/src/hooks/jev-cloud-connection.ts

@@ -4,7 +4,7 @@
  * `config --token` with a key that carries `jev:evaluate` stores the key in the
  * `jev` slot of `credentials.json` (`cloud-connection.ts`) and then, ONLY when
  * this machine has no `jev.json` at all, writes one that turns Jev on through
- * FailproofAI Cloud in shadow mode — logged, never enforced, until its owner
+ * FailproofAI Cloud in observe mode — logged, never enforced, until its owner
  * says otherwise. Never under `--no-transcripts`: that connection asked for
  * decisions only, so it stores the key and says Jev is available, and
  * `jev setup --provider failproofai` is the opt-in. `config --disconnect`
@@ -29,7 +29,7 @@
  * status screen. A BYOK file keeps working without the Cloud and is not the
  * Cloud's to delete, so it stays; so does a file this build cannot read, and a
  * Cloud file switched off — `--mode off` is the owner's opt-out, and deleting
- * it would let the next connect write a fresh shadow file. The
+ * it would let the next connect write a fresh observe-mode file. The
  * file is moved aside before it is judged, so the file judged is the file
  * deleted — see `removeCloudJevConfig`.
  *
@@ -67,7 +67,7 @@ import {
 } from "./semantic/jev-config";
 
 /** The mode a Cloud `jev.json` starts in (the user's decision: log first, enforce later). */
-export const CLOUD_JEV_INITIAL_MODE = "shadow" as const;
+export const CLOUD_JEV_INITIAL_MODE = "observe" as const;
 
 export type CloudJevConfigWrite =
   | { status: "written"; path: string; mode: typeof CLOUD_JEV_INITIAL_MODE; baseUrl: string }
@@ -145,7 +145,7 @@ export function existingJevConfig(cloudBase: string): CloudJevConfigWrite | null
  * Asked the way a hook asks (`inspectJevConfig`), so "on" here means a tool
  * call's next Jev request really goes to FailproofAI Cloud.
  */
-export function cloudJevRunningMode(): "shadow" | "enforce" | null {
+export function cloudJevRunningMode(): "observe" | "enforce" | null {
   try {
     const r = inspectJevConfig();
     if (r.status !== "ok" || r.config.provider !== JEV_CLOUD_PROVIDER) return null;

package/src/hooks/manager.ts

@@ -28,7 +28,7 @@ import { customPoliciesDir, globalPolicyConfigFile } from "./fp-home";
 import { readActiveCloudManagedPolicies } from "./cloud-managed-policies";
 import { CORE_SOURCE, addPack, setPackPolicyEnabled } from "./pack-store";
 import type { ResolvedPack } from "./pack-manifest";
-import { hasInstalledPacks, readInstalledPacks } from "./pack-manifest";
+import { hasInstalledRegexPacks, readInstalledPacks } from "./pack-manifest";
 import { packPolicyParamKey } from "./policy-evaluator";
 import { probeDaemonPolicyEvaluation } from "./daemon-service";
 import {
@@ -654,7 +654,8 @@ async function installHooksImpl(
     //
     // With a pack already installed the names are switched on individually
     // instead, which is additive and touches nothing else.
-    if (!hasInstalledPacks()) {
+    // A Jev-only pack has no policy to switch on, so it does not count here.
+    if (!hasInstalledRegexPacks()) {
       // Fetched, not unpacked from this package: there is no copy in here any
       // more. That makes this the one path in `policies --install` that needs
       // the network, so its failure is reported rather than thrown — the names

package/src/hooks/pack-cli.ts

@@ -26,7 +26,7 @@ import { compareVersions, parseSemver } from "./semver-precedence";
 // budget, which means reaching the semantic side. This is a CLI module — loaded
 // by `failproofai publish`, never by a hook — so the rule that keeps those
 // modules off an unconfigured machine's hook path does not apply here.
-import { BUILTIN_QUESTION_CHARS, MAX_PACK_QUESTION_CHARS, questionChars, semanticPoliciesFromPacks } from "./semantic/pack-policies";
+import { JEV_POLICIES_QUESTION_CHARS, MAX_PACK_QUESTION_CHARS, questionChars, semanticPoliciesFromPacks } from "./semantic/pack-policies";
 import {
   AmbiguousPackId,
   PACK_CHECKSUMS_ASSET,
@@ -484,19 +484,20 @@ async function build(rest: string[]): Promise<PackCliResult> {
   // the user's machine, in manifest order — a pack that enforces less than it
   // says, which is the failure this whole lane is built to avoid.
   //
-  // A pack from outside FailproofAI is ADDED to the built-in checks, which every
-  // machine spends the budget on first (`semanticPoliciesFromPacks`), so it gets
-  // only what they leave.
+  // A pack from outside FailproofAI shares one request with FailproofAI's own
+  // checks wherever both are installed, and those spend the budget first
+  // (`semanticPoliciesFromPacks`), so it is held to what they leave.
   const questionCost = semantic.reduce((total, entry) => total + questionChars(entry), 0);
   const firstParty = isFirstPartyPack(packSource);
-  const questionBudget = MAX_PACK_QUESTION_CHARS - (firstParty ? 0 : BUILTIN_QUESTION_CHARS);
+  const questionBudget = MAX_PACK_QUESTION_CHARS - (firstParty ? 0 : JEV_POLICIES_QUESTION_CHARS);
   if (questionCost > questionBudget) {
     return fail([
       `This pack's ${semantic.length} semantic policies compile to ${questionCost} characters of questions, ` +
         (firstParty
           ? `over the ${MAX_PACK_QUESTION_CHARS} one Jev request has room for.`
           : `over the ${questionBudget} a machine leaves a pack from outside FailproofAI: one Jev request has room ` +
-            `for ${MAX_PACK_QUESTION_CHARS}, and the 16 built-in checks every machine asks take ${BUILTIN_QUESTION_CHARS} of it first.`),
+            `for ${MAX_PACK_QUESTION_CHARS}, and FailproofAI/jev-policies' 16 checks take ${JEV_POLICIES_QUESTION_CHARS} of it first ` +
+            `where both are installed.`),
       "Shorten the probe instructions and criteria, or ship fewer policies per pack.",
     ]);
   }
@@ -511,9 +512,9 @@ async function build(rest: string[]): Promise<PackCliResult> {
   // Judged against the reviewers the PACK SHIPS WITH, not this build's: a pack
   // that carries both tiers replaces the compiled semantic set on every machine
   // that installs it, so `reviewedBy: ["its-own-check"]` is exactly right and
-  // the builtin list would call it a name "this build does not have". A pack
-  // with no semantic entries still answers to the builtin set, which is what its
-  // machines will be running.
+  // FailproofAI's names would call it a name "this build does not have". A pack
+  // with no semantic entries answers to FailproofAI's sixteen names, which is
+  // what `FailproofAI/jev-policies` brings to the machines that install both.
   const reviewers = semantic.length > 0 ? new Set(semantic.map((s) => s.name)) : undefined;
   const authorityProblems = hooks.flatMap((hook) => {
     const problem = authorityProblem({ authority: hook.authority, reviewedBy: hook.reviewedBy }, reviewers);
@@ -590,8 +591,8 @@ async function build(rest: string[]): Promise<PackCliResult> {
   //
   // `minCliVersion` and `semantic` follow the same rule, and for `semantic` it is
   // load-bearing rather than tidy: an EMPTY array would still be "a pack that
-  // declares semantic entries" to a careless reader, and the replacement rule
-  // turns that into "this pack replaced the compiled-in set with nothing".
+  // declares semantic entries" to a careless reader, which would count it as a
+  // pack giving Jev checks when it gives none.
   const manifest =
     JSON.stringify(
       {
@@ -631,7 +632,7 @@ async function build(rest: string[]): Promise<PackCliResult> {
             `(${questionCost} characters of questions), ` +
             (identity.effect === "observe"
               ? "not asked where it installs: Jev asks only the checks of packs that enforce."
-              : `${firstParty ? "replacing" : "added to"} the built-in checks where it installs.`),
+              : "asked by Jev wherever it installs."),
         ]
       : []),
     ...(requiredCli ? [`  Requires failproofai ${requiredCli} or newer.`] : []),
@@ -2651,17 +2652,17 @@ function semanticPhrase(count: number): string {
 }
 
 /**
- * How a pack's Jev checks sit beside this build's, for add, show and the
- * picker alike: a FailproofAI pack's replace them, anyone else's are added
- * (`replacesBuiltinChecks`), and only where `jevPacks` lets the pack take part —
- * never for an observe pack, only for its agents when scoped. One phrase, so
- * the three cannot drift apart again.
+ * Whether a pack's Jev checks are asked, for add, show and the picker alike:
+ * only where `jevPacks` lets the pack take part — never for an observe pack,
+ * only for its agents when scoped. The package ships no checks of its own, so
+ * a pack's are the whole set, beside any other pack's. One phrase, so the
+ * three cannot drift apart again.
  */
-function besideBuiltinChecks(pack: { source?: string; effect?: PolicyEffect; clis?: string[] | null }): string {
+function howJevAsksChecks(pack: { source?: string; effect?: PolicyEffect; clis?: string[] | null }): string {
   if (jevPacks([{ effect: pack.effect ?? "enforce", clis: null }]).length === 0) {
     return "not asked: this pack only observes, and Jev asks only the checks of packs that enforce";
   }
-  const how = isFirstPartyPack(pack) ? "replacing this build's own set" : "added to this build's own checks";
+  const how = "asked by Jev on every tool call they apply to";
   return pack.clis && pack.clis.length > 0 ? `${how}, for ${pack.clis.join(", ")} only` : how;
 }
 
@@ -2716,7 +2717,7 @@ async function pickFromSource(
   if (preview.semantic.length > 0) {
     io.stdout.write(
       `\n  This pack also brings ${semanticPhrase(preview.semantic.length)} (not selectable), ` +
-        `${besideBuiltinChecks(preview)}.\n  See: failproofai policies show ${source}\n\n`,
+        `${howJevAsksChecks(preview)}.\n  See: failproofai policies show ${source}\n\n`,
     );
   }
   const picked = await multiSelect<string>({
@@ -2851,7 +2852,7 @@ async function add(rest: string[]): Promise<PackCliResult> {
     // the half somebody installed did nothing and nothing said so.
     if (result.semantic > 0) {
       lines.push(
-        `  ${semanticPhrase(result.semantic)}, ${besideBuiltinChecks(result)}. ` +
+        `  ${semanticPhrase(result.semantic)}, ${howJevAsksChecks(result)}. ` +
           "They apply only where you configured Jev (`failproofai jev status`).",
       );
     }
@@ -3133,7 +3134,7 @@ function relativeAge(iso: string): string {
  *
  * Judged with `resolvePolicyAuthority` against the pack's OWN check names,
  * because that is the rule the installing machine applies: a pack declaring
- * semantic entries replaces the compiled-in set (`effectiveReviewerNames`), so
+ * semantic entries supplies the only checks it can name (`effectiveReviewerNames`), so
  * its `reviewedBy` may name only its own checks, and a declaration that names
  * anything else — or one sitting under `authority: "hard"`, which a manifest may
  * carry because the two fields are parsed independently — registers HARD. A
@@ -3247,7 +3248,7 @@ export function jevChecksSection(
     "",
     ...note(
       "Nothing toggles them: `--policy` cannot name one and `failproofai policies` never lists them. " +
-        `They arrive whole, ${besideBuiltinChecks(pack)}.`,
+        `They arrive whole, ${howJevAsksChecks(pack)}.`,
       opts,
     ),
     ...note(

package/src/hooks/pack-manifest.ts

@@ -152,8 +152,8 @@ export interface InstalledPackRecord {
    *
    * `unknown` like `policies`, and optional like it is not: a pack published
    * before this field existed carries none, and every one of them must keep
-   * parsing. A pack that declares at least one REPLACES the compiled-in
-   * semantic set wholesale — see `semantic/pack-policies.ts`.
+   * parsing. The package ships no Jev checks, so these are the only ones a
+   * machine asks — see `semantic/pack-policies.ts`.
    */
   semantic?: unknown;
   /**
@@ -339,6 +339,29 @@ export function hasInstalledPacks(): boolean {
   }
 }
 
+/**
+ * Whether an installed pack carries regex policies — the question the
+ * migration shim and `policies add <name>` actually mean to ask.
+ *
+ * `hasInstalledPacks` is the wrong question for them since the package stopped
+ * shipping Jev's checks: `FailproofAI/jev-policies` is now the normal way to
+ * turn Jev on, and it carries no regex policies. Counting it as "a pack is
+ * installed" switched off a legacy machine's `enabledPolicies` and sent a later
+ * `policies add block-rm-rf` to a pack that cannot enable it — both silently.
+ */
+export function hasInstalledRegexPacks(): boolean {
+  try {
+    const raw = JSON.parse(readFileSync(installedFilePath(), "utf8")) as { packs?: unknown };
+    if (!Array.isArray(raw.packs)) return false;
+    return raw.packs.some(
+      (p) => !!p && typeof p === "object" && Array.isArray((p as { policies?: unknown }).policies)
+        && ((p as { policies: unknown[] }).policies.length > 0),
+    );
+  } catch {
+    return false;
+  }
+}
+
 export function installedFilePath(): string {
   return process.env.FAILPROOFAI_PACK_DIR
     ? resolve(process.env.FAILPROOFAI_PACK_DIR, "installed.json")

package/src/hooks/pack-store.ts

@@ -1103,8 +1103,8 @@ export async function addPack(
     // installed did nothing.
     //
     // Omitted when empty for the same reason the manifest omits it: an empty
-    // array reads as "this pack declares semantic entries", and the replacement
-    // rule would then have it replace the compiled-in set with nothing.
+    // array reads as "this pack declares semantic entries" — a pack giving Jev
+    // checks when it gives none.
     ...(fetched.semantic.length > 0 ? { semantic: fetched.semantic } : {}),
     // Recorded so the READER re-checks it. This CLI has already satisfied it or
     // refused the install, but the record outlives this CLI: a downgrade, or a

package/src/hooks/policy-authority.ts

@@ -10,7 +10,9 @@
  *
  * - `hard` is the default and the answer to anything unclear. Absent, a value
  *   that is not one of the two, a `reviewedBy` that is empty or malformed or
- *   names a check this build does not have, or an `alwaysOn` policy: all hard.
+ *   names a check no installed pack declares, or an `alwaysOn` policy: all hard.
+ *   With no pack declaring Jev checks there are no reviewers at all, and every
+ *   policy is hard.
  * - `reviewable` means Jev may clear the policy's verdict — and only through the
  *   semantic policies it names, every one of which must have been asked.
  *
@@ -55,16 +57,23 @@ export interface ResolvedAuthority {
 }
 
 /**
- * The names `reviewedBy` may use: the semantic policies in
- * `src/hooks/semantic/policies.ts`. Not the probes (`INJECTION_PROBE`,
+ * The names of the sixteen Jev checks FailproofAI publishes in the
+ * `FailproofAI/jev-policies` pack. Not the probes (`INJECTION_PROBE`,
  * `SCOPE_PROBE`, the task probes) — those are inputs to Jev's decision, not
  * checks a regex verdict can be cleared by.
  *
- * Written out rather than read off `SEMANTIC_POLICIES`, and pinned to it by
- * `policy-authority.test.ts`. The registry imports this module, so a runtime
- * import of the semantic policies would load all sixteen of Jev's prompts on
- * every hook event of a machine that never configured Jev, and bundle them into
- * every pack artifact that registers a policy.
+ * Names only: the package ships none of the checks themselves, and this list is
+ * NOT a set of reviewers any machine has. It is used for two things:
+ *
+ * - **Reserved names.** Declared by a pack not installed from a FailproofAI
+ *   repository, one of these is void (`isReservedClaim`), so a third party
+ *   cannot become the question that clears the core pack's policies.
+ * - **Build-time vocabulary.** The core pack (`scripts/build-policy-pack.mjs`)
+ *   and a regex-only pack being published name these checks in `reviewedBy`
+ *   while carrying none of them; they live in `FailproofAI/jev-policies`.
+ *
+ * Pinned to the reference copy of that pack (`__tests__/fixtures/jev-policies.ts`)
+ * by `policy-authority.test.ts`.
  */
 export const SEMANTIC_POLICY_NAMES = [
   "destructive-deletion",
@@ -85,17 +94,16 @@ export const SEMANTIC_POLICY_NAMES = [
   "external-data-egress",
 ] as const;
 
+/** {@link SEMANTIC_POLICY_NAMES} as a set. Reserved names and build-time vocabulary — never a machine's live reviewers. */
+export const SEMANTIC_REVIEWER_NAMES: ReadonlySet<string> = new Set(SEMANTIC_POLICY_NAMES);
+
 /**
- * The compiled-in reviewer set, and the DEFAULT rather than the only one.
- *
- * A pack that declares its own `semantic` entries replaces
- * `SEMANTIC_POLICIES` wholesale on the machine that installed it, so the names
- * a `reviewedBy` may use there are the pack's. Callers that know which set is
- * live pass it (`effectiveReviewerNames()` in `effective-reviewers.ts`, which reads
- * the manifest and imports nothing from `semantic/`); everyone else gets this
- * one, which is what a machine with no pack runs.
+ * The reviewer set of a machine with no installed pack declaring Jev checks —
+ * the vanilla install — and the default wherever a caller does not say which
+ * set is live. Empty: with nothing to ask, nothing can clear, and every
+ * `reviewable` declaration registers `hard`.
  */
-export const SEMANTIC_REVIEWER_NAMES: ReadonlySet<string> = new Set(SEMANTIC_POLICY_NAMES);
+export const NO_REVIEWERS: ReadonlySet<string> = new Set<string>();
 
 const isName = (n: unknown): n is string => typeof n === "string" && n.length > 0;
 
@@ -103,7 +111,7 @@ const isName = (n: unknown): n is string => typeof n === "string" && n.length >
  * Judge one declaration.
  *
  * Stricter than `effectiveAuthority`, which is the §7 contract and needs only
- * one usable name: here EVERY entry must be a semantic policy this build has,
+ * one usable name: here EVERY entry must be a check this machine can ask,
  * and anything else makes the whole declaration hard rather than being dropped.
  * `reviewedBy` is a conjunction, so dropping a name the author wrote — a typo, a
  * stray `7` — would let Jev clear the policy on fewer checks than they asked
@@ -114,16 +122,23 @@ const isName = (n: unknown): n is string => typeof n === "string" && n.length >
  * What this returns is what `registerPolicy` stores, so a registered policy's
  * `reviewedBy` is always clean and the two functions agree on it.
  *
+ * With NO known reviewers — no installed pack declares a Jev check — a
+ * well-formed `reviewable` resolves `hard` WITHOUT a `downgraded` reason
+ * (unless a name it uses is contested between packs, which is still said). It is
+ * not a declaration going wrong but the machine having no Jev checks, which
+ * `jev status` and the dashboard say once; a warning per policy per hook event
+ * would say it fifteen times on every tool call of a core-pack machine.
+ *
  * @param knownReviewers - the semantic policies that CAN be asked on this
- *   machine. Defaults to the compiled-in set, which is what runs until a pack
- *   ships its own; see {@link SEMANTIC_REVIEWER_NAMES}. It is a parameter rather
- *   than a lookup because this module is imported by the registry, and reading
- *   which set is live means reading a file — a cost registration is willing to
- *   pay once and this judgement must not pay per call.
+ *   machine (`effectiveReviewerNames()` on the hook path). Defaults to
+ *   {@link NO_REVIEWERS}, so a caller that does not say is fail-safe. It is a
+ *   parameter rather than a lookup because this module is imported by the
+ *   registry, and reading which set is live means reading a file — a cost
+ *   registration is willing to pay once and this judgement must not pay per call.
  */
 export function resolvePolicyAuthority(
   decl: AuthorityDeclaration | undefined,
-  knownReviewers: ReadonlySet<string> = SEMANTIC_REVIEWER_NAMES,
+  knownReviewers: ReadonlySet<string> = NO_REVIEWERS,
   /** Names left out of `knownReviewers` because packs declare them differently, with those packs. */
   contested?: ReadonlyMap<string, string[]>,
 ): ResolvedAuthority {
@@ -137,6 +152,8 @@ export function resolvePolicyAuthority(
     return { authority: "hard", downgraded: "reviewedBy is not a list of semantic policy names" };
   }
   const unknown = names.filter((n) => !knownReviewers.has(n));
+  // No checks at all, and no contest to explain: quietly hard (see above).
+  if (knownReviewers.size === 0 && !unknown.some((n) => contested?.has(n))) return { authority: "hard" };
   if (unknown.length > 0) {
     return { authority: "hard", downgraded: `reviewedBy names ${unknown.map((n) => whyUnknown(n, knownReviewers, contested)).join("; ")}` };
   }
@@ -144,8 +161,8 @@ export function resolvePolicyAuthority(
 }
 
 /**
- * The rule that kept one name out. "Not in this build" is only true of the
- * compiled-in set: a pack's own checks, or a name two packs disagree on, is a
+ * The rule that kept one name out. "Not in this build" is only true of
+ * FailproofAI's own names, judged at build or publish time: a pack's own checks, or a name two packs disagree on, is a
  * different reason, and the author reading it has a different fix.
  */
 function whyUnknown(name: string, known: ReadonlySet<string>, contested?: ReadonlyMap<string, string[]>): string {
@@ -205,9 +222,11 @@ export function authorityProblem(
   decl: AuthorityDeclaration,
   /**
    * The reviewers the pack being built will SHIP WITH — its own `semantic`
-   * entries when it declares any, this build's set otherwise. A pack that
-   * carries both halves of the two-tier set names its own checks, and refusing
-   * that would make the feature unpublishable by the tool that implements it.
+   * entries when it declares any, FailproofAI's sixteen names otherwise (a
+   * regex-only pack names checks that ship in `FailproofAI/jev-policies`). A
+   * pack that carries both halves of the two-tier set names its own checks, and
+   * refusing that would make the feature unpublishable by the tool that
+   * implements it.
    */
   knownReviewers: ReadonlySet<string> = SEMANTIC_REVIEWER_NAMES,
 ): string | undefined {
@@ -283,13 +302,13 @@ export function manifestAuthority(
  *
  * @param knownReviewers - the checks that can be asked on this machine. Callers
  *   that merge what will be REGISTERED must pass `effectiveReviewerNames()`;
- *   the default is this build's compiled-in set, which is what a machine with no
- *   pack runs.
+ *   the default is {@link NO_REVIEWERS}, which is what a machine with no pack
+ *   declaring Jev checks has.
  */
 export function withMergedAuthority<T extends AuthorityFields>(
   record: T,
   declarations: ReadonlyArray<AuthorityFields>,
-  knownReviewers: ReadonlySet<string> = SEMANTIC_REVIEWER_NAMES,
+  knownReviewers: ReadonlySet<string> = NO_REVIEWERS,
 ): { merged: T; overruled: boolean; refused?: string } {
   const resolved = declarations.map((d) => resolvePolicyAuthority(d, knownReviewers));
   const allReviewable = resolved.length > 0 && resolved.every((r) => r.authority === "reviewable");

package/src/hooks/policy-evaluator.ts

@@ -24,7 +24,7 @@ import {
   type JevActivityFields,
   type JevReview,
   type RegexVerdict,
-  type ShadowVerdict,
+  type ObserveVerdict,
   type TwoTierReview,
 } from "./semantic/combine";
 // The code, not a copy of the string: the log line below turns on it, and a
@@ -62,8 +62,8 @@ export interface EvaluationResult {
     decidedByJev: boolean;
     /** The pack a deciding Jev check came from; only with `decidedByJev`. */
     jevOrigin?: { packId: string; packVersion?: string };
-    /** Shadow mode: Jev's own deny/instruct, recorded as a "would have" (see `ShadowVerdict`). */
-    shadowVerdict?: ShadowVerdict;
+    /** Observe mode: Jev's own deny/instruct, recorded as a "would have" (see `ObserveVerdict`). */
+    observeVerdict?: ObserveVerdict;
   };
 }
 
@@ -219,7 +219,7 @@ export async function evaluatePolicies(
   }
   const combined = combineTwoTier(collected.verdicts, review, twoTier.mode);
   if (combined.cleared.length > 0) {
-    hookLogInfo(`jev ${twoTier.mode === "shadow" ? "would clear" : "cleared"}: ${combined.cleared.join(", ")}`);
+    hookLogInfo(`jev ${twoTier.mode === "observe" ? "would clear" : "cleared"}: ${combined.cleared.join(", ")}`);
   }
   if (combined.activity.evaluator === "jev-fallback") {
     // Info, not warn: during an outage this is every gated call, and warn-level
@@ -251,7 +251,7 @@ export async function evaluatePolicies(
       activity: combined.activity,
       decidedByJev: combined.decidedByJev,
       ...(combined.decidedByJev && review.kind === "answered" && review.origin ? { jevOrigin: review.origin } : {}),
-      ...(combined.shadowVerdict ? { shadowVerdict: combined.shadowVerdict } : {}),
+      ...(combined.observeVerdict ? { observeVerdict: combined.observeVerdict } : {}),
     },
   };
 }

package/src/hooks/policy-registry.ts

@@ -73,13 +73,11 @@ export function registerPolicy(
   const canonical = normalizePolicyName(name);
   const registry = getRegistry();
   const idx = registry.findIndex((p) => p.name === canonical);
-  // Judged against the reviewers this MACHINE can ask, not against the ones this
-  // build compiled in. A pack that ships its own `semantic` set replaces the
-  // compiled one, so its policies name checks that exist here and nowhere in
-  // `SEMANTIC_POLICY_NAMES` — and judging them by the builtin list would
-  // downgrade the whole rewritten set to `hard` while reporting nothing but a
-  // warning. `effectiveReviewerNames` reads the manifest — already where a
-  // pack's `reviewedBy` itself comes from — once per registration pass.
+  // Judged against the reviewers this MACHINE can ask: the checks its installed
+  // packs declare, and none when no pack declares any (the package ships no
+  // Jev checks), in which case every policy registers `hard`.
+  // `effectiveReviewerNames` reads the manifest — already where a pack's
+  // `reviewedBy` itself comes from — once per registration pass.
   const authority = meta ? resolvePolicyAuthority(meta, effectiveReviewerNames()) : undefined;
   const entry: RegisteredPolicy = {
     name: canonical, description, fn, match, priority,