@intentius/chant-lexicon-cedar 0.44.8 → 0.44.10

package/dist/rules/dwds010.ts

@@ -0,0 +1,46 @@
+/**
+ * DWDS010: an emitted event schema with no pinned field widens every predicate
+ *
+ * The #1657 verification is specific about this one. `ServiceSchema::defaults()`
+ * — what runs when nobody passes `--event-schema` — uses
+ * `configuration/event-schemas/pinned.dwschema`, which carries
+ * `pin callerPrincipal: principalType(A) = principal` on every kind. Every
+ * temporal predicate is therefore correlated to the deciding request's
+ * principal, and events from other principals are invisible.
+ *
+ * Supplying any event schema opts out of that default wholesale. So a schema
+ * emitted without a pin does not merely "not add" a correlation: it removes
+ * one the policy author very likely assumed, and every `formerly` in the set
+ * starts matching other principals' events. That is a legitimate design —
+ * cross-principal correlation is the reason to write your own schema — but it
+ * is a decision, and a decision nobody can see in a diff is one nobody made.
+ *
+ * Report-only: chant does not know which the author wanted, only that it
+ * should be said out loud. `defaultEventSchema({ pinCallerPrincipal: false })`
+ * also stamps the reasoning into the emitted file.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { dogwoodSchemaFiles, readEventSchema } from "../../dogwood/scan";
+
+export const dwds010: PostSynthCheck = {
+  id: "DWDS010",
+  description: "An emitted dogwood event schema pins its temporal predicates to a request-side value",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const schema of dogwoodSchemaFiles(ctx)) {
+      const facts = readEventSchema(schema.text);
+      if (facts.kinds.length === 0 || facts.hasPin) continue;
+      diagnostics.push({
+        checkId: "DWDS010",
+        severity: "warning",
+        message: `Dogwood event schema "${schema.source}" declares no pinned field, so temporal predicates correlate across every principal — wider than upstream's default, which pins callerPrincipal to the deciding request's principal. Add a pinned field, or record why cross-principal correlation is wanted.`,
+        entity: schema.source,
+        lexicon: schema.lexicon,
+      });
+    }
+
+    return diagnostics;
+  },
+};

package/dist/serializer.d.ts

@@ -19,6 +19,12 @@
  * (#1650) generates typed classes onto exactly this shape, so nothing here
  * changes when it lands — the guards become typed expressions rather than
  * the opaque Cedar-expression strings they are today.
+ *
+ * A third view arrives when the build holds dogwood entities (#1658): `.dw`
+ * policy text and its `.dwschema`/`macros.dw` companions, rendered by
+ * `./dogwood/serialize.ts` and returned in the same result. Both legs share
+ * `./policy-text.ts` rather than a copy of it, because a `.dw` policy's head
+ * *is* a Cedar policy's head.
  */
 import type { Declarable } from "@intentius/chant/declarable";
 import type { Serializer } from "@intentius/chant/serializer";
@@ -69,14 +75,7 @@ export interface CedarPolicyProps {
      */
     annotations?: Record<string, string>;
 }
-/** Escape a string for a double-quoted Cedar literal. */
-export declare function escapeCedarString(value: string): string;
-/**
- * Derive a policy id from a logical name: `allowAdminRead` → `allow-admin-read`.
- * Cedar ids are free-form strings; kebab-case keeps them readable in the
- * `@id` annotation and stable across a rename-free refactor.
- */
-export declare function policyIdFromLogicalName(name: string): string;
+export { conditionStrings, escapeCedarString, getProps, isRecord, policyIdFromLogicalName, renderPolicyHead, renderScope, resolvePolicyId, } from "./policy-text.js";
 /**
  * One policy, as `.cedar` text.
  *
@@ -84,6 +83,9 @@ export declare function policyIdFromLogicalName(name: string): string;
  * nothing else — `AWS::VerifiedPermissions::Policy` carries its policy as
  * `Definition.Static.Statement`, a single Cedar policy rather than a set. Two
  * renderers would be two dialects; there is one.
+ *
+ * The head comes from `renderPolicyHead`, which the dogwood dialect's `.dw`
+ * leg also calls: three surfaces, one rendering of an annotation and a scope.
  */
 export declare function renderPolicyText(id: string, props: Record<string, unknown>): string;
 /** The JSON policy-set envelope, exactly as `cedar-wasm` accepts it. */
