@agentproto/policy 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentproto contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @agentproto/policy
+
+AIP-38 `POLICY.md` reference implementation. A markdown + frontmatter format for declaring policy on a resource — access grants (who can perform which actions), defaults (per-block behavioural defaults), limits (rate / quota caps), and requirements (cross-cutting must-haves like MFA / approval). Composable inline | ref | file. Granted on AIP-39 ACTION ids — implementations / TOOLs are decoupled from policy.
+
+> **Status: 0.1.0-alpha.** Generated by `scripts/scaffold-aip.mjs` — `build()` and `validate()` bodies are TODOs.
+
+Spec: <https://agentproto.sh/docs/aip-38>
+
+## Usage
+
+```ts
+import { definePolicy } from "@agentproto/policy"
+
+const x = definePolicy({
+  id: "my-policy",
+  description: "Short purpose.",
+  // ...
+})
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/chunk-DS2TYMHI.mjs

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { createDoctype } from '@agentproto/define-doctype';
+
+/**
+ * @agentproto/policy v0.1.0-alpha
+ * AIP-38 POLICY.md `definePolicy` reference implementation.
+ */
+
+var policyFrontmatterSchema = z.object({ "schema": z.literal("policy/v1"), "id": z.string().regex(new RegExp("^@[a-z0-9][a-z0-9-]*/[a-z0-9][a-z0-9-]*$")).describe("Standalone-only. Globally addressable id `@<owner-slug>/<policy-slug>`.").optional(), "version": z.string().regex(new RegExp("^\\d+\\.\\d+\\.\\d+(?:[-+][\\w.\\-]+)?$")).describe("Standalone-only. Spec version of THIS file.").optional(), "default": z.enum(["allow", "deny"]).describe("Default decision when no grant matches. `deny` strongly recommended; `allow` is audit-significant.").default("deny"), "grants": z.array(z.any()).describe("Access grants. Each grant ties a principal (AIP-23) to a set of actions (AIP-39).").default([]), "defaults": z.record(z.string(), z.record(z.string(), z.any())).describe("Per-block behavioural defaults. Keys are AIP block names (storage, sandbox, code, secrets); values are partial block configs.").default({}), "limits": z.array(z.any()).describe("Resource limits. Each `{ kind, value, scope?, per?, applies_to? }`.").default([]), "requirements": z.array(z.any()).describe("Cross-cutting must-haves (MFA, signing, approvals). ANDed across composed policies.").default([]), "metadata": z.record(z.string(), z.any()).describe("Free-form, namespaced.").optional() }).strict().describe("Validates the YAML frontmatter portion of an AIP-38 POLICY.md manifest, OR the inline form embedded in any other manifest's `policy:` block. Grants on AIP-39 ACTION ids; principals via AIP-23 identity-ref schemes.");
+var definePolicy = createDoctype({
+  aip: 38,
+  name: "policy",
+  readDescription: false,
+  validate(def) {
+    const result = policyFrontmatterSchema.safeParse(def);
+    if (!result.success) {
+      throw new Error(
+        `definePolicy (AIP-38): ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+      );
+    }
+  },
+  build(def) {
+    return { ...def };
+  }
+});
+
+export { definePolicy, policyFrontmatterSchema };
+//# sourceMappingURL=chunk-DS2TYMHI.mjs.map
+//# sourceMappingURL=chunk-DS2TYMHI.mjs.map

