@geonosis/policy 1.0.0

package/dist/index.js

@@ -0,0 +1,779 @@
+import {
+  toPolicyRule,
+  toPolicyRules
+} from "./chunk-JICJ4XEX.js";
+
+// src/lattice.ts
+var specificityOf = (scopeKeys, scope) => {
+  if (!scope) return 0;
+  let score = 0;
+  for (const [index, key] of scopeKeys.entries()) {
+    if (scope[key] !== void 0) score += 2 ** index;
+  }
+  return score;
+};
+var appliesTo = (rule, query, scopeKeys) => {
+  if (!rule.scope) return true;
+  for (const [key, want] of Object.entries(rule.scope)) {
+    if (want === void 0) continue;
+    if (!scopeKeys.includes(key)) return false;
+    if (query[key] !== want) return false;
+  }
+  return true;
+};
+var unsupportedScopesOf = (rules, scopeKeys) => {
+  const out = [];
+  for (const rule of rules) {
+    const scope = rule.scope;
+    if (!scope) continue;
+    const keys = Object.keys(scope).filter(
+      (key) => scope[key] !== void 0 && !scopeKeys.includes(key)
+    );
+    if (keys.length > 0) out.push({ id: rule.id, keys });
+  }
+  return out;
+};
+var unusableBecause = (rule, data) => {
+  if (!data.tiers.some((tier) => tier.name === rule.tier)) return `unknown tier "${rule.tier}"`;
+  const kind = data.kinds.find((spec) => spec.kind === rule.constraint.kind);
+  if (!kind) return `unknown kind "${rule.constraint.kind}"`;
+  if (kind.schema && !kind.schema.safeParse(rule.constraint.value).success) {
+    return `value ${JSON.stringify(rule.constraint.value)} is not a ${kind.kind}`;
+  }
+  return void 0;
+};
+var unusableRulesOf = (rules, data) => rules.flatMap((rule) => {
+  const reason2 = unusableBecause(rule, data);
+  return reason2 ? [{ id: rule.id, reason: reason2 }] : [];
+});
+var usableRulesOf = (rules, data) => rules.filter((rule) => unusableBecause(rule, data) === void 0);
+var unsetKindsOf = (rules, kinds) => {
+  const set = new Set(rules.map((rule) => rule.constraint.kind));
+  return kinds.map((kind) => kind.kind).filter((kind) => !set.has(kind));
+};
+var sameValue = (kind, a, b) => kind?.sameValue ? kind.sameValue(a, b) : JSON.stringify(a) === JSON.stringify(b);
+var explainDecision = (winner, overrode, conflicts) => {
+  const parts = [`${winner.id} (${winner.tier}) \u2014 ${winner.reason}`];
+  if (overrode) parts.push(`overrides ${overrode.id} (${overrode.tier}, overridable)`);
+  if (conflicts.length > 0) {
+    parts.push(
+      `CONFLICT with equal authority: ${conflicts.map((rule) => rule.id).join(", ")} \u2014 resolve in policy, not in code`
+    );
+  }
+  return parts.join("; ");
+};
+var resolveConstraint = (data, kind, query = {}, rules = data.rules) => {
+  const rank = (tier) => data.tiers.findIndex((spec) => spec.name === tier);
+  const specificity = (scope) => specificityOf(data.scopeKeys, scope);
+  const pool = usableRulesOf(rules, data).filter(
+    (rule) => rule.constraint.kind === kind && appliesTo(rule, query, data.scopeKeys)
+  );
+  if (pool.length === 0) return void 0;
+  const sorted = pool.map((rule, index) => ({ index, rule })).toSorted((a, b) => {
+    const byTier = rank(a.rule.tier) - rank(b.rule.tier);
+    if (byTier !== 0) return byTier;
+    const bySpecificity = specificity(b.rule.scope) - specificity(a.rule.scope);
+    return bySpecificity === 0 ? a.index - b.index : bySpecificity;
+  }).map((entry) => entry.rule);
+  const strongest = sorted[0];
+  if (!strongest) return void 0;
+  const tierOf = (rule) => data.tiers.find((spec) => spec.name === rule.tier);
+  const mayBeOverridden = (rule) => tierOf(rule)?.overridable === true && (rule.overridable ?? data.overridableByDefault);
+  const overrideTier = data.tiers.find((tier) => tier.overrides)?.name;
+  const override = overrideTier ? sorted.find((rule) => rule.tier === overrideTier) : void 0;
+  const overrode = override && override !== strongest && mayBeOverridden(strongest) ? strongest : void 0;
+  const winner = overrode ? override : strongest;
+  const suppressed = sorted.filter((rule) => rule !== winner);
+  const kindSpec = data.kinds.find((spec) => spec.kind === kind);
+  const conflicts = suppressed.filter(
+    (rule) => rank(rule.tier) === rank(winner.tier) && specificity(rule.scope) === specificity(winner.scope) && !sameValue(kindSpec, rule.constraint.value, winner.constraint.value)
+  );
+  return {
+    conflicts,
+    explain: explainDecision(winner, overrode, conflicts),
+    kind,
+    ...overrode ? { overrode } : {},
+    suppressed,
+    value: winner.constraint.value,
+    winner
+  };
+};
+
+// src/define.ts
+var asTiers = (values) => values.map((value) => typeof value === "string" ? { name: value } : value);
+var asKinds = (values) => values.map((value) => typeof value === "string" ? { kind: value } : value);
+var refuseDuplicates = (values, what) => {
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    if (seen.has(value)) {
+      throw new TypeError(
+        `definePolicy: ${what} "${value}" is declared twice. Which one a rule means would then depend on which was found first.`
+      );
+    }
+    seen.add(value);
+  }
+};
+var definePolicy = (input) => {
+  const tiers = asTiers(input.tiers);
+  const kinds = asKinds(input.kinds);
+  const scopeKeys = [...input.scopeKeys ?? []];
+  const rules = [...input.rules ?? []];
+  if (tiers.length === 0) {
+    throw new TypeError(
+      "definePolicy: `tiers` is empty. A lattice with no authorities could never decide anything, and every rule written against it would name a tier it does not have."
+    );
+  }
+  refuseDuplicates(
+    tiers.map((tier) => tier.name),
+    "tier"
+  );
+  refuseDuplicates(
+    kinds.map((kind) => kind.kind),
+    "kind"
+  );
+  refuseDuplicates(scopeKeys, "scope key");
+  const overriding = tiers.filter((tier) => tier.overrides);
+  if (overriding.length > 1) {
+    throw new TypeError(
+      `definePolicy: ${overriding.map((tier) => `"${tier.name}"`).join(
+        " and "
+      )} both declare \`overrides\`. The audited escape hatch is one tier or none \u2014 two of them race for the same rule.`
+    );
+  }
+  const lastAuthority = tiers.findLastIndex((tier) => !tier.advisory);
+  const firstAdvisory = tiers.findIndex((tier) => tier.advisory);
+  if (firstAdvisory !== -1 && firstAdvisory < lastAuthority) {
+    throw new TypeError(
+      `definePolicy: advisory tier "${tiers[firstAdvisory]?.name}" is declared stronger than "${tiers[lastAuthority]?.name}". An advisory tier fills silence; one that outranks an authority is not advisory, it is an authority with a reassuring name.`
+    );
+  }
+  const data = {
+    kinds,
+    overridableByDefault: input.overridableByDefault ?? true,
+    rules,
+    scopeKeys,
+    tiers
+  };
+  const journalledOnce = /* @__PURE__ */ new Set();
+  return {
+    ...data,
+    journalledOnce,
+    kindOf: (kind) => kinds.find((spec) => spec.kind === kind),
+    rank: (tier) => {
+      const index = tiers.findIndex((spec) => spec.name === tier);
+      return index === -1 ? void 0 : index;
+    },
+    resetJournal: () => journalledOnce.clear(),
+    resolve: (kind, query, given) => resolveConstraint(data, kind, query, given),
+    specificity: (scope) => specificityOf(scopeKeys, scope),
+    tierOf: (tier) => tiers.find((spec) => spec.name === tier),
+    unsetKinds: (given = rules) => unsetKindsOf(given, kinds),
+    unsupportedScopes: (given = rules) => unsupportedScopesOf(given, scopeKeys),
+    unusableRules: (given = rules) => unusableRulesOf(given, data),
+    usableRules: (given = rules) => usableRulesOf(given, data)
+  };
+};
+
+// src/types.ts
+var POLICY_FALLBACK = "policy.fallback";
+var POLICY_INVALID_VALUE = "policy.invalid_value";
+
+// src/read.ts
+var attempt = async (what) => {
+  try {
+    return await what();
+  } catch {
+    return void 0;
+  }
+};
+var accepts = (policy, kind, value) => {
+  const schema = policy.kindOf(kind)?.schema;
+  return schema ? schema.safeParse(value).success : true;
+};
+var record = async (policy, journal, entry) => {
+  const key = `${entry.event}::${entry.kind}::${entry.op ?? ""}`;
+  if (policy.journalledOnce.has(key)) return;
+  policy.journalledOnce.add(key);
+  await attempt(() => journal?.write(entry));
+};
+var readPolicy = async (policy, kind, query = {}, options) => {
+  const rules = options.rule ? await attempt(() => options.rule?.rules(kind, query)) ?? [] : policy.rules;
+  const decision = policy.resolve(kind, query, rules);
+  if (decision) {
+    const spec = policy.kindOf(kind);
+    if (spec?.isReference?.(decision.value)) {
+      const referenced = await attempt(
+        () => spec.dereference?.(decision.value, { config: options.config, query })
+      );
+      if (referenced !== void 0) {
+        return { decision, source: "rule", usedFallback: false, value: referenced };
+      }
+    } else {
+      return { decision, source: "rule", usedFallback: false, value: decision.value };
+    }
+  }
+  const configured = await attempt(() => options.config?.get(kind, query));
+  if (configured !== void 0 && accepts(policy, kind, configured)) {
+    return { source: "config", usedFallback: false, value: configured };
+  }
+  if (!options.silent) {
+    await record(policy, options.journal, {
+      event: POLICY_FALLBACK,
+      fellBackTo: options.fallback,
+      kind,
+      ...options.op ? { op: options.op } : {},
+      ...options.subject ? { subject: options.subject } : {}
+    });
+  }
+  return { source: "fallback", usedFallback: true, value: options.fallback };
+};
+var policyOrDefault = async (policy, input, apply) => {
+  try {
+    return apply(input.value);
+  } catch (error) {
+    await record(policy, input.journal, {
+      event: POLICY_INVALID_VALUE,
+      fellBackTo: input.fallback,
+      kind: input.kind,
+      op: input.op,
+      rejected: {
+        reason: error instanceof Error ? error.message : String(error),
+        value: input.value
+      },
+      ...input.subject ? { subject: input.subject } : {}
+    });
+    return apply(input.fallback);
+  }
+};
+
+// src/conformance.ts
+var probePolicy = () => definePolicy({
+  kinds: ["quoteExpiryDays", "containerCutoff", "aiCostCapUsd", "unread"],
+  scopeKeys: ["companyId"],
+  tiers: ["contract", { name: "tenant", overridable: true }]
+});
+var reason = "the reason a person blocked by this rule would read";
+var ROWS = [
+  {
+    constraint_kind: "quoteExpiryDays",
+    constraint_value: 30,
+    reason,
+    rule_key: "expiry-30",
+    tier: "tenant"
+  },
+  {
+    constraint_kind: "quoteExpiryDays",
+    constraint_value: 60,
+    reason,
+    rule_key: "expiry-60-acme",
+    scope: { companyId: "comp_acme" },
+    tier: "tenant"
+  },
+  {
+    constraint_kind: "containerCutoff",
+    constraint_value: { dayOfWeek: 5, hourUtc: 18 },
+    reason,
+    rule_key: "cutoff-friday",
+    tier: "tenant"
+  },
+  {
+    constraint_kind: "aiCostCapUsd",
+    constraint_value: 0.5,
+    overridable: false,
+    reason,
+    rule_key: "cost-cap",
+    tier: "tenant"
+  },
+  {
+    constraint_kind: "quoteExpiryDays",
+    constraint_value: 1,
+    reason,
+    rule_key: "expiry-retired",
+    status: "retired",
+    tier: "contract"
+  }
+];
+var check = async (name, assertion) => {
+  try {
+    await assertion();
+    return { name, passed: true };
+  } catch (error) {
+    return { detail: error instanceof Error ? error.message : String(error), name, passed: false };
+  }
+};
+var must = (condition, detail) => {
+  if (!condition) throw new Error(detail);
+};
+var same = (actual, expected, what) => must(
+  JSON.stringify(actual) === JSON.stringify(expected),
+  `${what}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`
+);
+var runPolicyAdapterConformance = async (harness) => {
+  const over = (config) => harness.create({ config, rows: ROWS });
+  const checks = [
+    await check("reads a stored rule back as one the lattice can use", async () => {
+      const rules = await over().adapter.rule.rules("quoteExpiryDays", {});
+      const found = rules.find((rule) => rule.id === "expiry-30");
+      must(found !== void 0, "no rule came back under the key it was stored with");
+      same(found?.constraint, { kind: "quoteExpiryDays", value: 30 }, "the constraint");
+      same(found?.tier, "tenant", "the authority");
+      same(found?.reason, reason, "the reason");
+    }),
+    await check("leaves a retired row out, because it is not a current opinion", async () => {
+      const rules = await over().adapter.rule.rules("quoteExpiryDays", {});
+      must(
+        !rules.some((rule) => rule.id === "expiry-retired"),
+        "a retired rule came back and would have decided"
+      );
+    }),
+    await check("keeps the scope, so a rule reaches only the subject it was aimed at", async () => {
+      const { adapter } = over();
+      const policy = probePolicy();
+      const rules = await adapter.rule.rules("quoteExpiryDays", {});
+      same(
+        policy.resolve("quoteExpiryDays", { companyId: "comp_acme" }, rules)?.value,
+        60,
+        "the scoped rule"
+      );
+      same(
+        policy.resolve("quoteExpiryDays", { companyId: "comp_other" }, rules)?.value,
+        30,
+        "the general rule"
+      );
+    }),
+    await check("carries a structured value through the store unchanged", async () => {
+      const rules = await over().adapter.rule.rules("containerCutoff", {});
+      same(
+        rules.find((rule) => rule.id === "cutoff-friday")?.constraint.value,
+        { dayOfWeek: 5, hourUtc: 18 },
+        "the schedule"
+      );
+    }),
+    await check("keeps a row that refuses to be overridden", async () => {
+      const rules = await over().adapter.rule.rules("aiCostCapUsd", {});
+      same(rules.find((rule) => rule.id === "cost-cap")?.overridable, false, "the override flag");
+    }),
+    await check("answers nothing for a kind the store holds no value for", async () => {
+      const value = await over().adapter.config?.get("unread", {});
+      must(value === void 0, `an unset kind answered with ${JSON.stringify(value)}`);
+    }),
+    await check("reads an admin-set value when no rule speaks", async () => {
+      const { adapter } = over({ unread: 7 });
+      const reading = await readPolicy(
+        probePolicy(),
+        "unread",
+        {},
+        {
+          config: adapter.config,
+          fallback: 1,
+          rule: adapter.rule
+        }
+      );
+      same(reading.value, 7, "the admin-set value");
+      same(reading.source, "config", "which layer decided");
+    }),
+    await check("records a fallback, naming the kind that had nothing to say", async () => {
+      const { adapter, written } = over();
+      await readPolicy(
+        probePolicy(),
+        "unread",
+        {},
+        {
+          config: adapter.config,
+          fallback: 1,
+          journal: adapter.journal,
+          op: "a-named-operation",
+          rule: adapter.rule
+        }
+      );
+      const entries = written();
+      same(entries.length, 1, "how many records one fallback produced");
+      must(
+        JSON.stringify(entries).includes("unread"),
+        "the record does not name the kind, so nobody can count it"
+      );
+      must(
+        JSON.stringify(entries).includes("a-named-operation"),
+        "the record does not name the operation, so repeats cannot be told apart"
+      );
+    }),
+    await check("does not let a store that is down throw out of a config read", async () => {
+      await harness.createBroken().config?.get("unread", {});
+    })
+  ];
+  return { adapter: harness.name, checks, passed: checks.every((entry) => entry.passed) };
+};
+
+// src/learning.ts
+var emptyPlaybook = () => ({ entries: [], version: 0 });
+var DEFAULT_MIN_OBSERVATIONS = 3;
+var LearningError = class extends Error {
+  constructor(code, message) {
+    super(`${code}: ${message}`);
+    this.code = code;
+    this.name = "LearningError";
+  }
+  code;
+};
+var DEFAULT_REFUSAL_PREFIX = "POLICY_REFUSED";
+var DEFAULT_REVERSAL_VERBS = /\b(override|revert|undo|cancel|reassign|reschedule)\b/i;
+var observeReversals = (entries, verbs) => {
+  const out = [];
+  for (const [index, decided] of entries.entries()) {
+    const next = entries[index + 1];
+    if (!next) continue;
+    if (decided.actor.kind === "user" || next.actor.kind !== "user") continue;
+    if (!decided.subject || decided.subject !== next.subject) continue;
+    if (!verbs.test(next.name)) continue;
+    const op = decided.op ?? decided.name;
+    out.push({
+      id: `reversed:${op}`,
+      journalRefs: [decided.id, next.id],
+      kind: "pitfall",
+      statement: `A person reversed the automated "${op}" on ${decided.subject} (via ${next.name}) \u2014 check the decision before repeating it`
+    });
+  }
+  return out;
+};
+var observeRuleFriction = (entry, prefix) => {
+  if (!entry.error) return [];
+  const [, ruleId, detail] = new RegExp(`${prefix}: ([\\w:.-]+)(?: \u2014 (.*))?`).exec(entry.error) ?? [];
+  if (!ruleId) return [];
+  return [
+    {
+      id: `friction:${ruleId}`,
+      journalRefs: [entry.id],
+      kind: "rule-friction",
+      statement: `Rule "${ruleId}" blocked an action again${detail ? ` \u2014 ${detail.slice(0, 140)}` : ""} \u2014 amend the rule or stop attempting it`
+    }
+  ];
+};
+var observeUnsetPolicy = (entry) => {
+  const fell = entry.fellBackTo;
+  if (!fell) return [];
+  return [
+    {
+      id: `unset:${fell.kind}`,
+      journalRefs: [entry.id],
+      kind: "unset-policy",
+      statement: `No rule sets "${fell.kind}", so the hardcoded default ${JSON.stringify(
+        fell.value
+      )} decided instead \u2014 write the rule or delete the knob`
+    }
+  ];
+};
+var observeRecurringOps = (entries, minimum) => {
+  const byOp = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    if (entry.error || !entry.op) continue;
+    const refs = byOp.get(entry.op);
+    if (refs) refs.push(entry.id);
+    else byOp.set(entry.op, [entry.id]);
+  }
+  return [...byOp].filter(([, refs]) => refs.length >= minimum).map(([op, refs]) => ({
+    id: `macro:${op}`,
+    journalRefs: refs,
+    kind: "macro",
+    statement: `"${op}" ran ${refs.length} times \u2014 save it as a named strategy`
+  }));
+};
+var observeJournal = (entries, options = {}) => [
+  ...observeReversals(entries, options.reversalVerbs ?? DEFAULT_REVERSAL_VERBS),
+  ...entries.flatMap((entry) => [
+    ...observeRuleFriction(entry, options.refusalPrefix ?? DEFAULT_REFUSAL_PREFIX),
+    ...observeUnsetPolicy(entry)
+  ]),
+  ...observeRecurringOps(entries, options.minRepeatsForMacro ?? 2)
+];
+var reflect = (observations, now = /* @__PURE__ */ new Date()) => {
+  const byId = /* @__PURE__ */ new Map();
+  const at = now.toISOString();
+  for (const observation of observations) {
+    const existing = byId.get(observation.id);
+    if (existing) {
+      existing.evidence.observations += 1;
+      existing.evidence.journalRefs = [
+        .../* @__PURE__ */ new Set([...existing.evidence.journalRefs, ...observation.journalRefs])
+      ];
+      continue;
+    }
+    byId.set(observation.id, {
+      evidence: { journalRefs: [...observation.journalRefs], observations: 1, updatedAt: at },
+      id: observation.id,
+      kind: observation.kind,
+      ...observation.scope ? { scope: observation.scope } : {},
+      statement: observation.statement,
+      status: "candidate",
+      ...observation.suggests ? { suggests: observation.suggests } : {}
+    });
+  }
+  return [...byId.values()];
+};
+var curate = (playbook, candidates) => {
+  const entries = playbook.entries.map((entry) => ({ ...entry, evidence: { ...entry.evidence } }));
+  const byId = new Map(entries.map((entry) => [entry.id, entry]));
+  for (const candidate of candidates) {
+    const existing = byId.get(candidate.id);
+    if (!existing) {
+      entries.push(candidate);
+      byId.set(candidate.id, candidate);
+      continue;
+    }
+    if (existing.status === "demoted") continue;
+    existing.evidence.observations += candidate.evidence.observations;
+    existing.evidence.journalRefs = [
+      .../* @__PURE__ */ new Set([...existing.evidence.journalRefs, ...candidate.evidence.journalRefs])
+    ];
+    existing.evidence.updatedAt = candidate.evidence.updatedAt;
+    if (existing.status === "candidate") existing.statement = candidate.statement;
+  }
+  return { entries, version: playbook.version + 1 };
+};
+var promote = (playbook, id, options = {}) => {
+  const minimum = options.minObservations ?? DEFAULT_MIN_OBSERVATIONS;
+  const entry = playbook.entries.find((candidate) => candidate.id === id);
+  if (!entry) throw new LearningError("UNKNOWN_LEARNING", `no learning "${id}"`);
+  if (entry.evidence.observations < minimum) {
+    throw new LearningError(
+      "INSUFFICIENT_EVIDENCE",
+      `"${id}" has ${entry.evidence.observations} observation(s), needs ${minimum}`
+    );
+  }
+  return {
+    entries: playbook.entries.map(
+      (candidate) => candidate.id === id ? {
+        ...candidate,
+        evidence: {
+          ...candidate.evidence,
+          ...options.metric ? { metric: options.metric } : {}
+        },
+        status: "active"
+      } : candidate
+    ),
+    version: playbook.version + 1
+  };
+};
+var demote = (playbook, id, reason2) => {
+  if (!playbook.entries.some((entry) => entry.id === id)) {
+    throw new LearningError("UNKNOWN_LEARNING", `no learning "${id}"`);
+  }
+  return {
+    entries: playbook.entries.map(
+      (entry) => entry.id === id ? { ...entry, demotedReason: reason2, status: "demoted" } : entry
+    ),
+    version: playbook.version + 1
+  };
+};
+var playbookRules = (policy, playbook) => {
+  const advisory = policy.tiers.find((tier) => tier.advisory);
+  if (!advisory) {
+    throw new TypeError(
+      "playbookRules: this policy declares no advisory tier. A learning has to enter the lattice somewhere it can only fill silence; without one, promoting it would give a suggestion the authority of an authored rule."
+    );
+  }
+  return playbook.entries.flatMap((entry) => {
+    const suggests = entry.suggests;
+    if (entry.status !== "active" || !suggests) return [];
+    return [
+      {
+        constraint: suggests,
+        id: `${advisory.name}:${entry.id}`,
+        reason: `${entry.statement} (${entry.evidence.observations} observations)`,
+        ...entry.scope ? { scope: entry.scope } : {},
+        tier: advisory.name
+      }
+    ];
+  });
+};
+var playbookGuidance = (playbook) => {
+  const active = playbook.entries.filter((entry) => entry.status === "active");
+  if (active.length === 0) return "";
+  const lines = active.map(
+    (entry) => `- [${entry.kind}] ${entry.statement} (${entry.evidence.observations} observations)`
+  );
+  return `Learned playbook (v${playbook.version}, advisory):
+${lines.join("\n")}`;
+};
+
+// src/journal-events.ts
+var firstString = (data, keys) => {
+  for (const key of keys) {
+    const value = data[key];
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return null;
+};
+var journalRowForEvent = (eventName, data, options) => {
+  const payload = Array.isArray(data) ? data[0] : data;
+  if (!payload || typeof payload !== "object") return null;
+  const subject = firstString(payload, options.subjectKeys);
+  if (!subject) return null;
+  const actorId = firstString(payload, options.actorKeys ?? []);
+  return {
+    actor_id: actorId,
+    actor_kind: actorId ? "user" : "system",
+    event_name: eventName,
+    // The STEM, not the full name: two outcomes of one decision are the same operation being run
+    // again, and the recurring-ops signal counts operations.
+    op: eventName.split(".")[0] ?? eventName,
+    subject
+  };
+};
+
+// src/markdown.ts
+var scopeOf = (rule) => {
+  const entries = Object.entries(rule.scope ?? {}).filter(([, value]) => value !== void 0);
+  return entries.length === 0 ? "all" : entries.map(([key, value]) => `${key}=${String(value)}`).join(", ");
+};
+var generatePolicyMarkdown = (policy, options = {}) => {
+  const rules = options.rules ?? policy.rules;
+  const lines = [
+    `# ${options.title ?? "Policy"}`,
+    "",
+    `> GENERATED by ${options.generator ?? "the policy kernel"} \u2014 do not hand-edit.`,
+    `> ${options.source ?? "The policy data"} beside it is what the engine reads.`,
+    "> Committed on purpose: this is the domain knowledge the business has accumulated, and it",
+    "> should arrive with a checkout.",
+    "",
+    `## Rules (${rules.length}) \u2014 enforced`,
+    "",
+    // DERIVED, and printed whether or not any rule uses it: the ordering is a property of the
+    // lattice, not of today's rules. Written as prose this sentence lies the moment a tier is added
+    // or reordered — in a document whose whole purpose is that a fresh checkout starts knowing the
+    // truth.
+    `Precedence: ${policy.tiers.map((tier) => tier.name).join(" > ")}.`,
+    "Within a tier the more specific scope wins; two equal authorities that disagree are reported,",
+    "never resolved silently.",
+    ""
+  ];
+  if (rules.length === 0) {
+    lines.push("_None installed. Every reader falls back to its own constant, and says so._", "");
+  } else {
+    lines.push(
+      "| Rule | Tier | Scope | Constraint | Why |",
+      "| --- | --- | --- | --- | --- |",
+      ...rules.map(
+        (rule) => `| \`${rule.id}\` | ${rule.tier} | ${scopeOf(rule)} | \`${rule.constraint.kind}\` = \`${JSON.stringify(rule.constraint.value)}\` | ${rule.reason} |`
+      ),
+      ""
+    );
+  }
+  const unset = policy.unsetKinds(rules);
+  if (unset.length > 0) {
+    lines.push(
+      `## Constraints nothing sets (${unset.length})`,
+      "",
+      "A reader falling back to its own default forever looks identical to one that is working.",
+      "",
+      ...unset.map((kind) => `- \`${kind}\``),
+      ""
+    );
+  }
+  const unusable = [
+    ...policy.unusableRules(rules).map((rule) => `- \`${rule.id}\` \u2014 ${rule.reason}`),
+    ...policy.unsupportedScopes(rules).map(
+      (rule) => `- \`${rule.id}\` \u2014 scoped on ${rule.keys.join(", ")}, which this build has no key for`
+    )
+  ];
+  if (unusable.length > 0) {
+    lines.push(
+      `## Rules this build cannot honour (${unusable.length})`,
+      "",
+      "Named rather than dropped: a rule the code cannot read means the policy is newer than the",
+      "build, or older \u2014 a deployment-order problem, and the one case always worth saying aloud.",
+      "",
+      ...unusable,
+      ""
+    );
+  }
+  const playbook = options.playbook;
+  if (playbook) {
+    const active = playbook.entries.filter((entry) => entry.status === "active");
+    const candidates = playbook.entries.filter((entry) => entry.status === "candidate");
+    lines.push(
+      `## Learned playbook (v${playbook.version})`,
+      "",
+      `${active.length} active, ${candidates.length} candidate. An active entry that carries a`,
+      "constraint enters the lattice at the advisory tier, where it can only fill silence.",
+      "",
+      ...active.map((entry) => `- **${entry.id}** \u2014 ${entry.statement}`),
+      ""
+    );
+  }
+  return `${lines.join("\n")}
+`;
+};
+var describePolicy = (policy, options = {}) => {
+  const rules = options.rules ?? policy.rules;
+  const maximum = options.maxRules ?? 8;
+  const active = (options.playbook?.entries ?? []).filter((entry) => entry.status === "active");
+  if (rules.length === 0) {
+    return "No policy is installed yet \u2014 nothing is enforced, and every reader falls back to the constant compiled into it.";
+  }
+  const lines = [
+    `ACTIVE POLICY (${rules.length} rule${rules.length === 1 ? "" : "s"}, enforced \u2014 a refusal names the rule that blocked it):`,
+    ...rules.slice(0, maximum).map((rule) => {
+      const scope = rule.scope && Object.keys(rule.scope).length > 0 ? ` [${scopeOf(rule)}]` : "";
+      return `  ${rule.tier}:${rule.id}${scope} \u2014 ${rule.constraint.kind}=${JSON.stringify(
+        rule.constraint.value
+      )} (${rule.reason})`;
+    })
+  ];
+  if (rules.length > maximum) {
+    lines.push(`  + ${rules.length - maximum} more \u2014 read the whole set before deciding.`);
+  }
+  lines.push(
+    "  A more specific scope beats a general one inside a tier; stronger tiers win outright."
+  );
+  if (active.length > 0) {
+    lines.push("", "LEARNED (advisory \u2014 fills silence, never overrides a rule):");
+    for (const entry of active.slice(0, 4)) lines.push(`  ${entry.statement}`);
+  }
+  return lines.join("\n");
+};
+
+// src/seed.ts
+var sameScope = (left, right) => {
+  const a = left ?? {};
+  const b = right ?? {};
+  return [.../* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)])].every((key) => a[key] === b[key]);
+};
+var rulesToSeed = (seed, existing) => {
+  const active = existing.filter((rule) => (rule.status ?? "active") === "active");
+  return seed.filter(
+    (rule) => !active.some(
+      (row) => row.id === rule.id || row.constraint.kind === rule.constraint.kind && sameScope(row.scope, rule.scope)
+    )
+  );
+};
+export {
+  DEFAULT_MIN_OBSERVATIONS,
+  LearningError,
+  POLICY_FALLBACK,
+  POLICY_INVALID_VALUE,
+  appliesTo,
+  curate,
+  definePolicy,
+  demote,
+  describePolicy,
+  emptyPlaybook,
+  generatePolicyMarkdown,
+  journalRowForEvent,
+  observeJournal,
+  playbookGuidance,
+  playbookRules,
+  policyOrDefault,
+  promote,
+  readPolicy,
+  reflect,
+  resolveConstraint,
+  rulesToSeed,
+  runPolicyAdapterConformance,
+  specificityOf,
+  toPolicyRule,
+  toPolicyRules,
+  unsetKindsOf,
+  unsupportedScopesOf,
+  unusableRulesOf,
+  usableRulesOf
+};