failproofai 1.0.6 → 1.0.7-beta.0

package/src/hooks/pack-store.ts

@@ -35,8 +35,17 @@
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { PACK_COMMIT_RE, packsRoot, parsePackIdentity, parsePackPolicy, readInstalledPacks } from "./pack-manifest";
-import type { ResolvedPack } from "./pack-manifest";
+import {
+  MAX_SEMANTIC_POLICIES_PER_PACK,
+  PACK_COMMIT_RE,
+  checkPackMinCliVersion,
+  packsRoot,
+  parsePackIdentity,
+  parsePackPolicy,
+  parsePackSemanticPolicy,
+  readInstalledPacks,
+} from "./pack-manifest";
+import type { ResolvedPack, SemanticManifestEntry } from "./pack-manifest";
 import type { InstalledPackRecord } from "./pack-manifest";
 import type { PolicyCatalogEntry } from "./policy-types";
 import type { PolicyEffect } from "./cloud-managed-policies";
@@ -86,6 +95,13 @@ export interface AddPackResult {
   selection: SelectionReason;
   /** Category slugs the pack offers, for `--category`. */
   categories: string[];
+  /**
+   * How many Jev question sets came with it, and not a list of names: they are
+   * not selectable and not switchable, so a name here would invite a `--policy`
+   * that cannot work. A non-zero count is what stops a semantic-only install
+   * reporting "the pack is installed and enforcing nothing".
+   */
+  semantic: number;
   artifact: string;
 }
 