package/dist/chunk-DS2TYMHI.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts","../src/define-policy.ts"],"names":[],"mappings":";;;;;;;;AAeO,IAAM,uBAAA,GAA0B,CAAA,CAAE,MAAA,CAAO,EAAE,QAAA,EAAU,CAAA,CAAE,OAAA,CAAQ,WAAW,CAAA,EAAG,IAAA,EAAM,CAAA,CAAE,MAAA,GAAS,KAAA,CAAM,IAAI,MAAA,CAAO,0CAA0C,CAAC,CAAA,CAAE,QAAA,CAAS,yEAAyE,EAAE,QAAA,EAAS,EAAG,SAAA,EAAW,CAAA,CAAE,MAAA,EAAO,CAAE,KAAA,CAAM,IAAI,OAAO,yCAAyC,CAAC,CAAA,CAAE,QAAA,CAAS,6CAA6C,CAAA,CAAE,QAAA,EAAS,EAAG,WAAW,CAAA,CAAE,IAAA,CAAK,CAAC,OAAA,EAAQ,MAAM,CAAC,CAAA,CAAE,QAAA,CAAS,oGAAoG,CAAA,CAAE,OAAA,CAAQ,MAAM,CAAA,EAAG,QAAA,EAAU,CAAA,CAAE,KAAA,CAAM,CAAA,CAAE,KAAK,CAAA,CAAE,QAAA,CAAS,mFAAmF,CAAA,CAAE,OAAA,CAAQ,EAAW,GAAG,UAAA,EAAY,CAAA,CAAE,MAAA,CAAO,CAAA,CAAE,MAAA,EAAO,EAAG,CAAA,CAAE,MAAA,CAAO,CAAA,CAAE,MAAA,EAAO,EAAG,CAAA,CAAE,GAAA,EAAK,CAAC,CAAA,CAAE,SAAS,+HAA+H,CAAA,CAAE,OAAA,CAAQ,EAAW,CAAA,EAAG,QAAA,EAAU,CAAA,CAAE,MAAM,CAAA,CAAE,GAAA,EAAK,CAAA,CAAE,QAAA,CAAS,qEAAqE,CAAA,CAAE,OAAA,CAAQ,EAAW,CAAA,EAAG,cAAA,EAAgB,CAAA,CAAE,KAAA,CAAM,CAAA,CAAE,GAAA,EAAK,EAAE,QAAA,CAAS,qFAAqF,CAAA,CAAE,OAAA,CAAQ,EAAW,CAAA,EAAG,UAAA,EAAY,EAAE,MAAA,CAAO,CAAA,CAAE,MAAA,EAAO,EAAG,CAAA,CAAE,GAAA,EAAK,CAAA,CAAE,SAAS,wBAAwB,CAAA,CAAE,QAAA,EAAS,EAAG,CAAA,CAAE,MAAA,EAAO,CAAE,SAAS,uNAAuN;ACMlgD,IAAM,eAAe,aAAA,CAA8C;AAAA,EACxE,GAAA,EAAK,EAAA;AAAA,EACL,IAAA,EAAM,QAAA;AAAA,EACN,eAAA,EAAiB,KAAA;AAAA,EACjB,SAAS,GAAA,EAAK;AACZ,IAAA,MAAM,MAAA,GAAS,uBAAA,CAAwB,SAAA,CAAU,GAAG,CAAA;AACpD,IAAA,IAAI,CAAC,OAAO,OAAA,EAAS;AACnB,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,CAAA,uBAAA,EAA0B,OAAO,KAAA,CAAM,MAAA,CACpC,IAAI,CAAC,CAAA,KAAM,GAAG,CAAA,CAAE,IAAA,CAAK,KAAK,GAAG,CAAC,KAAK,CAAA,CAAE,OAAO,EAAE,CAAA,CAC9C,IAAA,CAAK,IAAI,CAAC,CAAA;AAAA,OACf;AAAA,IACF;AAAA,EAIF,CAAA;AAAA,EACA,MAAM,GAAA,EAAK;AAKT,IAAA,OAAO,EAAE,GAAG,GAAA,EAAI;AAAA,EAClB;AACF,CAAC","file":"chunk-DS2TYMHI.mjs","sourcesContent":["/**\n * AIP-38 POLICY.md frontmatter zod schema.\n *\n * Generated from `resources/aip-38/draft/POLICY.schema.json` via\n * json-schema-to-zod. Imported by both `define-policy.ts` (TS path\n * validation) and `manifest/index.ts` (.md path validation) so every\n * field-level constraint runs in both authoring paths from a single\n * source of truth — re-run scaffold-aip to refresh after spec changes.\n *\n * Cross-field rules (if/then/allOf in JSON Schema) don't translate\n * cleanly and live in `define-policy.ts`'s `validate(def)` instead.\n */\n\nimport { z } from \"zod\"\n\nexport const policyFrontmatterSchema = z.object({ \"schema\": z.literal(\"policy/v1\"), \"id\": z.string().regex(new RegExp(\"^@[a-z0-9][a-z0-9-]*/[a-z0-9][a-z0-9-]*$\")).describe(\"Standalone-only. Globally addressable id `@<owner-slug>/<policy-slug>`.\").optional(), \"version\": z.string().regex(new RegExp(\"^\\\\d+\\\\.\\\\d+\\\\.\\\\d+(?:[-+][\\\\w.\\\\-]+)?$\")).describe(\"Standalone-only. Spec version of THIS file.\").optional(), \"default\": z.enum([\"allow\",\"deny\"]).describe(\"Default decision when no grant matches. `deny` strongly recommended; `allow` is audit-significant.\").default(\"deny\"), \"grants\": z.array(z.any()).describe(\"Access grants. Each grant ties a principal (AIP-23) to a set of actions (AIP-39).\").default([] as never), \"defaults\": z.record(z.string(), z.record(z.string(), z.any())).describe(\"Per-block behavioural defaults. Keys are AIP block names (storage, sandbox, code, secrets); values are partial block configs.\").default({} as never), \"limits\": z.array(z.any()).describe(\"Resource limits. Each `{ kind, value, scope?, per?, applies_to? }`.\").default([] as never), \"requirements\": z.array(z.any()).describe(\"Cross-cutting must-haves (MFA, signing, approvals). ANDed across composed policies.\").default([] as never), \"metadata\": z.record(z.string(), z.any()).describe(\"Free-form, namespaced.\").optional() }).strict().describe(\"Validates the YAML frontmatter portion of an AIP-38 POLICY.md manifest, OR the inline form embedded in any other manifest's `policy:` block. Grants on AIP-39 ACTION ids; principals via AIP-23 identity-ref schemes.\")\n\nexport type PolicyFrontmatter = z.infer<typeof policyFrontmatterSchema>\n","import { createDoctype } from \"@agentproto/define-doctype\"\nimport { policyFrontmatterSchema } from \"./schema.js\"\nimport type { PolicyDefinition, PolicyHandle } from \"./types.js\"\n\n/**\n * AIP-38 reference implementation of `definePolicy`.\n *\n * Built on `createDoctype` so the cross-AIP invariants (id pattern,\n * description length, top-level freeze, \"definePolicy (AIP-38): …\"\n * error prefix) run uniformly with every other AIP defineX.\n *\n * Field-level validation runs the schema-derived zod from\n * `./schema.ts` against the input. Same source of truth as the .md\n * path uses (`parsePolicyManifest`), so a malformed TS-authored\n * definition fails with the same diagnostic as a malformed manifest.\n * Cross-field rules go in `validate(def)` after the zod check.\n *\n * Identity / description extractors detected from the JSON Schema:\n *   readIdentity: def.id\n *   readDescription: skipped (no string-y required field detected).\n */\nexport const definePolicy = createDoctype<PolicyDefinition, PolicyHandle>({\n  aip: 38,\n  name: \"policy\",\n  readDescription: false,\n  validate(def) {\n    const result = policyFrontmatterSchema.safeParse(def)\n    if (!result.success) {\n      throw new Error(\n        `definePolicy (AIP-38): ${result.error.issues\n          .map((i) => `${i.path.join(\".\")}: ${i.message}`)\n          .join(\"; \")}`,\n      )\n    }\n    // TODO: spec-38-specific cross-field rules (if/then/allOf in\n    // the JSON Schema) — those don't translate to zod cleanly and\n    // belong here. See @agentproto/operator's autonomy=gated rule.\n  },\n  build(def) {\n    // Default build: spread the validated definition into a fresh object.\n    // Hand-tune for nested freezing (Object.freeze on arrays/objects) and\n    // for fields that need defaults applied — see @agentproto/operator\n    // for a reference shape.\n    return { ...def } as PolicyHandle\n  },\n})\n"]}

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import { P as PolicyDefinition } from './schema-ALC4Y3-2.js';
+export { a as PolicyFrontmatter, b as PolicyHandle, p as policyFrontmatterSchema } from './schema-ALC4Y3-2.js';
+import 'zod';
+
+/**
+ * AIP-38 reference implementation of `definePolicy`.
+ *
+ * Built on `createDoctype` so the cross-AIP invariants (id pattern,
+ * description length, top-level freeze, "definePolicy (AIP-38): …"
+ * error prefix) run uniformly with every other AIP defineX.
+ *
+ * Field-level validation runs the schema-derived zod from
+ * `./schema.ts` against the input. Same source of truth as the .md
+ * path uses (`parsePolicyManifest`), so a malformed TS-authored
+ * definition fails with the same diagnostic as a malformed manifest.
+ * Cross-field rules go in `validate(def)` after the zod check.
+ *
+ * Identity / description extractors detected from the JSON Schema:
+ *   readIdentity: def.id
+ *   readDescription: skipped (no string-y required field detected).
+ */
+declare const definePolicy: (def: PolicyDefinition) => Readonly<PolicyDefinition>;
+
+/**
+ * @agentproto/policy — AIP-38 POLICY.md `definePolicy` reference impl.
+ *
+ * A markdown + frontmatter format for declaring policy on a resource — access grants (who can perform which actions), defaults (per-block behavioural defaults), limits (rate / quota caps), and requirements (cross-cutting must-haves like MFA / approval). Composable inline | ref | file. Granted on AIP-39 ACTION ids — implementations / TOOLs are decoupled from policy.
+ *
+ * Spec: https://agentproto.sh/docs/aip-38
+ *
+ * Authoring paths:
+ *   - TS:  `definePolicy({...})` → `PolicyHandle`
+ *   - MD:  `parsePolicyManifest(src) → policyFromManifest({...})` → `PolicyHandle`
+ */
+declare const SPEC_NAME: "agentpolicy/v1";
+declare const SPEC_VERSION: "1.0.0-alpha";
+
+export { PolicyDefinition, SPEC_NAME, SPEC_VERSION, definePolicy };