@@ -117,16 +119,6 @@ export interface CedarPolicyRecord {
     /** Props with references resolved, ready for either renderer. */
     props: Record<string, unknown>;
 }
-/**
- * The Cedar id for a policy: an explicit `annotations.id` when the author gave
- * one, else derived from the logical name.
- *
- * This is the only rule that links a chant entity to a policy in a live AVP
- * store (#1652) — the observation resolves the same id from the same props and
- * matches it against the `@id` annotation the statement carries. Two copies of
- * this rule would be a mapping that drifts silently, so there is one.
- */
-export declare function resolvePolicyId(logicalName: string, props: Record<string, unknown>): string;
 /**
  * Every `Cedar::Policy` in a build, with references walked and ids resolved.
  *

package/dist/serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,EAAE,UAAU,EAAoB,MAAM,6BAA6B,CAAC;AAGhF,OAAO,EAAgD,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAI5F,8CAA8C;AAC9C,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AAEjD,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AAEzD,0EAA0E;AAC1E,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAClB,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GACrB;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,KAAK,CAAC;IAAC,EAAE,CAAC,EAAE,KAAK,CAAA;CAAE,GACtC;IAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAAC,EAAE,CAAC,EAAE,KAAK,CAAC;IAAC,EAAE,CAAC,EAAE,KAAK,CAAA;CAAE,GACjD;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAAC,EAAE,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAEvD,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,qDAAqD;IACrD,SAAS,CAAC,EAAE,UAAU,CAAC;IACvB,qDAAqD;IACrD,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAeD,yDAAyD;AACzD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOvD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM5D;AAmDD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CA0BnF;AAID,wEAAwE;AACxE,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAC3C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACtC,aAAa,EAAE,OAAO,EAAE,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,GAAG,CAAC,EAAE,kBAAkB,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CA4BxF;AAID,yFAAyF;AACzF,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAK3F;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,iBAAiB,EAAE,CAiBzF;AAID,eAAO,MAAM,eAAe,EAAE,UAgC7B,CAAC"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,EAAE,UAAU,EAAoB,MAAM,6BAA6B,CAAC;AAGhF,OAAO,EAAgD,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAY5F,8CAA8C;AAC9C,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AAEjD,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AAEzD,0EAA0E;AAC1E,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAClB,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GACrB;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,KAAK,CAAC;IAAC,EAAE,CAAC,EAAE,KAAK,CAAA;CAAE,GACtC;IAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAAC,EAAE,CAAC,EAAE,KAAK,CAAC;IAAC,EAAE,CAAC,EAAE,KAAK,CAAA;CAAE,GACjD;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAAC,EAAE,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAEvD,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,qDAAqD;IACrD,SAAS,CAAC,EAAE,UAAU,CAAC;IACvB,qDAAqD;IACrD,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AASD,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,QAAQ,EACR,QAAQ,EACR,uBAAuB,EACvB,gBAAgB,EAChB,WAAW,EACX,eAAe,GAChB,MAAM,eAAe,CAAC;AAwBvB;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAWnF;AAID,wEAAwE;AACxE,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAC3C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACtC,aAAa,EAAE,OAAO,EAAE,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,GAAG,CAAC,EAAE,kBAAkB,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CA4BxF;AAID,yFAAyF;AACzF,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,iBAAiB,EAAE,CAiBzF;AAID,eAAO,MAAM,eAAe,EAAE,UAqD7B,CAAC"}

package/dist/skills/chant-cedar-authoring.md

@@ -0,0 +1,180 @@
+---
+skill: chant-cedar-authoring
+description: Author Cedar authorization policies as typed chant resources — schema to generated classes to .cedar and JSON outputs
+user-invocable: true
+---
+
+# Cedar Policies as Typed Resources
+
+## What this lexicon covers
+
+Cedar is an authorization policy language. Its toolchain validates and evaluates
+policies; it does not help you write them. There are no functions, no modules,
+no loops, and templates carry exactly two slots (`?principal`, `?resource`), so
+teams managing large policy sets generate `.cedar` text with string templating.
+This lexicon replaces that with typed TypeScript.
+
+Two artifacts come out of every build:
+
+- `<name>.cedar` — the policy text every Cedar evaluator reads (Amazon Verified
+  Permissions, cedar-agent, an embedded `cedar-wasm`).
+- `policies.cedar.json` — the same set in the Cedar JSON policy format, beside
+  it. This is also the parse source for import.
+
+chant is nowhere in either. An emitted policy set is consumed by any evaluator.
+
+## The three steps
+
+### 1. Declare a schema
+
+The schema is *your* file, not a global upstream — it is the input codegen
+reads. Write it in Cedar's human-readable syntax and point the config at it:
+
+```typescript
+// chant.config.ts
+import type { ChantConfig } from "@intentius/chant";
+import "@intentius/chant-lexicon-cedar";
+
+export default {
+  lexicons: ["cedar"],
+  cedar: {
+    schema: "authz/app.cedarschema",
+    validation: { mode: "strict", requireProjectSchema: true },
+  },
+} satisfies ChantConfig;
+```
+
+Turn `requireProjectSchema` on once the project has its own schema. Without it a
+missing file silently falls back to the bundled default, and the difference
+between "your entity types" and "somebody else's" is invisible.
+
+### 2. Run generate
+
+```bash
+npx chant generate --lexicon cedar
+```
+
+That produces, per declaration in the schema:
+
+| Schema declaration | Generated |
+|---|---|
+| `entity Document in [Folder] = { … }` | `Document` class, `DocumentAttributes` property class, `DocumentUid` template-literal type |
+| `action read appliesTo { … }` | `ReadAction` constant, `ReadContext` property class |
+| — | `Policy` class, `EntityTypeName`, `ActionUid`, `PolicyScope`, `ALL_ACTIONS`, `ALL_ENTITY_TYPES` |
+
+`DocumentUid` is `` `App::Document::"${string}"` `` — a typo'd namespace is a
+compile error, not a validation error hours later.
+
+### 3. Write policies
+
+```typescript
+import { Policy, ReadAction, WriteAction, type UserUid } from "@intentius/chant-lexicon-cedar";
+
+const archivist: UserUid = 'App::User::"archivist"';
+
+export const ownerRead = new Policy({
+  effect: "permit",
+  principal: { is: "App::User" },
+  action: { in: [ReadAction, WriteAction] },
+  resource: { is: "App::Document" },
+  when: ["resource.owner == principal"],
+  annotations: { doc: "Owners always read their own documents." },
+});
+
+export const restrictDelete = new Policy({
+  effect: "forbid",
+  resource: { is: "App::Document" },
+  when: ['resource.classification == "confidential"'],
+  unless: [`principal == ${archivist}`],
+});
+```
+
+## Policy props
+
+| Prop | Meaning |
+|------|---------|
+| `effect` | `"permit"` or `"forbid"`. Defaults to `permit` |
+| `principal`, `action`, `resource` | Scope constraints. Omit for unconstrained |
+| `when` | Cedar expression strings, one `when { … }` clause each |
+| `unless` | Cedar expression strings, one `unless { … }` clause each |
+| `annotations` | `Record<string, string>`, emitted as `@key("value")` |
+
+### Scope forms
+
+| Written | Emitted |
+|---|---|
+| `{}` or omitted | `principal` |
+| `{ eq: X }` | `principal == X` |
+| `{ in: X }` | `principal in X` |
+| `{ in: [X, Y] }` | `principal in [X, Y]` |
+| `{ is: "App::User" }` | `principal is App::User` |
+| `{ is: "App::User", in: X }` | `principal is App::User in X` |
+
+`when`/`unless` stay strings. Cedar's expression grammar *is* the policy
+language; typing it in TypeScript is a separate problem, and the escape hatch
+would leak either way.
+
+## Policy ids
+
+The id comes from the export's logical name, kebab-cased: `allowAdminRead`
+becomes `@id("allow-admin-read")`. Set `annotations.id` to pin one explicitly —
+worth doing for a policy whose id something downstream references.
+
+## Composites
+
+Repeated policy shapes go in a factory, because Cedar has nowhere to put them.
+
+```typescript
+import {
+  DeleteAction,
+  DenyByDefaultSet,
+  OwnerCanManage,
+  ReadAction,
+  WriteAction,
+} from "@intentius/chant-lexicon-cedar";
+
+const docOwner = OwnerCanManage({
+  entityType: "App::Document",
+  actions: [ReadAction, WriteAction],
+  principal: "App::User",
+});
+
+const guarded = DenyByDefaultSet({
+  policies: [docOwner],
+  entityType: "App::Document",
+  actions: DeleteAction,
+  when: ['resource.classification == "confidential"'],
+  unless: ['principal == App::User::"archivist"'],
+});
+
+export const [confidentialFloor, documentOwnerGrant] = guarded.all;
+```
+
+`DenyByDefaultSet` returns the `forbid` floor and its members from one call, so
+deleting the floor deletes the grants with it. A `forbid` beats every `permit`
+in the set unconditionally — it is the only construct that survives a later,
+wider grant.
+
+## Checking the result
+
+```bash
+npx chant build                         # emits both artifacts, runs the CED rules
+npx chant coverage --lexicon cedar      # is every schema declaration generated?
+```
+
+The MCP tool `cedar:coverage` answers the other question: which schema entity
+types and actions the *policy set* can reach, which are reachable only from a
+`forbid`, and which no policy touches at all. An entity type nothing covers is
+inert under Cedar's default-deny — either the intent or a hole.
+
+## Things that will bite
+
+- **An empty schema validates everything clean.** `checkParseSchema("")`
+  succeeds. Set `requireProjectSchema: true`.
+- **`Group` and `Team`-shaped container entities appear in no `appliesTo`.**
+  They exist to be `in`, so no policy — not even `permit (principal, action,
+  resource)` — resolves to them. `cedar:coverage` reports that honestly rather
+  than rounding it up.
+- **A policy naming an entity type outside the schema still parses.** It
+  resolves to an empty request envelope and never fires. `cedar:coverage`
+  reports it under `inert`.

package/dist/skills/chant-cedar-avp-embedding.md

@@ -0,0 +1,125 @@
+---
+skill: chant-cedar-avp-embedding
+description: Embed a typed cedar-lexicon policy into an AWS Verified Permissions policy resource instead of a hand-written string
+user-invocable: true
+---
+
+# Cedar Policies Inside Verified Permissions
+
+## The seam
+
+Amazon Verified Permissions is one deployment vehicle for Cedar, and chant
+already ships it: `AWS::VerifiedPermissions::Policy` in the aws lexicon carries
+its policy text in a `definition.static.statement` field typed `CedarPolicy` —
+which is to say, `string`.
+
+That string is the seam. Everything upstream of it — the schema, the entity
+types, the actions, the scope constraints — is what the cedar lexicon owns.
+Everything downstream — the policy store, the CloudFormation `ApplyOp`, the IAM
+around it — is the aws lexicon's, and already works.
+
+```
+cedar lexicon                       aws lexicon
+schema → Policy → .cedar text  →   VerifiedPermissionsPolicy.definition.static.statement
+```
+
+The walk-away test holds on both sides. The emitted `.cedar` file is read by any
+evaluator with no AWS involved; the AVP resource deploys through the same
+CloudFormation path every other AWS resource does.
+
+## The typed handoff
+
+`avpPolicyDefinition(name, props)` returns exactly the `Definition` property
+`AWS::VerifiedPermissions::Policy` takes, rendered by the same renderer that
+writes the `.cedar` file — so the deployed policy and the reviewed file cannot
+disagree.
+
+```typescript
+import { Policy, ReadAction, avpPolicyDefinition } from "@intentius/chant-lexicon-cedar";
+import { VerifiedPermissionsPolicy } from "@intentius/chant-lexicon-aws";
+
+const ownerReadProps = {
+  effect: "permit",
+  principal: { is: "App::User" },
+  action: { eq: ReadAction },
+  resource: { is: "App::Document" },
+  when: ["resource.owner == principal"],
+} as const;
+
+/** The evaluator-agnostic artifact: this is what lands in the `.cedar` file. */
+export const ownerRead = new Policy(ownerReadProps);
+
+/** The AVP deployment view of the same policy. */
+export const ownerReadAvp = new VerifiedPermissionsPolicy({
+  PolicyStoreId: policyStore.ref(),
+  Definition: avpPolicyDefinition("ownerRead", ownerReadProps, {
+    ownership: { stack: "authz", env: "prod" },
+    description: "Owners read their own documents.",
+  }),
+});
+```
+
+Beside it: `avpStatement()` for the bare string, `avpStatementJSON()` for
+evaluators that take the JSON policy format, and `avpPolicySet(entities)` to
+render a whole build's policies at once, keyed by chant entity name.
+
+**The cedar lexicon does not depend on the aws lexicon.** The seam is the data
+shape, which is stable CloudFormation. `examples/avp-embedding/` shows the
+pairing with a plain-object stand-in, because the shipped cedar examples build
+against the cedar serializer alone.
+
+## The lifecycle surface
+
+`describeResources()`, `observeAmbient()` and `exportResources()` read a live
+policy store. Point them at one with `CEDAR_AVP_POLICY_STORE_ID` (or
+`CEDAR_AVP_POLICY_STORE_ID_<ENV>`), or a `policyStoreId` prop on a declared
+policy.
+
+The link from a chant entity to a live policy is the Cedar `@id` annotation,
+which is derived from the export name (`ownerRead` → `owner-read`) unless
+`annotations.id` overrides it. Rename an export and the observation follows it;
+rename it *and* pin `annotations.id` and the live policy stays matched.
+
+## Rules
+
+- **Do not write the statement as prose.** A hand-typed
+  `"permit(principal, action, resource);"` in an AVP resource is the exact thing
+  this lexicon exists to remove, and the meta-policy wall (see the
+  `chant-cedar-meta-policy` skill) fails a bare permit in a prod build.
+- **Do not try to tag an individual policy.** AVP policy *stores* are taggable;
+  individual policies are not — `CreatePolicy` has no tag surface and a policy
+  has no ARN. chant's per-policy marker therefore rides in the policy
+  description, stamped by passing `ownership` to `avpPolicyDefinition` and read
+  back by `describeResources`/`exportResources`. Store tags remain the coarse
+  channel. The design record, including what the choice costs, is
+  `src/avp/OWNERSHIP.md`.
+- **Do not hand-write the description when you want ownership.** Pass
+  `ownership` and let the marker be encoded; the description is capped at 150
+  characters and the encoder truncates prose rather than the marker, which is
+  what keeps a chant-owned policy from silently reading as foreign.
+- **Do not treat an ambient permit as housekeeping.** A permit found in a store
+  that no source file declares is a standing grant somebody made outside review.
+  It is a security finding. `observeAmbient()` reports the statement and its
+  effect and stops short of the verdict — the judgement is yours.
+
+## Non-AVP evaluators
+
+AVP is not the only target, and the lexicon does not privilege it. The same
+emitted `.cedar` and `policies.cedar.json` feed:
+
+- **cedar-agent** — a standalone Cedar decision service; point it at the policy
+  file and the entity store.
+- **An embedded `cedar-wasm`** — the package this lexicon already depends on.
+  Load the policy text in-process and call `isAuthorized`.
+- **Cloudflare-style embeddings** — the same file, read at the edge.
+
+If the deployment target is anything other than AVP, there is no embedding step
+at all. Emit the files and ship them.
+
+## Cedar-for-Kubernetes
+
+The CNCF push includes Cedar as a Kubernetes authorizer, with policies as CRDs.
+Those kinds belong to the k8s lexicon's CRD sources — the same rule that kept
+`helm.cattle.io` out of the k3s lexicon. What the cedar lexicon does there is
+lint the policy *text* embedded in those kinds, which is the pattern the ARGO
+rules already use.