failproofai 1.0.7 → 1.0.8-beta.0

package/src/hooks/policy-registry.ts

@@ -7,6 +7,8 @@
  */
 import type { HookEventType } from "./types";
 import type { PolicyFunction, PolicyMatcher, PolicyParamsSchema, RegisteredPolicy } from "./policy-types";
+import { effectiveReviewerNames, forgetEffectiveReviewerNames } from "./effective-reviewers";
+import { resolvePolicyAuthority, type AuthorityDeclaration } from "./policy-authority";
 
 const REGISTRY_KEY = "__FAILPROOFAI_POLICY_REGISTRY__";
 const INDEX_CACHE_KEY = "__FAILPROOFAI_POLICY_INDEX_CACHE__";
@@ -58,15 +60,34 @@ export function registerPolicy(
   match: PolicyMatcher,
   priority: number = 0,
   params?: PolicyParamsSchema,
+  /**
+   * The policy's authority declaration, as its source wrote it. Judged HERE,
+   * so the registry only ever holds an effective value: `reviewable` with a
+   * clean `reviewedBy`, or `hard`. See `resolvePolicyAuthority`.
+   *
+   * Absent means the caller declared nothing, and the entry then carries no
+   * authority field at all — which `effectiveAuthority` reads as hard.
+   */
+  meta?: AuthorityDeclaration,
 ): void {
   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.
+  const authority = meta ? resolvePolicyAuthority(meta, effectiveReviewerNames()) : undefined;
   const entry: RegisteredPolicy = {
     name: canonical, description, fn, match, priority,
     // Absent stays absent: `evaluatePolicies` distinguishes "declares a schema"
     // from "declares none", and a spread `params: undefined` is neither.
     ...(params ? { params } : {}),
+    ...(authority ? { authority: authority.authority } : {}),
+    ...(authority?.reviewedBy ? { reviewedBy: authority.reviewedBy } : {}),
   };
   if (idx >= 0) {
     registry[idx] = entry;
@@ -106,10 +127,15 @@ export function getPoliciesForEvent(
   return result;
 }
 
-export function clearPolicies(): void {
+/** `cli`: the agent this pass registers for, which scopes the Jev reviewer set. */
+export function clearPolicies(cli?: string): void {
   const g = globalThis as GlobalWithRegistry;
   g[REGISTRY_KEY] = [];
   setIndexCache(null);
+  // The reviewer set describes the policies that are about to be registered, so
+  // it is rebuilt with them. Dropping it here is also what keeps one read per
+  // evaluation instead of one per policy.
+  forgetEffectiveReviewerNames(cli);
 }
 
 /**

package/src/hooks/policy-reviewability.ts

@@ -0,0 +1,258 @@
+/**
+ * How much of what this machine enforces Jev is allowed to CLEAR — the
+ * diagnostic half of `policy-authority.ts`, and nothing else.
+ *
+ * ## The silence this exists to break
+ *
+ * Authority decides one thing: whether Jev may clear a regex policy's deny or
+ * instruct (`combine.ts`, which returns early unless the authority is
+ * `reviewable`). Absent means `hard`, and that default is right — it is what
+ * keeps an unknown pack, cloud or custom policy from being weakened by a
+ * classifier nobody asked about it.
+ *
+ * It is also completely silent. `authority` and `reviewedBy` reach a pack
+ * through its manifest, and the only thing that writes them there is
+ * `scripts/build-policy-pack.mjs`, which ships WITH this release. So a pack
+ * published before it declares none, every policy in it resolves to `hard`
+ * with nothing downgraded, and `warnAuthority` — which only speaks when a
+ * `reviewable` declaration was not honored — has nothing to say. The result a
+ * customer gets is the deny half of the two-tier evaluator working exactly as
+ * documented, the clear half unable to fire once, and no diagnostic anywhere:
+ * `jev status` says `on`, the fallback rate says the calls are being answered,
+ * and `cleared` says `nothing` forever.
+ *
+ * This module counts. It changes no policy's authority and no verdict, it is
+ * never imported from the hook path, and a machine with no `jev.json` never
+ * reaches a caller of it.
+ *
+ * ## What "enabled" means here
+ *
+ * The same thing it means in `handler.ts`, read from the same files, without
+ * loading or executing a policy:
+ *
+ * - **Installed packs** — each pack's manifest entries, narrowed by its
+ *   `enabled` selection (absent means the whole pack). A pack's `clis`
+ *   narrowing is NOT applied: there is no agent CLI in a status command, and
+ *   the honest answer to "what could Jev clear on this machine" spans all of
+ *   them.
+ * - **Builtins** — this build's catalog, under the same migration shim the
+ *   handler applies: they enforce only while no pack is installed. The
+ *   `alwaysOn` guard is counted always, because it registers always (and is
+ *   hard always, so it can only ever lower the ratio).
+ * - **Cloud assignments** — the active deployment's records, whose authority is
+ *   declared by whoever deployed them. One record per assignment; an artifact
+ *   that registers several hooks is still one central decision.
+ *
+ * Two things are deliberately NOT counted, and `customFiles` is what says so
+ * out loud when it matters:
+ *
+ * - **Policies from the user's own files.** A custom hook declares its
+ *   authority inside the module, so counting one means importing and running
+ *   somebody's JavaScript — from a settings page, on every read. The count of
+ *   custom policy FILES the hook loads (configured paths and the project and
+ *   user convention files) is reported instead, the summary says in words that
+ *   those policies were not counted, and no "never" is diagnosed beside them.
+ * - **A session pause.** It suspends local policy for minutes, and a warning
+ *   about a policy set that is coming back shortly would be noise.
+ */
+import { readActiveCloudManagedPolicies } from "./cloud-managed-policies";
+import { jevPacks } from "./effective-reviewers";
+import { resolve } from "node:path";
+import { discoverPolicyFiles } from "./custom-hooks-loader";
+import { customPoliciesDir } from "./fp-home";
+import { configuredCustomPolicyPaths, findProjectConfigDir, readMergedHooksConfig } from "./hooks-config";
+import { hasInstalledPacks, readInstalledPacks } from "./pack-manifest";
+import { resolvePolicyAuthority, SEMANTIC_REVIEWER_NAMES } from "./policy-authority";
+import { POLICY_CATALOG } from "./policy-catalog";
+import { normalizePolicyName } from "./policy-registry";
+import type { HooksConfig } from "./policy-types";
+// A CLI and dashboard module, never on the hook path, so it may ask the
+// resolver itself (`pack-cli.ts` does the same).
+import { semanticPoliciesFromPacks } from "./semantic/pack-policies";
+
+/** Anything that carries an authority declaration: a catalog entry, a pack entry, a cloud record. */
+export interface AuthorityRecord {
+  authority?: unknown;
+  reviewedBy?: unknown;
+  alwaysOn?: boolean;
+}
+
+export interface ReviewableCoverage {
+  /** Enabled policies whose authority could be read without running code. */
+  enabled: number;
+  /** Of those, the ones Jev may clear a deny or an instruct from. */
+  reviewable: number;
+  /**
+   * Custom policy files the hook loads — configured paths and the project and
+   * user convention files — whose policies are not in the counts above.
+   */
+  customFiles: number;
+}
+
+/** The command that replaces a pack with one built by this release. */
+export const RETAKE_PACK_COMMAND = "failproofai policies add FailproofAI/policies";
+
+/**
+ * Count a policy set by the authority it would REGISTER with —
+ * `resolvePolicyAuthority`, the rule `registerPolicy` applies — so this cannot
+ * report a clear that would not happen or hide one that would.
+ *
+ * Deliberately not `effectiveAuthority`, the looser §7 contract `jev-review.ts`
+ * asks at evaluation time. That one needs a single non-empty name and is right
+ * where it is asked, because by then the registry holds a `reviewedBy` that
+ * registration already cleaned, and on cleaned records the two rules agree.
+ * Nothing counted HERE has been through registration: these records are read
+ * straight off a pack manifest, this build's catalog and the cloud deployment.
+ * So a declaration naming a check this build does not have — `reviewedBy:
+ * ["future-check"]`, which is what a pack built against a NEWER semantic set
+ * looks like here — is reviewable to the loose rule and hard in the registry,
+ * and counting it would report a clear that can never happen while
+ * `reviewableProblem` stayed silent about the machine it exists to warn.
+ */
+export function countReviewable(
+  policies: Iterable<AuthorityRecord>,
+  /**
+   * The semantic checks that can be asked on this machine. Defaults to the
+   * compiled-in set; `surveyReviewableCoverage` passes the pack's when one
+   * declares its own, because otherwise this diagnostic reports "0 of 11
+   * reviewable" on exactly the machines the feature was built for — the ones
+   * running a pack that carries both tiers.
+   */
+  knownReviewers?: ReadonlySet<string>,
+): {
+  enabled: number;
+  reviewable: number;
+} {
+  let enabled = 0;
+  let reviewable = 0;
+  for (const p of policies) {
+    enabled += 1;
+    if (resolvePolicyAuthority(p, knownReviewers).authority === "reviewable") reviewable += 1;
+  }
+  return { enabled, reviewable };
+}
+
+/**
+ * What this machine's enabled policy set looks like to Jev. Reads three files
+ * and no policy: see the header for what is in the counts and what is not.
+ *
+ * Every source is wrapped, and an unreadable one contributes nothing rather
+ * than throwing — the same fail-open posture `handler.ts` takes for packs and
+ * cloud policies, for the same reason: this is a diagnostic, and one corrupt
+ * byte must not replace a settings page with an error boundary.
+ */
+export function surveyReviewableCoverage(cwd?: string): ReviewableCoverage {
+  const records: AuthorityRecord[] = [];
+
+  let packsInstalled = false;
+  /**
+   * The reviewers a pack brought with it. Collected from the SAME read as the
+   * policies rather than through `effectiveReviewerNames()`, which would re-read
+   * and re-verify every artifact for an answer already in hand — and would, for
+   * one read of a manifest being rewritten underneath, be able to disagree with
+   * the records counted here.
+   *
+   * A pack's `enabled` selection is deliberately not applied: it narrows which
+   * of its REGEX policies register, and its semantic set is not selectable.
+   */
+  let reviewers: ReadonlySet<string> | undefined;
+  try {
+    packsInstalled = hasInstalledPacks();
+    const packs = readInstalledPacks().packs;
+    for (const pack of packs) {
+      const selected = pack.enabled;
+      records.push(...(selected ? pack.policies.filter((p) => selected.includes(p.name)) : pack.policies));
+    }
+    // The names of the questions a request will actually carry: only the packs
+    // whose checks take part (an observe pack's do not), minus a reserved or
+    // contested name AND minus a check the question budget drops — which the
+    // hook path's manifest-only `reviewerNamesFor` cannot see. Anything else and
+    // the panel and `jev status` promise a clear that cannot happen.
+    const asked = semanticPoliciesFromPacks(jevPacks(packs));
+    reviewers = asked.fromPack ? new Set(asked.policies.map((p) => p.name)) : SEMANTIC_REVIEWER_NAMES;
+  } catch {
+    // An unreadable manifest enforces nothing; `readInstalledPacks` already
+    // reports that to the hook log on the path that cares.
+  }
+
+  let config: HooksConfig;
+  try {
+    config = readMergedHooksConfig(cwd);
+  } catch {
+    config = { enabledPolicies: [] };
+  }
+  // The migration shim, exactly as `handler.ts` applies it: this build's
+  // builtins enforce only until a pack is installed.
+  const legacyEnabled = new Set(packsInstalled ? [] : config.enabledPolicies.map(normalizePolicyName));
+  for (const policy of POLICY_CATALOG) {
+    if (policy.alwaysOn || legacyEnabled.has(normalizePolicyName(policy.name))) records.push(policy);
+  }
+
+  try {
+    for (const assignment of readActiveCloudManagedPolicies()) {
+      records.push({ authority: assignment.authority, reviewedBy: assignment.reviewedBy });
+    }
+  } catch {
+    // Same fail-open as the handler's own read of this file.
+  }
+
+  // Every file `loadAllCustomHooks` would load, by resolved path so a file
+  // both named and discovered (or a project root that IS home) counts once.
+  let customFiles = 0;
+  try {
+    // Relative paths against the project root, as the loader resolves them.
+    const projectRoot = findProjectConfigDir(cwd ?? process.cwd());
+    const files = new Set(configuredCustomPolicyPaths(config).map((p) => resolve(projectRoot, p)));
+    if (config.customPoliciesEnabled !== false) {
+      const projectDir = resolve(projectRoot, ".failproofai", "policies");
+      for (const dir of [projectDir, customPoliciesDir()]) for (const f of discoverPolicyFiles(dir)) files.add(f);
+    }
+    customFiles = files.size;
+  } catch {
+    customFiles = 0;
+  }
+
+  return { ...countReviewable(records, reviewers), customFiles };
+}
+
+/**
+ * The one line both surfaces show: the count, in the words `jev status` and the
+ * dashboard panel must agree on. A non-zero count is worth saying too — it is
+ * how someone learns how much of their policy set Jev can act on at all.
+ */
+export function reviewableSummary(coverage: ReviewableCoverage): string {
+  const { enabled, reviewable } = coverage;
+  // Said out loud rather than folded into the number, because a custom policy
+  // CAN be reviewable and this count would not know: reading that declaration
+  // means importing and running the file it lives in.
+  const tail = coverage.customFiles > 0 ? " (policies from your own files are not counted)" : "";
+  if (enabled === 0) return `No policies are enabled here, so there is nothing for Jev to clear${tail}.`;
+  const noun = enabled === 1 ? "1 enabled policy is" : `${enabled} enabled policies are`;
+  if (reviewable === 0) return `0 of ${noun} reviewable${tail}.`;
+  return `${reviewable} of ${noun} reviewable: Jev may clear a deny or an instruction from those, and from no others${tail}.`;
+}
+
+/**
+ * Why Jev can never clear anything here, and what fixes it — or null when it
+ * can clear something, which needs no explanation.
+ *
+ * It states the observation before naming the usual cause, because the cause is
+ * the usual one and not the only one: a machine can also reach zero by enabling
+ * only hard policies, or by having nothing but the self-protection guard. The
+ * remedy is the same in each case, and it is one command.
+ *
+ * Nothing is diagnosed for an empty policy set: there is no clear to lose, and
+ * an authority warning to someone who enforces nothing answers a question they
+ * did not ask.
+ */
+export function reviewableProblem(coverage: ReviewableCoverage): string | null {
+  // Policies from the user's own files were not counted and may be reviewable,
+  // so "never" cannot be said honestly; the summary already says what was skipped.
+  if (coverage.enabled === 0 || coverage.reviewable > 0 || coverage.customFiles > 0) return null;
+  return (
+    "Jev can add a deny or an instruction on this machine, but it can never clear one. " +
+    "No enabled policy is marked reviewable — a policy pack published before this release carries no such marks — " +
+    `so re-take the pack (\`${RETAKE_PACK_COMMAND}\`) to get a marked copy, ` +
+    "or enforce this build's builtin policies, which carry them."
+  );
+}

package/src/hooks/policy-types.ts

@@ -43,6 +43,54 @@ export interface RegisteredPolicy {
    * the user's OWN configured `policyParams` for it, not merely the defaults.
    */
   params?: PolicyParamsSchema;
+  /** Whether Jev may clear this policy's deny/instruct; see {@link effectiveAuthority}. */
+  authority?: PolicyAuthority;
+  /**
+   * The semantic policies (`src/hooks/semantic/policies.ts`) that must all be
+   * asked, and each clear (see {@link PolicyAuthority}), before Jev clears this
+   * policy.
+   */
+  reviewedBy?: string[];
+}
+
+/**
+ * Who has the last word on a policy's deny or instruct when Jev is configured.
+ *
+ * - `hard`: final. Jev can never clear it.
+ * - `reviewable`: Jev may clear it, but only through the semantic policies
+ *   named in `reviewedBy`, and only when every one of them was actually asked
+ *   and each answered `none`, `overridden`, or a deny the human's task
+ *   softened to a warning (`combine.ts`, "A check that fired without consent
+ *   keeps the floor").
+ *   A named check that was NOT asked always keeps the verdict standing.
+ */
+export type PolicyAuthority = "hard" | "reviewable";
+
+/**
+ * The authority a policy actually has. `reviewable` only when it is declared
+ * `reviewable`, names at least one semantic policy in `reviewedBy`, and is not
+ * `alwaysOn`. Anything else — absent, invalid, an empty `reviewedBy`, the
+ * self-protection guard — is `hard`, so an unknown custom, cloud or third-party
+ * policy can never be weakened by Jev.
+ *
+ * This is the §7 contract every task builds against, and it is deliberately
+ * the looser of two rules: one usable name is enough here. REGISTRATION is
+ * stricter — `resolvePolicyAuthority` in `policy-authority.ts` makes the whole
+ * declaration hard if any entry is malformed or is not a semantic policy this
+ * build has, and that is what `registerPolicy` stores. So a registered policy's
+ * `reviewedBy` is already clean, and the two rules agree on everything that
+ * reaches the registry.
+ */
+export function effectiveAuthority(p: {
+  authority?: unknown;
+  reviewedBy?: unknown;
+  alwaysOn?: boolean;
+}): PolicyAuthority {
+  if (p.alwaysOn === true) return "hard";
+  if (p.authority !== "reviewable") return "hard";
+  if (!Array.isArray(p.reviewedBy)) return "hard";
+  const named = p.reviewedBy.filter((n) => typeof n === "string" && n.length > 0);
+  return named.length > 0 ? "reviewable" : "hard";
 }
 
 export interface PolicyParamsSchema {
@@ -89,6 +137,10 @@ export interface BuiltinPolicyDefinition {
    *  secondary line in the audit report. e.g. "Could leak code from neighboring
    *  repos to the model." */
   impact?: string;
+  /** See {@link PolicyAuthority}. Absent means `hard`. */
+  authority?: PolicyAuthority;
+  /** See {@link RegisteredPolicy.reviewedBy}. */
+  reviewedBy?: string[];
 }
 
 export interface CustomHook {
@@ -98,6 +150,82 @@ export interface CustomHook {
     events?: HookEventType[];
   };
   fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+  /**
+   * See {@link PolicyAuthority}. Absent means `hard`.
+   *
+   * Honored for the user's own local policy files (explicit paths and
+   * `.failproofai/policies/`). For a pack policy the pack's MANIFEST decides,
+   * and for a cloud-managed one the cloud ARTIFACT record does — the same split
+   * as `params`, so the declaration a user reviewed in a listing is the one
+   * that takes effect.
+   */
+  authority?: PolicyAuthority;
+  /** See {@link RegisteredPolicy.reviewedBy}. */
+  reviewedBy?: string[];
+}
+
+/**
+ * The tool classes a semantic policy may be asked about.
+ *
+ * A structural copy of `ToolClass` in `src/hooks/semantic/types.ts`, and
+ * deliberately not an import of it. This module is the public API's type
+ * surface — every custom policy file and every pack entry imports it — and the
+ * semantic modules must stay off the import graph of a machine with no
+ * `jev.json` (see `precondition-names.ts` for what that costs when it slips).
+ * A type import would be erased, but the two lists still have to agree, so
+ * `__tests__/hooks/semantic/pack-semantic-registry.test.ts` pins them.
+ */
+export type SemanticToolClass = "shell" | "write" | "read" | "network" | "other";
+
+/** One yes/no question in a semantic policy, as a pack declares it. */
+export interface SemanticProbeDeclaration {
+  /** Lowercase slug, unique within the policy. The answer map is keyed `<policy>.<id>`. */
+  id: string;
+  instructions: string;
+  criteria?: { true: string; false: string };
+}
+
+/**
+ * A semantic (Jev) policy as its author DECLARES it — a question set, not code.
+ *
+ * The compiled-in equivalent is `SemanticPolicy` in `semantic/types.ts`, and
+ * the one difference is the whole reason both exist: there, `precondition` is a
+ * function over the computed facts; here it is the NAME of one, because a
+ * declaration has to survive a trip through a JSON manifest and because a
+ * downloaded artifact must not hand this process an expression to evaluate on
+ * every tool call. `semantic/preconditions.ts` binds the name to its predicate.
+ *
+ * There is no `fn` and no `match`: a semantic policy never executes locally and
+ * is never selected by event or tool name — `appliesTo` and `precondition`
+ * decide what it is asked about, and Jev answers it. That is also why it is
+ * registered through `semanticPolicies`, its own namespace, rather than as a
+ * variant of `customPolicies.add`.
+ */
+export interface SemanticPolicyDeclaration {
+  /** Short slug. Reported as `semantic/<name>`, and what a `reviewedBy` names. */
+  name: string;
+  /** Past-tense phrase for what was caught, e.g. "Deleted something irreplaceable". */
+  title: string;
+  appliesTo: SemanticToolClass[];
+  /** `deny` blocks on strong evidence and warns on moderate; `instruct` only ever warns. */
+  mode: "deny" | "instruct";
+  /**
+   * Whether the human's own explicit request may clear this policy.
+   *
+   * Required, with no default anywhere in the stack. It is the field that
+   * decides whether a prompt injection can talk its way past the policy, and a
+   * default for it would be a security decision made by absence — the author
+   * would never learn which way it went.
+   */
+  userCanOverride: boolean;
+  /** A name from `PACK_PRECONDITION_NAMES`. Absent, or `"always"`, means no precondition. */
+  precondition?: string;
+  /** Every probe must hold for the policy to fire (conjunction). 1–6 of them. */
+  probes: SemanticProbeDeclaration[];
+  /** If this holds, the policy does not fire — the documented exceptions. */
+  exempt?: SemanticProbeDeclaration;
+  /** Shown to the agent when the policy fires. */
+  guidance: string;
 }
 
 export interface LlmConfig {