package/dist/index.mjs

@@ -0,0 +1,14 @@
+export { definePolicy, policyFrontmatterSchema } from './chunk-DS2TYMHI.mjs';
+
+/**
+ * @agentproto/policy v0.1.0-alpha
+ * AIP-38 POLICY.md `definePolicy` reference implementation.
+ */
+
+// src/index.ts
+var SPEC_NAME = "agentpolicy/v1";
+var SPEC_VERSION = "1.0.0-alpha";
+
+export { SPEC_NAME, SPEC_VERSION };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;AAYO,IAAM,SAAA,GAAY;AAClB,IAAM,YAAA,GAAe","file":"index.mjs","sourcesContent":["/**\n * @agentproto/policy — AIP-38 POLICY.md `definePolicy` reference impl.\n *\n * A markdown + frontmatter format for declaring policy on a resource — access grants (who can perform which actions), defaults (per-block behavioural defaults), limits (rate / quota caps), and requirements (cross-cutting must-haves like MFA / approval). Composable inline | ref | file. Granted on AIP-39 ACTION ids — implementations / TOOLs are decoupled from policy.\n *\n * Spec: https://agentproto.sh/docs/aip-38\n *\n * Authoring paths:\n *   - TS:  `definePolicy({...})` → `PolicyHandle`\n *   - MD:  `parsePolicyManifest(src) → policyFromManifest({...})` → `PolicyHandle`\n */\n\nexport const SPEC_NAME = \"agentpolicy/v1\" as const\nexport const SPEC_VERSION = \"1.0.0-alpha\" as const\n\nexport { definePolicy } from \"./define-policy.js\"\nexport { policyFrontmatterSchema } from \"./schema.js\"\nexport type { PolicyFrontmatter } from \"./schema.js\"\nexport type { PolicyDefinition, PolicyHandle } from \"./types.js\"\n"]}

