@intentius/chant-lexicon-cedar 0.44.8

package/src/mcp/policy-coverage.ts

@@ -0,0 +1,205 @@
+/**
+ * "Which policies cover this resource?" — answered from a build (epic #1645).
+ *
+ * `src/coverage.ts` next door asks a different question: is every schema
+ * declaration reachable from the *generated artifacts*. This one asks whether
+ * every schema declaration is reachable from the *policy set*, which is the
+ * authorization question. An entity type no policy can ever apply to is a
+ * resource nothing grants and nothing denies — under Cedar's default-deny it is
+ * inert, and that is either the intent or a hole.
+ *
+ * The answer comes from `getValidRequestEnvsPolicy`, Cedar's own resolver: it
+ * takes one policy and the schema and returns every (principal, action,
+ * resource) triple the policy could apply to, having already expanded `is`,
+ * `in`, action groups, and `appliesTo`. Reimplementing that against the parsed
+ * scope would be a second, worse Cedar; this is why the wasm package is a
+ * runtime dependency rather than a dev one.
+ */
+
+import {
+  getValidRequestEnvsPolicy,
+  policySetTextToParts,
+  policyToJson,
+} from "@cedar-policy/cedar-wasm/nodejs";
+import { readSchemaSource, type ResolveSchemaOptions } from "../spec/fetch";
+import { parseCedarSchema } from "../spec/parse";
+
+export interface CedarPolicyCoverageItem {
+  /** `App::Document` or `App::Action::"read"`. */
+  name: string;
+  kind: "entity" | "action";
+  /** How many policies in the set can apply to it. */
+  policies: number;
+  /** Ids of the policies that can, in declaration order. */
+  policyIds: string[];
+  /** True when at least one of those policies is a `permit`. */
+  permitted: boolean;
+  /** True when at least one of those policies is a `forbid`. */
+  forbidden: boolean;
+}
+
+export interface CedarPolicyCoverageReport {
+  /** Where the schema came from. */
+  schemaPath: string;
+  isDefaultSchema: boolean;
+  /** Policies the set parsed into. */
+  policyCount: number;
+  entityTypes: number;
+  entityTypesCovered: number;
+  actions: number;
+  actionsCovered: number;
+  /** Declarations no policy in the set can apply to. */
+  uncovered: string[];
+  /** Declarations reachable only from a `forbid` — nothing ever grants them. */
+  forbidOnly: string[];
+  items: CedarPolicyCoverageItem[];
+  /** Policies the resolver could not place, with its reason. */
+  unresolved: Array<{ policyId: string; error: string }>;
+  /**
+   * Ids of policies whose valid request envelope is empty — no request can ever
+   * match them.
+   *
+   * A scope naming an entity type the schema does not declare lands here rather
+   * than in {@link unresolved}: `getValidRequestEnvsPolicy` answers "success,
+   * nothing" rather than failing, and a policy that can never fire is a real
+   * finding either way. It is usually a typo'd entity type.
+   */
+  inert: string[];
+  /**
+   * Why the policy set could not be split into policies, when it could not.
+   *
+   * Without this a set that fails to parse reports zero policies and every
+   * declaration uncovered — the same numbers as a project with no policies at
+   * all, and the opposite diagnosis.
+   */
+  parseErrors: string[];
+}
+
+export interface CedarPolicyCoverageOptions extends ResolveSchemaOptions {
+  /** The emitted `.cedar` policy set text. */
+  policySetText: string;
+}
+
+/**
+ * A policy's id and effect, read from Cedar's own parse rather than from the
+ * text.
+ *
+ * The regex version of this worked on the serializer's output and only on the
+ * serializer's output: a hand-formatted policy, an annotation whose value
+ * contains the word `forbid`, or an escaped quote inside `@id` each break it.
+ * `policyToJson` is already in the package, so there is no reason to guess.
+ *
+ * `index` supplies the fallback id, because a Cedar policy is not required to
+ * annotate one and a report keyed by "" would collapse them together.
+ */
+function identify(text: string, index: number): { id: string; effect: "permit" | "forbid" } {
+  const parsed = policyToJson(text);
+  if (parsed.type !== "success") {
+    return { id: `policy-${index + 1}`, effect: "permit" };
+  }
+  const annotated = parsed.json.annotations?.id;
+  return {
+    id: typeof annotated === "string" && annotated.length > 0 ? annotated : `policy-${index + 1}`,
+    effect: parsed.json.effect === "forbid" ? "forbid" : "permit",
+  };
+}
+
+/**
+ * Report which schema declarations the policy set can reach.
+ */
+export function computePolicyCoverage(options: CedarPolicyCoverageOptions): CedarPolicyCoverageReport {
+  const source = readSchemaSource(options);
+  const { decls } = parseCedarSchema(source.text);
+
+  const parts = policySetTextToParts(options.policySetText);
+  const policies = parts.type === "success" ? parts.policies : [];
+  const parseErrors = parts.type === "success" ? [] : parts.errors.map((e) => e.message);
+
+  const hits = new Map<string, { ids: string[]; permitted: boolean; forbidden: boolean }>();
+  const unresolved: Array<{ policyId: string; error: string }> = [];
+  const inert: string[] = [];
+
+  policies.forEach((text, index) => {
+    const { id, effect } = identify(text, index);
+    const envs = getValidRequestEnvsPolicy(text, source.text);
+    if (envs.type !== "success") {
+      unresolved.push({ policyId: id, error: envs.error });
+      return;
+    }
+
+    const reached = [...envs.principals, ...envs.actions, ...envs.resources];
+    if (reached.length === 0) {
+      inert.push(id);
+      return;
+    }
+
+    for (const name of reached) {
+      const hit = hits.get(name) ?? { ids: [], permitted: false, forbidden: false };
+      if (!hit.ids.includes(id)) hit.ids.push(id);
+      if (effect === "permit") hit.permitted = true;
+      else hit.forbidden = true;
+      hits.set(name, hit);
+    }
+  });
+
+  const items: CedarPolicyCoverageItem[] = decls
+    .map((decl) => {
+      const hit = hits.get(decl.typeName);
+      return {
+        name: decl.typeName,
+        kind: decl.kind,
+        policies: hit?.ids.length ?? 0,
+        policyIds: hit?.ids ?? [],
+        permitted: hit?.permitted ?? false,
+        forbidden: hit?.forbidden ?? false,
+      };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  const entities = items.filter((i) => i.kind === "entity");
+  const actions = items.filter((i) => i.kind === "action");
+
+  return {
+    schemaPath: source.path,
+    isDefaultSchema: source.isDefault,
+    policyCount: policies.length,
+    entityTypes: entities.length,
+    entityTypesCovered: entities.filter((i) => i.policies > 0).length,
+    actions: actions.length,
+    actionsCovered: actions.filter((i) => i.policies > 0).length,
+    uncovered: items.filter((i) => i.policies === 0).map((i) => i.name),
+    forbidOnly: items.filter((i) => i.policies > 0 && !i.permitted).map((i) => i.name),
+    items,
+    unresolved,
+    inert,
+    parseErrors,
+  };
+}
+
+/** Human-readable summary, for the CLI-shaped callers. */
+export function formatPolicyCoverage(report: CedarPolicyCoverageReport): string {
+  const lines = [
+    `Cedar policy coverage — ${report.policyCount} policy/policies against ` +
+      `${report.isDefaultSchema ? "the bundled default schema" : report.schemaPath}`,
+    `  Entity types: ${report.entityTypesCovered}/${report.entityTypes}`,
+    `  Actions:      ${report.actionsCovered}/${report.actions}`,
+  ];
+
+  for (const error of report.parseErrors) {
+    lines.push(`  Parse error:  ${error}`);
+  }
+  if (report.uncovered.length > 0) {
+    lines.push(`  Uncovered:    ${report.uncovered.join(", ")}`);
+  }
+  if (report.forbidOnly.length > 0) {
+    lines.push(`  Forbid only:  ${report.forbidOnly.join(", ")}`);
+  }
+  if (report.inert.length > 0) {
+    lines.push(`  Never fires:  ${report.inert.join(", ")}`);
+  }
+  for (const problem of report.unresolved) {
+    lines.push(`  Unresolved:   ${problem.policyId} — ${problem.error}`);
+  }
+
+  return lines.join("\n");
+}

package/src/package-cli.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env tsx
+/**
+ * Thin entry point for `npm run bundle` in lexicon-cedar.
+ *
+ * Unlike the other lexicons this does not generate `src/generated/` first —
+ * codegen is schema-driven and per-project, and lands in #1650. Until then
+ * the bundle carries the manifest, rules and integrity over an empty registry.
+ */
+import { packageLexicon } from "./codegen/package";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+const { spec, stats } = await packageLexicon({ verbose: true });
+
+const distDir = join(pkgDir, "dist");
+writeBundleSpec(spec, distDir);
+
+console.error(`Packaged ${stats.resources} entities, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+console.error(`dist/ written to ${distDir}`);

package/src/plugin.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vitest";
+import { isLexiconPlugin } from "@intentius/chant/lexicon";
+import { cedarPlugin } from "./plugin";
+import { cedarSerializer, CEDAR_POLICY_TYPE } from "./serializer";
+import { AVP_OWNERSHIP_KEYS } from "./avp/ownership";
+
+describe("cedar plugin", () => {
+  it("is a valid LexiconPlugin", () => {
+    expect(isLexiconPlugin(cedarPlugin)).toBe(true);
+  });
+
+  it("is named after the lexicon", () => {
+    expect(cedarPlugin.name).toBe("cedar");
+  });
+
+  it("exposes the cedar serializer", () => {
+    expect(cedarPlugin.serializer).toBe(cedarSerializer);
+    expect(cedarPlugin.serializer?.rulePrefix).toBe("CED");
+  });
+
+  it("registers the lifecycle methods core dispatches through", () => {
+    for (const method of ["generate", "validate", "coverage", "package", "docs"] as const) {
+      expect(typeof cedarPlugin[method], method).toBe("function");
+    }
+  });
+
+  it("registers the LSP providers", () => {
+    expect(typeof cedarPlugin.completionProvider).toBe("function");
+    expect(typeof cedarPlugin.hoverProvider).toBe("function");
+  });
+
+  it("declares at least one lint rule, all under the CED prefix", () => {
+    const rules = cedarPlugin.lintRules?.() ?? [];
+    expect(rules.length).toBeGreaterThan(0);
+    for (const rule of rules) {
+      expect(rule.id.startsWith("CED"), rule.id).toBe(true);
+    }
+  });
+
+  it("registers the agent-facing extensions", () => {
+    for (const method of ["skills", "mcpTools", "mcpResources", "initTemplates"] as const) {
+      expect(typeof cedarPlugin[method], method).toBe("function");
+    }
+  });
+
+  it("ships three skills whose frontmatter matches their registered name", () => {
+    const skills = cedarPlugin.skills?.() ?? [];
+    expect(skills).toHaveLength(3);
+
+    for (const skill of skills) {
+      // An empty body means the loader could not read the file — the skill
+      // registers, `chant init` copies nothing, and no test would notice.
+      expect(skill.content.length, `${skill.name} has no content`).toBeGreaterThan(0);
+      expect(skill.content).toContain(`skill: ${skill.name}`);
+      expect(skill.content).toContain("user-invocable: true");
+      expect(skill.description.length).toBeGreaterThan(0);
+    }
+
+    expect(skills.map((s) => s.name).sort()).toEqual([
+      "chant-cedar-authoring",
+      "chant-cedar-avp-embedding",
+      "chant-cedar-meta-policy",
+    ]);
+  });
+
+  it("contributes the conventional MCP pair plus the cedar-specific tool", () => {
+    expect(cedarPlugin.mcpTools?.().map((t) => t.name)).toEqual(["cedar:diff", "coverage"]);
+    expect(cedarPlugin.mcpResources?.().map((r) => r.uri)).toEqual(["cedar:resource-catalog"]);
+  });
+
+  it("scaffolds three distinct init templates", () => {
+    const names = ["default", "avp-embedding", "gateway-policy-set"] as const;
+    const sets = names.map((n) => cedarPlugin.initTemplates?.(n));
+
+    for (const set of sets) {
+      expect(set?.src["policies.ts"]).toContain("export const");
+      expect(set?.root?.["schema.cedarschema"]).toContain("namespace ");
+    }
+    expect(new Set(sets.map((s) => s?.src["policies.ts"])).size).toBe(3);
+  });
+
+  // ── AVP lifecycle (#1652) ────────────────────────────────────
+
+  it("registers the AVP lifecycle readers", () => {
+    for (const method of ["describeResources", "ambientKinds", "observeAmbient", "exportResources"] as const) {
+      expect(typeof cedarPlugin[method], method).toBe("function");
+    }
+  });
+
+  it("declares an ownership channel with complete keys", () => {
+    const channel = cedarPlugin.ownershipChannel;
+    expect(channel).toBeDefined();
+    expect(channel!.keys).toEqual(AVP_OWNERSHIP_KEYS);
+    for (const key of ["managedBy", "stack", "env"] as const) {
+      expect(typeof channel!.keys[key], key).toBe("string");
+      expect(channel!.keys[key].length).toBeGreaterThan(0);
+    }
+  });
+
+  it("declares a marker channel only on the paths it implements (chant #1348)", () => {
+    const channel = cedarPlugin.ownershipChannel!;
+    expect([...channel.reads].sort()).toEqual(["describeResources", "exportResources"]);
+    for (const path of channel.reads) {
+      expect(typeof cedarPlugin[path], path).toBe("function");
+    }
+    // Not declared, because it is not implemented — the whole point of the
+    // per-path declaration is that a caller learns this before asking.
+    expect(channel.reads).not.toContain("observeResourcesDeep");
+    expect(cedarPlugin.observeResourcesDeep).toBeUndefined();
+  });
+
+  it("can enumerate the one kind it deploys", () => {
+    expect(cedarPlugin.ambientKinds?.()).toEqual([CEDAR_POLICY_TYPE]);
+  });
+});

package/src/plugin.ts

@@ -0,0 +1,312 @@
+import type { LexiconPlugin, SkillDefinition, IntrinsicDef, InitTemplateSet } from "@intentius/chant/lexicon";
+import type { LintRule } from "@intentius/chant/lint/rule";
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+import type { CompletionContext, CompletionItem, HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import type { McpToolContribution, McpResourceContribution } from "@intentius/chant/mcp/types";
+import { createSkillsLoader } from "@intentius/chant/lexicon-plugin-helpers";
+import { cedarSerializer } from "./serializer";
+import { rules } from "./lint/rules";
+import { postSynthChecks as cedarPostSynthChecks } from "./lint/post-synth";
+import { cedarAuditCatalog } from "./lint/audit-catalog";
+import { completions } from "./lsp/completions";
+import { hover } from "./lsp/hover";
+import { cedarMcpResources, cedarMcpTools } from "./mcp/index";
+import { cedarInitTemplates } from "./init-templates";
+import { cedarConfigSchema } from "./config";
+import { detectTemplate as detectCedarTemplate } from "./detect";
+import { CedarTemplateGenerator, CedarTemplateParser } from "./import/adapter";
+// #1652 — the AVP ownership channel is data on the plugin, so its keys have to
+// be a value at module load rather than a dynamic import.
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+import { AVP_OWNERSHIP_KEYS } from "./avp/ownership";
+import { AVP_AMBIENT_KINDS } from "./avp/ambient";
+
+/**
+ * cedar lexicon plugin.
+ *
+ * Implements all required LexiconPlugin lifecycle methods.
+ */
+export const cedarPlugin: LexiconPlugin = {
+  name: "cedar",
+  serializer: cedarSerializer,
+
+  // ── Required lifecycle methods ────────────────────────────────
+
+  async generate(options?: { verbose?: boolean }): Promise<void> {
+    // Cedar's codegen input is the project's own schema, so the `cedar` config
+    // namespace is read here rather than being decoration (#1650).
+    const { generate, writeGeneratedFiles } = await import("./codegen/generate");
+    const { loadCedarConfig } = await import("./config");
+    const projectRoot = process.cwd();
+    const result = await generate({ ...options, projectRoot, config: await loadCedarConfig(projectRoot) });
+    writeGeneratedFiles(result);
+  },
+
+  async validate(options?: { verbose?: boolean }): Promise<void> {
+    const { validate } = await import("./validate");
+    const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+    const result = await validate();
+    printValidationResult(result);
+  },
+
+  async coverage(options?: { verbose?: boolean; minOverall?: number }): Promise<void> {
+    const { analyzeCedarCoverage } = await import("./coverage");
+    const { loadCedarConfig } = await import("./config");
+    const projectRoot = process.cwd();
+    analyzeCedarCoverage({
+      projectRoot,
+      config: await loadCedarConfig(projectRoot),
+      verbose: options?.verbose,
+      minOverall: options?.minOverall,
+    });
+  },
+
+  async package(options?: { verbose?: boolean; force?: boolean }): Promise<void> {
+    const { packageLexicon } = await import("./codegen/package");
+    const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+    const { join, dirname } = await import("path");
+    const { fileURLToPath } = await import("url");
+
+    const { spec, stats } = await packageLexicon(options);
+    const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+    writeBundleSpec(spec, join(pkgDir, "dist"));
+
+    console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+  },
+
+  // ── Optional extensions ────────────────────────────────────
+
+  lintRules() {
+    return rules;
+  },
+
+  postSynthChecks() {
+    // Auto-discovered from lint/post-synth/ and committed as a static barrel
+    // by `npm run generate:barrels` — adding a check is dropping a file.
+    return cedarPostSynthChecks;
+  },
+
+  auditCatalog() {
+    return cedarAuditCatalog;
+  },
+
+  skills: createSkillsLoader(import.meta.url, [
+    {
+      file: "chant-cedar-authoring.md",
+      name: "chant-cedar-authoring",
+      description:
+        "Author Cedar policies as typed chant resources — schema to generated classes to .cedar and JSON outputs",
+      triggers: [
+        { type: "file-pattern", value: "**/*.cedarschema" },
+        { type: "file-pattern", value: "**/policies.ts" },
+        { type: "context", value: "cedar policy" },
+        { type: "context", value: "cedar schema" },
+        { type: "context", value: "authorization policy" },
+      ],
+      parameters: [],
+      examples: [
+        {
+          title: "Owner-scoped permit",
+          description: "Grant an action to the owner of a resource",
+          input: "Let users read documents they own",
+          output: `new Policy({ principal: { is: "App::User" }, action: { eq: ReadAction }, when: ["resource.owner == principal"] })`,
+        },
+      ],
+    },
+    {
+      file: "chant-cedar-avp-embedding.md",
+      name: "chant-cedar-avp-embedding",
+      description:
+        "Embed a typed cedar-lexicon policy into an AWS Verified Permissions policy resource instead of a hand-written string",
+      triggers: [
+        { type: "context", value: "verified permissions" },
+        { type: "context", value: "avp policy store" },
+        { type: "context", value: "cedar deployment" },
+        { type: "context", value: "cedar-agent" },
+      ],
+      parameters: [],
+      examples: [
+        {
+          title: "Policy destined for a policy store",
+          input: "Deploy this Cedar policy to Verified Permissions",
+          output: "Emit the .cedar text and reference it — the typed statement seam lands with #1652",
+        },
+      ],
+    },
+    {
+      file: "chant-cedar-meta-policy.md",
+      name: "chant-cedar-meta-policy",
+      description:
+        "Organizational policy over Cedar policy sets — the bare-permit wall, forbid conventions, and env-aware severity",
+      triggers: [
+        { type: "context", value: "cedar lint" },
+        { type: "context", value: "bare permit" },
+        { type: "context", value: "policy review" },
+        { type: "context", value: "meta-policy" },
+      ],
+      parameters: [],
+      examples: [
+        {
+          title: "The bare-permit wall",
+          input: "Is `permit (principal, action, resource);` acceptable?",
+          output: "Warn in dev and staging; fail the build in prod",
+        },
+      ],
+    },
+  ]),
+
+  initTemplates(template?: string): InitTemplateSet {
+    // The branch names are spelled out here rather than only in
+    // ./init-templates.ts because `chant dev check-lexicon` counts a lexicon's
+    // templates by scanning this file. The content lives next door.
+    if (template === "avp-embedding") return cedarInitTemplates("avp-embedding");
+    if (template === "gateway-policy-set") return cedarInitTemplates("gateway-policy-set");
+    return cedarInitTemplates(template);
+  },
+
+  mcpTools() {
+    return cedarMcpTools();
+  },
+
+  mcpResources() {
+    // `createCatalogResource` resolves the registry relative to the module URL
+    // it is handed, so it needs this file's — src/generated/, not src/mcp/.
+    return cedarMcpResources(import.meta.url);
+  },
+
+  detectTemplate(data: unknown) {
+    return detectCedarTemplate(data);
+  },
+
+  /** `.cedar` text and the JSON policy-set envelope, into the core IR (#1653). */
+  templateParser() {
+    return new CedarTemplateParser();
+  },
+
+  /** The IR back out as `new Policy({ … })` against the generated classes. */
+  templateGenerator() {
+    return new CedarTemplateGenerator();
+  },
+
+  completionProvider(ctx: CompletionContext) {
+    return completions(ctx);
+  },
+
+  hoverProvider(ctx: HoverContext) {
+    return hover(ctx);
+  },
+
+  async docs(options?) {
+    const { generateDocs } = await import("./codegen/docs");
+    return generateDocs(options);
+  },
+
+  /** The shape of the `cedar` key in `chant.config.ts` — see ./config.ts. */
+  configSchema: cedarConfigSchema,
+
+  /**
+   * The pinned upstream is the Cedar *grammar*, not a downloaded spec (#1650).
+   *
+   * `CEDAR_WASM_VERSION` is the package version the self-upgrade tooling bumps;
+   * `CEDAR_LANG_VERSION` beside it is the language version `generate()` asserts
+   * at runtime, since a package bump that leaves the language at 4.5 cannot
+   * change what parses. Both live in src/spec/pin.ts, which also carries the
+   * content pin over the bundled default schema.
+   */
+  upstreamPin: {
+    file: "src/spec/pin.ts",
+    pattern: /export const CEDAR_WASM_VERSION\s*=\s*"([^"]+)"/,
+    replace: (v: string, line: string) => line.replace(/= "[^"]+"/, `= "${v}"`),
+    upstream: { owner: "cedar-policy", repo: "cedar", kind: "releases" as const },
+  },
+
+  // ── AVP lifecycle (#1652) ──────────────────────────────────────
+
+  /**
+   * AVP policy stores are taggable; the policies inside them are not, so the
+   * per-policy channel is a marker encoded into `Definition.Static.Description`
+   * and the store's tags are the coarse channel beside it. Only the two paths
+   * that actually read the description are declared (chant #1348) — the full
+   * design record is src/avp/OWNERSHIP.md.
+   */
+  ownershipChannel: {
+    keys: AVP_OWNERSHIP_KEYS,
+    reads: ["describeResources", "exportResources"] as const,
+  },
+
+  /**
+   * Observe the declared policy set against a live AVP policy store.
+   *
+   * The tri-state carries more weight here than on most substrates: a declared
+   * policy reported absent becomes a `create`, and creating a permit that
+   * already exists duplicates a grant. Every path that did not look says so.
+   */
+  async describeResources(options: {
+    environment: string;
+    buildOutput: string;
+    entityNames: string[];
+    entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+    stack?: string;
+    region?: string;
+    owned?: boolean;
+  }) {
+    const { describeAvpResources } = await import("./avp/describe-resources");
+    return describeAvpResources({
+      environment: options.environment,
+      entityNames: options.entityNames,
+      entities: options.entities,
+      ...(options.owned !== undefined ? { owned: options.owned } : {}),
+      ...(options.region ? { client: { region: options.region } } : {}),
+    });
+  },
+
+  /** The one kind this lexicon deploys, and therefore the one it can enumerate. */
+  ambientKinds(): string[] {
+    return [...AVP_AMBIENT_KINDS];
+  },
+
+  /**
+   * Policies in the store that nothing declares — a standing grant nobody in
+   * the source tree can see. For an authorization store this is a security
+   * finding rather than housekeeping.
+   */
+  async observeAmbient(options: {
+    environment: string;
+    kinds: string[];
+    observed: Record<string, ResourceMetadata>;
+    stack?: string;
+    region?: string;
+  }) {
+    const { observeAvpAmbient } = await import("./avp/ambient");
+    return observeAvpAmbient({
+      environment: options.environment,
+      kinds: options.kinds,
+      observed: options.observed,
+      ...(options.region ? { client: { region: options.region } } : {}),
+    });
+  },
+
+  /**
+   * Full-fidelity read of the live policies, as import IR. Server-written
+   * fields are stripped to the declared shape unless `verbatim` is set — see
+   * the note in src/avp/live-export.ts for what counts as server-written when
+   * the only thing a user authors is the statement.
+   */
+  async exportResources(options: {
+    environment: string;
+    stack?: string;
+    region?: string;
+    selector?: { type?: string; name?: string };
+    owned?: boolean;
+    verbatim?: boolean;
+  }) {
+    const { exportAvpResources } = await import("./avp/live-export");
+    return exportAvpResources({
+      environment: options.environment,
+      ...(options.selector ? { selector: options.selector } : {}),
+      ...(options.owned !== undefined ? { owned: options.owned } : {}),
+      ...(options.verbatim !== undefined ? { verbatim: options.verbatim } : {}),
+      ...(options.region ? { client: { region: options.region } } : {}),
+    });
+  },
+};