@@ -454,6 +470,10 @@ interface FetchedPack {
   id: string;
   version: string;
   policies: PolicyCatalogEntry[];
+  /** The pack's Jev question sets, validated. Empty when it declares none. */
+  semantic: SemanticManifestEntry[];
+  /** The minimum CLI it claims, once this one has been checked against it. */
+  minCliVersion?: string;
   effect?: PolicyEffect;
   /** The git commit the publisher built this from, when they had one. */
   commit?: string;
@@ -461,6 +481,66 @@ interface FetchedPack {
   artifactDigest: string;
 }
 
+/**
+ * The shape both fetch paths read a manifest's `semantic` array through.
+ *
+ * REFUSES what the loader would only drop, and the asymmetry is the same one
+ * `parsePackPolicy` already has on this path: nothing has been written yet, so
+ * refusing costs the user a clear error message and the publisher a fix —
+ * whereas dropping an entry here would install a pack that enforces less than
+ * the preview just showed, with the difference recorded only in a hook log. The
+ * loader drops instead because by then the pack IS installed and refusing it
+ * denies every tool call its regex policies cover.
+ *
+ * The per-pack cap is checked for the same reason. Over it, the loader keeps the
+ * first 24 in declared order and records the rest as dropped; letting that
+ * happen silently at install time means a machine quietly running a subset of
+ * what the user agreed to.
+ *
+ * The CHARACTER budget is deliberately not checked here. It lives in
+ * `semantic/pack-policies.ts`, and importing that module would pull Jev's
+ * sixteen prompts into this one — which is reachable from a Next.js server
+ * action (`app/actions/pack-actions.ts`), not just from the CLI. `failproofai
+ * publish` refuses an over-budget pack at build time, and a pack built by some
+ * other tool has its overflow dropped at resolve time with a recorded reason.
+ */
+function parseManifestSemantic(packId: string, value: unknown): SemanticManifestEntry[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error(`pack ${packId} semantic is not an array`);
+  if (value.length > MAX_SEMANTIC_POLICIES_PER_PACK) {
+    throw new Error(
+      `pack ${packId} declares ${value.length} semantic policies, over the cap of ${MAX_SEMANTIC_POLICIES_PER_PACK}`,
+    );
+  }
+  const entries = value.map((entry, i) => parsePackSemanticPolicy(packId, entry, i));
+  const names = new Set<string>();
+  for (const entry of entries) {
+    if (names.has(entry.name)) throw new Error(`pack ${packId} declares semantic policy ${entry.name} twice`);
+    names.add(entry.name);
+  }
+  return entries;
+}
+
+/**
+ * Refuse a pack this CLI is too old to run — HERE, where the message is
+ * something the person who typed the command can act on.
+ *
+ * The loader refuses it too, and that refusal is the fail-closed one: on a
+ * machine where it lands, every tool call the pack's policies cover is denied
+ * until somebody works out why. Catching it at install turns the same fact into
+ * one line at the moment of choosing.
+ *
+ * A minimum this build cannot compare is IGNORED, exactly as the loader ignores
+ * it: a publisher's typo in a version string must not be able to stop anyone
+ * installing a pack. `failproofai publish` refuses to write one, so this is
+ * only reachable from a pack built by some other tool.
+ */
+function assertMinCliVersion(packId: string, declared: unknown): string | undefined {
+  const verdict = checkPackMinCliVersion(packId, declared);
+  if (verdict.kind === "too-old") throw new Error(verdict.reason);
+  return verdict.kind === "satisfied" ? verdict.declared : undefined;
+}
+
 /** Fetch and fully validate a pack, without writing anything. */
 /**
  * The short names for the pack Failproof AI publishes.
@@ -543,6 +623,19 @@ export interface PackPreview {
   /** The git commit the publisher built this from, when they had one. */
   commit?: string;
   policies: PolicyCatalogEntry[];
+  /**
+   * The pack's Jev question sets. Shown, not selectable: a pack's `enabled`
+   * narrowing picks which of its REGEX policies register, and its semantic set
+   * replaces this build's wholesale or not at all.
+   *
+   * Carried on the preview because the preview is what somebody consents to. A
+   * pack that quietly brings sixteen new questions to the classifier — and
+   * replaces the sixteen this build shipped — is not something to discover after
+   * installing it.
+   */
+  semantic: SemanticManifestEntry[];
+  /** The minimum CLI this pack declares, when it declares one this build can read. */
+  minCliVersion?: string;
   /** The exact source the preview was read from, tag resolved and pinned. */
   source: string;
   /** True when the tag was resolved rather than typed. */
@@ -589,22 +682,52 @@ export async function fetchPackPreview(source: string): Promise<PackPreview> {
   if (!raw || typeof raw !== "object") throw new Error(`${PACK_MANIFEST_ASSET} is not an object`);
   const value = raw as {
     id?: unknown; version?: unknown; policies?: unknown; effect?: unknown; commit?: unknown;
+    semantic?: unknown; minCliVersion?: unknown;
   };
   const identity = parsePackIdentity(value);
-  if (!Array.isArray(value.policies) || value.policies.length === 0) {
-    throw new Error("pack manifest declares no policies");
-  }
+  const minCliVersion = assertMinCliVersion(identity.id, value.minCliVersion);
+  const semantic = parseManifestSemantic(identity.id, value.semantic);
+  const policies = parseManifestPolicies(identity.id, value.policies);
+  assertDeclaresSomething(policies, semantic);
   return {
     id: identity.id,
     version: identity.version,
     effect: identity.effect,
     ...(identity.commit ? { commit: identity.commit } : {}),
-    policies: value.policies.map((policy, i) => parsePackPolicy(identity.id, policy, i)),
+    policies,
+    semantic,
+    ...(minCliVersion ? { minCliVersion } : {}),
     source: formatPackSpec(spec),
     resolvedFromLatest,
   };
 }
 
+/**
+ * The regex half of a manifest. ABSENT is an empty list, not an error: a pack of
+ * Jev questions alone is a legitimate thing to publish now, and ours writes
+ * `policies: []` for one. Present and not an array is still malformed.
+ */
+function parseManifestPolicies(packId: string, value: unknown): PolicyCatalogEntry[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error(`pack ${packId} policies is not an array`);
+  return value.map((policy, i) => parsePackPolicy(packId, policy, i));
+}
+
+/**
+ * A pack has to bring SOMETHING, and either half counts.
+ *
+ * It used to be "at least one regex policy", which made a pack of Jev questions
+ * alone impossible to install — and that is a legitimate pack: the regex floor
+ * may already be somebody else's, and the two halves version independently. This
+ * is the same widening `build()` makes to its "registered no policies" refusal,
+ * so the two ends of the lane agree on what an empty pack is.
+ */
+function assertDeclaresSomething(policies: PolicyCatalogEntry[], semantic: SemanticManifestEntry[]): void {
+  if (policies.length === 0 && semantic.length === 0) {
+    throw new Error("pack manifest declares no policies");
+  }
+}
+
 /**
  * The record this install is really an update OF — matched by id, or failing
  * that by artifact digest.
@@ -647,20 +770,26 @@ async function fetchPack(spec: PinnedPackSpec): Promise<FetchedPack> {
   if (!parsed || typeof parsed !== "object") throw new Error(`${PACK_MANIFEST_ASSET} is not an object`);
   const raw = parsed as {
     id?: unknown; version?: unknown; policies?: unknown; effect?: unknown; commit?: unknown;
+    semantic?: unknown; minCliVersion?: unknown;
   };
   const identity = parsePackIdentity(raw);
-  if (!Array.isArray(raw.policies) || raw.policies.length === 0) {
-    throw new Error("pack manifest declares no policies");
-  }
+  // Before the shape checks below, because being too old for the pack is not a
+  // complaint about the pack: the message to give is "update the CLI", and a
+  // manifest field this build cannot read yet must not be reported as malformed.
+  const minCliVersion = assertMinCliVersion(identity.id, raw.minCliVersion);
   // Validated with the SAME rules the loader applies, so a pack that could never
   // load is refused here — while nothing has been written — rather than
   // installing cleanly and failing silently on the next tool call.
-  const policies = raw.policies.map((p, i) => parsePackPolicy(identity.id, p, i));
+  const policies = parseManifestPolicies(identity.id, raw.policies);
+  const semantic = parseManifestSemantic(identity.id, raw.semantic);
+  assertDeclaresSomething(policies, semantic);
 
   return {
     id: identity.id,
     version: identity.version,
     policies,
+    semantic,
+    ...(minCliVersion ? { minCliVersion } : {}),
     ...(raw.effect !== undefined ? { effect: identity.effect } : {}),
     ...(identity.commit ? { commit: identity.commit } : {}),
     artifact,
@@ -931,6 +1060,22 @@ export async function addPack(
     entry: artifactRel,
     sha256: fetched.artifactDigest,
     policies: fetched.policies,
+    // Both halves of the manifest reach the record, because `installed.json` is
+    // the only thing enforcement reads. Left off, a pack's Jev questions were
+    // fetched, verified, shown in the preview and then dropped on the floor: the
+    // resolver found no `semantic` on any installed pack, kept this build's
+    // compiled set, and every pack policy naming one of the pack's own checks in
+    // `reviewedBy` registered as hard. Nothing failed, and the half the user
+    // 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.
+    ...(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
+    // machine restored from another's home directory, has to meet it again.
+    ...(fetched.minCliVersion ? { minCliVersion: fetched.minCliVersion } : {}),
     // Provenance, carried through from the manifest so `policies` and the
     // dashboard can say which source produced what is installed. NOT part of
     // verification — `sha256` above is the pin, and this is a label beside it.
@@ -978,6 +1123,7 @@ export async function addPack(
     available,
     selection: reason,
     categories: [...new Set(fetched.policies.map((p) => slugifyCategory(p.category)))],
+    semantic: fetched.semantic.length,
     artifact: artifactAbs,
   };
 }

package/src/hooks/policy-authority.ts

@@ -0,0 +1,333 @@
+/**
+ * Policy authority: who has the last word on a policy's deny or instruct once
+ * Jev is configured. See {@link PolicyAuthority} for the two values and
+ * `docs/policies/authority.mdx` for the builtin table.
+ *
+ * Every route a policy arrives by — a builtin, the user's own policy file, an
+ * installed pack, a cloud assignment — declares its authority somewhere
+ * different. This module is the one place those declarations are read and
+ * judged, so the rule cannot drift between them:
+ *
+ * - `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.
+ * - `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.
+ *
+ * Nothing here decides anything at evaluation time. It resolves a declaration
+ * once, at registration, and `registerPolicy` stores the result, so what sits in
+ * the registry is already the effective authority.
+ */
+import { existsSync } from "node:fs";
+import { jevConfigFile } from "./fp-home";
+import { hookLogWarn } from "./hook-logger";
+import { effectiveAuthority } from "./policy-types";
+import type { CustomHook, PolicyAuthority, PolicyCatalogEntry } from "./policy-types";
+
+/**
+ * A declaration as it arrives, before anything has vouched for it. Fields are
+ * `unknown` because three of the four sources are files on disk written by
+ * somebody else.
+ */
+export interface AuthorityDeclaration {
+  authority?: unknown;
+  reviewedBy?: unknown;
+  /** The self-protection guard. Always hard, whatever else it says. */
+  alwaysOn?: boolean;
+}
+
+/** The shape-valid authority fields a parsed record (a pack entry, a cloud assignment) carries. */
+export interface AuthorityFields {
+  authority?: PolicyAuthority;
+  reviewedBy?: string[];
+}
+
+/** What a registered policy carries: already judged, and honest to its type. */
+export interface ResolvedAuthority {
+  authority: PolicyAuthority;
+  /** Present exactly when `authority` is `reviewable`. Deduplicated, in declared order. */
+  reviewedBy?: string[];
+  /**
+   * Why a `reviewable` declaration was not honored, for a warning. Absent when
+   * nothing asked for `reviewable` — a policy that is simply hard is not news.
+   */
+  downgraded?: string;
+}
+
+/**
+ * The names `reviewedBy` may use: the semantic policies in
+ * `src/hooks/semantic/policies.ts`. 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.
+ */
+export const SEMANTIC_POLICY_NAMES = [
+  "destructive-deletion",
+  "production-infra-change",
+  "git-history-rewrite",
+  "push-to-protected-branch",
+  "commit-on-protected-branch",
+  "secret-exposure",
+  "credential-exfiltration",
+  "remote-code-execution",
+  "privilege-escalation",
+  "database-destruction",
+  "read-outside-workspace",
+  "agent-config-tampering",
+  "system-modification",
+  "env-secrets-dump",
+  "external-destructive-action",
+  "external-data-egress",
+] as const;
+
+/**
+ * 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 `pack-manifest.ts`, which reads
+ * the manifest and imports nothing from `semantic/`); everyone else gets this
+ * one, which is what a machine with no pack runs.
+ */
+export const SEMANTIC_REVIEWER_NAMES: ReadonlySet<string> = new Set(SEMANTIC_POLICY_NAMES);
+
+const isName = (n: unknown): n is string => typeof n === "string" && n.length > 0;
+
+/**
+ * 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,
+ * 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
+ * for. It is also the safe direction for version skew: a pack built against a
+ * newer semantic set, installed on an older build, enforces as hard rather than
+ * as reviewable-by-less.
+ *
+ * What this returns is what `registerPolicy` stores, so a registered policy's
+ * `reviewedBy` is always clean and the two functions agree on it.
+ *
+ * @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.
+ */
+export function resolvePolicyAuthority(
+  decl: AuthorityDeclaration | undefined,
+  knownReviewers: ReadonlySet<string> = SEMANTIC_REVIEWER_NAMES,
+): ResolvedAuthority {
+  const declaredReviewable = decl?.authority === "reviewable";
+  if (!decl || effectiveAuthority(decl) === "hard") {
+    if (!declaredReviewable) return { authority: "hard" };
+    return { authority: "hard", downgraded: whyHard(decl!) };
+  }
+  const names = decl.reviewedBy as unknown[];
+  if (!names.every(isName)) {
+    return { authority: "hard", downgraded: "reviewedBy is not a list of semantic policy names" };
+  }
+  const unknown = names.filter((n) => !knownReviewers.has(n));
+  if (unknown.length > 0) {
+    return {
+      authority: "hard",
+      downgraded:
+        `reviewedBy names ${unknown.map((n) => JSON.stringify(n)).join(", ")}, ` +
+        `which ${unknown.length === 1 ? "is not a semantic policy" : "are not semantic policies"} in this build`,
+    };
+  }
+  return { authority: "reviewable", reviewedBy: [...new Set(names)] };
+}
+
+function whyHard(decl: AuthorityDeclaration): string {
+  if (decl.alwaysOn === true) return "it is alwaysOn, and the self-protection guard is never reviewable";
+  if (!Array.isArray(decl.reviewedBy) || decl.reviewedBy.length === 0) {
+    return "reviewedBy does not name any semantic policy";
+  }
+  return "reviewedBy is not a list of semantic policy names";
+}
+
+/**
+ * The shape-valid authority fields of a serialized policy entry, for parsers.
+ *
+ * Invalid fields are DROPPED, never thrown on. A pack or cloud deployment that
+ * is refused over a typo in an optional field fails closed and denies every
+ * tool call its policies cover; dropping the field makes that one policy hard,
+ * which is the default the typo would have produced at registration anyway.
+ * Names are not checked against the semantic set here — that is a property of
+ * the build reading the entry, not of the entry, and is judged at registration.
+ */
+export function authorityFieldsOf(raw: Record<string, unknown>): AuthorityFields {
+  const out: AuthorityFields = {};
+  if (raw.authority === "hard" || raw.authority === "reviewable") out.authority = raw.authority;
+  const list = raw.reviewedBy;
+  if (Array.isArray(list) && list.length > 0 && list.every(isName)) {
+    out.reviewedBy = [...(list as string[])];
+  }
+  return out;
+}
+
+/**
+ * Why a declaration cannot be PUBLISHED as written, or `undefined` when it can.
+ *
+ * For build steps — `scripts/build-policy-pack.mjs` and `failproofai publish`.
+ * The loaders drop a malformed field and registration downgrades a refused
+ * `reviewable`, both toward hard and both only as a warning, because by then the
+ * pack is installed and refusing it would fail it closed. At build time nothing
+ * is installed yet, so refusing costs nobody anything, while shipping the
+ * declaration would make the policy silently hard on every machine that
+ * installs it — a decision its author made, quietly not taking effect.
+ *
+ * An empty `reviewedBy` on a hard policy is not a problem: it says nothing.
+ */
+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.
+   */
+  knownReviewers: ReadonlySet<string> = SEMANTIC_REVIEWER_NAMES,
+): string | undefined {
+  if (decl.authority !== undefined && decl.authority !== "hard" && decl.authority !== "reviewable") {
+    const t = typeof decl.authority;
+    return `authority must be "hard" or "reviewable", and is ${t === "string" ? JSON.stringify(decl.authority) : `${/^[aeiou]/.test(t) ? "an" : "a"} ${t}`}`;
+  }
+  if (decl.reviewedBy !== undefined && !(Array.isArray(decl.reviewedBy) && decl.reviewedBy.every(isName))) {
+    return "reviewedBy must be a list of semantic policy names";
+  }
+  const { downgraded } = resolvePolicyAuthority(decl, knownReviewers);
+  return downgraded ? `authority "reviewable" was refused — ${downgraded}` : undefined;
+}
+
+/**
+ * The authority fields a pack MANIFEST should carry for one entry: resolved, as
+ * the registry will store them, so the manifest says exactly what takes effect.
+ * Throws, naming the entry, on anything {@link authorityProblem} refuses.
+ */
+export function manifestAuthority(
+  entry: AuthorityDeclaration & { name: string },
+  knownReviewers: ReadonlySet<string> = SEMANTIC_REVIEWER_NAMES,
+): {
+  authority: PolicyAuthority;
+  reviewedBy?: string[];
+} {
+  const problem = authorityProblem(entry, knownReviewers);
+  if (problem) throw new Error(`${entry.name}: ${problem}`);
+  const { authority, reviewedBy } = resolvePolicyAuthority(entry, knownReviewers);
+  return reviewedBy ? { authority, reviewedBy } : { authority };
+}
+
+/**
+ * One authority for several declarations that land on ONE registration.
+ *
+ * Artifacts are content-addressed, so two cloud assignments or two packs whose
+ * code is byte-identical load as one policy (the collapse in
+ * `custom-hooks-loader.ts`). Keeping one of their declarations would let the
+ * order of `active.json` or `installed.json` decide — and let one pack's
+ * manifest, or one team's assignment, make another's policy reviewable.
+ *
+ * So it resolves toward HARD, the way the collapse resolves the effect toward
+ * enforce: reviewable only when EVERY declaration resolves to reviewable, and
+ * then through the UNION of their checks (more checks that must all come back
+ * clear is stricter, never weaker). Otherwise it takes the first declaration
+ * that is not reviewable, so a refused one is still reported at registration.
+ *
+ * Returns `record` itself when its own fields already say that, and a copy with
+ * only the two authority fields replaced otherwise. `overruled` is true when
+ * some declaration asked for reviewable, validly, and did not get it.
+ */
+export function withMergedAuthority<T extends AuthorityFields>(
+  record: T,
+  declarations: ReadonlyArray<AuthorityFields>,
+): { merged: T; overruled: boolean } {
+  const resolved = declarations.map((d) => resolvePolicyAuthority(d));
+  const allReviewable = resolved.length > 0 && resolved.every((r) => r.authority === "reviewable");
+  const fields: AuthorityFields = allReviewable
+    ? { authority: "reviewable", reviewedBy: [...new Set(resolved.flatMap((r) => r.reviewedBy ?? []))] }
+    : fieldsOf(declarations[resolved.findIndex((r) => r.authority !== "reviewable")] ?? {});
+  const overruled = !allReviewable && resolved.some((r) => r.authority === "reviewable");
+  const same =
+    record.authority === fields.authority &&
+    JSON.stringify(record.reviewedBy) === JSON.stringify(fields.reviewedBy);
+  if (same) return { merged: record, overruled };
+  const { authority: _a, reviewedBy: _r, ...rest } = record;
+  return { merged: { ...rest, ...fields } as T, overruled };
+}
+
+/** The authority fields a record actually carries, and nothing else. */
+function fieldsOf(d: AuthorityFields): AuthorityFields {
+  return {
+    ...(d.authority !== undefined ? { authority: d.authority } : {}),
+    ...(d.reviewedBy !== undefined ? { reviewedBy: d.reviewedBy } : {}),
+  };
+}
+
+const warnedAuthority = new Set<string>();
+
+/**
+ * Say that an authority declaration was not honored — once per process, and
+ * only once Jev is configured (a global `jev.json` exists).
+ *
+ * Without Jev, authority decides nothing, so there is nothing to tell anyone —
+ * and a warning is not free: it goes to the hook's stderr, which some CLIs show
+ * as the deny text itself, on every event, for every machine that installed a
+ * pack built against a newer semantic set. Once per process keeps the daemon's
+ * warm worker from repeating it for every tool call. Authors are told at build
+ * time as well: `failproofai publish` refuses what this would warn about.
+ *
+ * Presence of the file rather than a validated load: a machine where someone
+ * has started configuring Jev is where the answer to "why does Jev never clear
+ * this policy" is wanted, and a stat keeps the semantic modules unloaded.
+ */
+export function warnAuthority(message: string): void {
+  try {
+    if (!existsSync(jevConfigFile())) return;
+  } catch {
+    return;
+  }
+  if (warnedAuthority.has(message)) return;
+  warnedAuthority.add(message);
+  hookLogWarn(message);
+}
+
+/**
+ * Where a loaded hook's authority is declared, by the route it arrived on.
+ *
+ * - **Cloud-managed:** the artifact record in the active deployment. A cloud
+ *   policy's authority is a central decision, so code inside the artifact
+ *   cannot grant itself `reviewable`.
+ * - **Pack:** the pack's own manifest entry for that policy, matched by name —
+ *   the same place its `params` schema is read from. A pack can only ever
+ *   describe its own policies this way: its names cannot contain `/`, and they
+ *   register under `pack/<id>@<version>/`, so no manifest can reach a builtin
+ *   or another pack's policy. A policy the artifact registers but the manifest
+ *   does not declare has no entry and is hard. When packs share one artifact,
+ *   the loader has already merged their entries toward hard
+ *   ({@link withMergedAuthority}), so no one of them decides for the others.
+ * - **The user's own file:** the hook itself.
+ */
+export function authorityDeclarationFor(
+  hook: Pick<CustomHook, "name" | "authority" | "reviewedBy">,
+  source: {
+    cloudManaged?: { authority?: unknown; reviewedBy?: unknown };
+    pack?: { policies: PolicyCatalogEntry[] };
+  },
+): AuthorityDeclaration {
+  if (source.cloudManaged) {
+    return { authority: source.cloudManaged.authority, reviewedBy: source.cloudManaged.reviewedBy };
+  }
+  if (source.pack) {
+    const entry = source.pack.policies.find((p) => p.name === hook.name);
+    return { authority: entry?.authority, reviewedBy: entry?.reviewedBy };
+  }
+  return { authority: hook.authority, reviewedBy: hook.reviewedBy };
+}