package/dist/manifest/index.d.ts

@@ -0,0 +1,28 @@
+import { a as PolicyFrontmatter, b as PolicyHandle } from '../schema-ALC4Y3-2.js';
+export { p as policyFrontmatterSchema } from '../schema-ALC4Y3-2.js';
+import 'zod';
+
+/**
+ * AIP-38 POLICY.md sidecar parser + manifest-to-handle constructor.
+ *
+ * Mirror of `@agentproto/tool/manifest` and `@agentproto/driver/manifest`:
+ * the .md provides metadata; the TS module supplies any spec-specific
+ * runtime bits (schemas, execute bodies, …) that can't live in
+ * frontmatter. Both inputs end up in `definePolicy` so the cross-AIP
+ * invariants run uniformly.
+ *
+ *
+ * The frontmatter zod schema below was generated from
+ * `resources/aip-38/draft/POLICY.schema.json` via json-schema-to-zod.
+ * Re-run scaffold-aip to refresh after spec changes (or hand-tune
+ * any constraint the converter doesn't capture cleanly).
+ */
+
+interface PolicyManifest {
+    frontmatter: PolicyFrontmatter;
+    body: string;
+}
+declare function parsePolicyManifest(source: string): PolicyManifest;
+declare function policyFromManifest(manifest: PolicyManifest): PolicyHandle;
+
+export { PolicyFrontmatter, type PolicyManifest, parsePolicyManifest, policyFromManifest };

package/dist/manifest/index.mjs

@@ -0,0 +1,28 @@
+import { policyFrontmatterSchema, definePolicy } from '../chunk-DS2TYMHI.mjs';
+export { policyFrontmatterSchema } from '../chunk-DS2TYMHI.mjs';
+import matter from 'gray-matter';
+
+/**
+ * @agentproto/policy v0.1.0-alpha
+ * AIP-38 POLICY.md `definePolicy` reference implementation.
+ */
+function parsePolicyManifest(source) {
+  const parsed = matter(source);
+  if (Object.keys(parsed.data).length === 0) {
+    throw new Error("parsePolicyManifest: missing or empty frontmatter");
+  }
+  const result = policyFrontmatterSchema.safeParse(parsed.data);
+  if (!result.success) {
+    throw new Error(
+      `parsePolicyManifest: invalid frontmatter \u2014 ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+    );
+  }
+  return { frontmatter: result.data, body: parsed.content };
+}
+function policyFromManifest(manifest) {
+  return definePolicy(manifest.frontmatter);
+}
+
+export { parsePolicyManifest, policyFromManifest };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/manifest/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/manifest/index.ts"],"names":[],"mappings":";;;;;;;;AA8BO,SAAS,oBAAoB,MAAA,EAAgC;AAClE,EAAA,MAAM,MAAA,GAAS,OAAO,MAAM,CAAA;AAC5B,EAAA,IAAI,OAAO,IAAA,CAAK,MAAA,CAAO,IAAI,CAAA,CAAE,WAAW,CAAA,EAAG;AACzC,IAAA,MAAM,IAAI,MAAM,mDAAmD,CAAA;AAAA,EACrE;AACA,EAAA,MAAM,MAAA,GAAS,uBAAA,CAAwB,SAAA,CAAU,MAAA,CAAO,IAAI,CAAA;AAC5D,EAAA,IAAI,CAAC,OAAO,OAAA,EAAS;AACnB,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,CAAA,gDAAA,EAA8C,OAAO,KAAA,CAAM,MAAA,CACxD,IAAI,CAAC,CAAA,KAAM,GAAG,CAAA,CAAE,IAAA,CAAK,KAAK,GAAG,CAAC,KAAK,CAAA,CAAE,OAAO,EAAE,CAAA,CAC9C,IAAA,CAAK,IAAI,CAAC,CAAA;AAAA,KACf;AAAA,EACF;AACA,EAAA,OAAO,EAAE,WAAA,EAAa,MAAA,CAAO,IAAA,EAAM,IAAA,EAAM,OAAO,OAAA,EAAQ;AAC1D;AAEO,SAAS,mBAAmB,QAAA,EAAwC;AAKzE,EAAA,OAAO,YAAA,CAAa,SAAS,WAA0C,CAAA;AACzE","file":"index.mjs","sourcesContent":["/**\n * AIP-38 POLICY.md sidecar parser + manifest-to-handle constructor.\n *\n * Mirror of `@agentproto/tool/manifest` and `@agentproto/driver/manifest`:\n * the .md provides metadata; the TS module supplies any spec-specific\n * runtime bits (schemas, execute bodies, …) that can't live in\n * frontmatter. Both inputs end up in `definePolicy` so the cross-AIP\n * invariants run uniformly.\n *\n *\n * The frontmatter zod schema below was generated from\n * `resources/aip-38/draft/POLICY.schema.json` via json-schema-to-zod.\n * Re-run scaffold-aip to refresh after spec changes (or hand-tune\n * any constraint the converter doesn't capture cleanly).\n */\n\nimport matter from \"gray-matter\"\nimport { policyFrontmatterSchema, type PolicyFrontmatter } from \"../schema.js\"\nimport { definePolicy } from \"../define-policy.js\"\nimport type { PolicyDefinition, PolicyHandle } from \"../types.js\"\n\n// Re-export so consumers can import the schema + inferred type either\n// from \"@@agentproto/policy/manifest\" or directly from \"@@agentproto/policy/schema\".\nexport { policyFrontmatterSchema, type PolicyFrontmatter }\n\nexport interface PolicyManifest {\n  frontmatter: PolicyFrontmatter\n  body: string\n}\n\nexport function parsePolicyManifest(source: string): PolicyManifest {\n  const parsed = matter(source)\n  if (Object.keys(parsed.data).length === 0) {\n    throw new Error(\"parsePolicyManifest: missing or empty frontmatter\")\n  }\n  const result = policyFrontmatterSchema.safeParse(parsed.data)\n  if (!result.success) {\n    throw new Error(\n      `parsePolicyManifest: invalid frontmatter — ${result.error.issues\n        .map((i) => `${i.path.join(\".\")}: ${i.message}`)\n        .join(\"; \")}`,\n    )\n  }\n  return { frontmatter: result.data, body: parsed.content }\n}\n\nexport function policyFromManifest(manifest: PolicyManifest): PolicyHandle {\n  // The zod-validated frontmatter is structurally compatible with\n  // PolicyDefinition; the cast pins the typing once the manifest\n  // schema and the TS interface diverge (e.g. handle has frozen fields\n  // a literal config doesn't carry yet).\n  return definePolicy(manifest.frontmatter as unknown as PolicyDefinition)\n}\n"]}

package/dist/schema-ALC4Y3-2.d.ts

@@ -0,0 +1,196 @@
+import { z } from 'zod';
+
+/**
+ * AIP-38 PolicyDefinition + PolicyHandle.
+ *
+ * `PolicyDefinition` was generated from
+ * `resources/aip-38/draft/POLICY.schema.json` via json-schema-to-typescript.
+ * `PolicyHandle` is the readonly view of the same shape; tighten it
+ * by hand for fields that get defaults applied in build().
+ */
+/**
+ * Validates the YAML frontmatter portion of an AIP-38 POLICY.md manifest, OR the inline form embedded in any other manifest's `policy:` block. Grants on AIP-39 ACTION ids; principals via AIP-23 identity-ref schemes.
+ */
+interface PolicyDefinition {
+    schema: "policy/v1";
+    /**
+     * Standalone-only. Globally addressable id `@<owner-slug>/<policy-slug>`.
+     */
+    id?: string;
+    /**
+     * Standalone-only. Spec version of THIS file.
+     */
+    version?: string;
+    /**
+     * Default decision when no grant matches. `deny` strongly recommended; `allow` is audit-significant.
+     */
+    default?: "allow" | "deny";
+    /**
+     * Access grants. Each grant ties a principal (AIP-23) to a set of actions (AIP-39).
+     */
+    grants?: Grant[];
+    /**
+     * Per-block behavioural defaults. Keys are AIP block names (storage, sandbox, code, secrets); values are partial block configs.
+     */
+    defaults?: {
+        [k: string]: {
+            [k: string]: unknown;
+        };
+    };
+    /**
+     * Resource limits. Each `{ kind, value, scope?, per?, applies_to? }`.
+     */
+    limits?: Limit[];
+    /**
+     * Cross-cutting must-haves (MFA, signing, approvals). ANDed across composed policies.
+     */
+    requirements?: Requirement[];
+    /**
+     * Free-form, namespaced.
+     */
+    metadata?: {
+        [k: string]: unknown;
+    };
+}
+interface Grant {
+    /**
+     * AIP-23 identity-ref. Schemes: operator://, user://, org://, guild://, bot://, group://, role://, *.
+     */
+    principal: {
+        name: string;
+        email: string;
+        avatar?: string;
+        gpg_key?: string;
+        role?: string;
+        metadata?: {};
+        [k: string]: unknown;
+    } | {
+        ref: string;
+        role?: string;
+        [k: string]: unknown;
+    } | {
+        file: string;
+        role?: string;
+        [k: string]: unknown;
+    } | string;
+    /**
+     * @minItems 1
+     */
+    actions: [ActionGrant, ...ActionGrant[]];
+    /**
+     * Conditions ANDed (all must hold). Unknown conditions skip the grant.
+     */
+    conditions?: Condition[];
+    /**
+     * Time-bound grant; expires at granted_at + ttl_seconds.
+     */
+    ttl_seconds?: number;
+    /**
+     * ISO 8601. Audit metadata.
+     */
+    granted_at?: string;
+    /**
+     * Who issued this grant. Audit metadata.
+     */
+    granted_by?: {
+        name: string;
+        email: string;
+        avatar?: string;
+        gpg_key?: string;
+        role?: string;
+        metadata?: {};
+        [k: string]: unknown;
+    } | {
+        ref: string;
+        role?: string;
+        [k: string]: unknown;
+    } | {
+        file: string;
+        role?: string;
+        [k: string]: unknown;
+    } | string;
+    /**
+     * Soft-revoke marker. A revoked grant evaluates as no-grant.
+     */
+    revoked?: boolean;
+}
+interface ActionGrant {
+    /**
+     * AIP-39 ACTION reference. Bare id (e.g. `storage:commit`), workspace-relative path, or registry slug (`@agentik/actions/standard/storage-commit`). `*` suffix permits wildcards (`storage:*`).
+     */
+    action: string;
+    /**
+     * Optional scope narrowing for this grant (action-specific).
+     */
+    scope?: string;
+}
+interface Condition {
+    /**
+     * Condition kind. Standard: `during-business-hours`, `ip-range`, `mfa-recent`, `approval-from`, `signed-by`. Hosts MAY register custom kinds.
+     */
+    kind: string;
+    [k: string]: unknown;
+}
+interface Limit {
+    /**
+     * Limit kind. Standard: `max-concurrent-sandboxes`, `rate-tool-calls`, `max-egress-bytes-per-day`. Host-extensible.
+     */
+    kind: string;
+    value: number;
+    /**
+     * Per what? `user`, `workspace`, `org`, host-specific.
+     */
+    scope?: string;
+    /**
+     * For rate-style limits.
+     */
+    per?: "second" | "minute" | "hour" | "day";
+    /**
+     * Action refs the limit applies to. Empty / missing = all actions.
+     */
+    applies_to?: string[];
+    [k: string]: unknown;
+}
+interface Requirement {
+    /**
+     * Requirement kind. Standard: `mfa-recent`, `signed-by`, `approval-from`. Host-extensible.
+     */
+    kind: string;
+    /**
+     * Action refs this requirement applies to. Empty / missing = all actions.
+     */
+    applies_to?: string[];
+    [k: string]: unknown;
+}
+type PolicyHandle = Readonly<PolicyDefinition>;
+
+/**
+ * AIP-38 POLICY.md frontmatter zod schema.
+ *
+ * Generated from `resources/aip-38/draft/POLICY.schema.json` via
+ * json-schema-to-zod. Imported by both `define-policy.ts` (TS path
+ * validation) and `manifest/index.ts` (.md path validation) so every
+ * field-level constraint runs in both authoring paths from a single
+ * source of truth — re-run scaffold-aip to refresh after spec changes.
+ *
+ * Cross-field rules (if/then/allOf in JSON Schema) don't translate
+ * cleanly and live in `define-policy.ts`'s `validate(def)` instead.
+ */
+
+declare const policyFrontmatterSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"policy/v1">;
+    id: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    default: z.ZodDefault<z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+    }>>;
+    grants: z.ZodDefault<z.ZodArray<z.ZodAny>>;
+    defaults: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodAny>>>;
+    limits: z.ZodDefault<z.ZodArray<z.ZodAny>>;
+    requirements: z.ZodDefault<z.ZodArray<z.ZodAny>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$strict>;
+type PolicyFrontmatter = z.infer<typeof policyFrontmatterSchema>;
+
+export { type PolicyDefinition as P, type PolicyFrontmatter as a, type PolicyHandle as b, policyFrontmatterSchema as p };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@agentproto/policy",
+  "version": "0.1.0-alpha.0",
+  "description": "@agentproto/policy — AIP-38 POLICY.md reference implementation. A markdown + frontmatter format for declaring policy on a resource — access grants (who can perform which actions), defaults (per-block behavioural defaults), limits (rate / quota caps), and requirements (cross-cutting must-haves like MFA / approval). Composable inline | ref | file. Granted on AIP-39 ACTION ids — implementations / TOOLs are decoupled from policy.",
+  "keywords": [
+    "agentproto",
+    "aip-38",
+    "policy",
+    "definePolicy",
+    "open-standard",
+    "agentic"
+  ],
+  "homepage": "https://agentproto.sh/docs/aip-38",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts",
+    "directory": "packages/policy"
+  },
+  "bugs": {
+    "url": "https://github.com/agentproto/ts/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./manifest": {
+      "types": "./dist/manifest/index.d.ts",
+      "import": "./dist/manifest/index.mjs",
+      "default": "./dist/manifest/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "zod": "^4.4.3",
+    "@agentproto/define-doctype": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@agentproto/tooling": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
+}