permdock 0.6.0 → 0.8.0

package/dist/{casl-DjEDhTCP.js → casl-CHHoCldP.js}

@@ -1,6 +1,6 @@
 import { r as isRecord } from "./compact-CAf557ZB.js";
-import { t as applyFiles } from "./files-C5ZI27eV.js";
-import { n as isIdentifier, t as emitPolicyModule } from "./policy-module-CTlwMvLI.js";
+import { t as applyFiles } from "./files-B3AA05f1.js";
+import { n as isIdentifier, t as emitPolicyModule } from "./policy-module-xym9fnSq.js";
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 //#region src/cli/importers/casl.ts
@@ -32,7 +32,10 @@ function isStrings(value) {
 function split(item) {
 	return typeof item === "string" && item.includes(",") ? item.split(",") : item;
 }
-/** A rule in either shape: the object form, or `packRules`' `[action, subject, conditions, inverted, fields]`. */
+/**
+* A rule in either shape: the object form, or `packRules`' `[action, subject,
+* conditions, inverted, fields]`.
+*/
 function readRule(value) {
 	if (Array.isArray(value)) {
 		const [action, subject, conditions, inverted, fields] = value;
@@ -79,7 +82,10 @@ function readValue(value) {
 	}
 	return { unsupported: "a nested object value" };
 }
-/** The Mongo-query subset CASL conditions use, as a `where`; anything else is reported by name. */
+/**
+* The Mongo-query subset CASL conditions use, as a `where`; anything else is
+* reported by name.
+*/
 function readConditions(conditions) {
 	const parts = [];
 	for (const [key, value] of Object.entries(conditions)) {
@@ -143,11 +149,11 @@ function collectActions(rule, subjects, actionsBySubject) {
 	}
 }
 /**
-* CASL rules per role, as PermDock roles: `inverted` rules are denies,
-* `manage` and `all` expand to every action and subject the rules name, and
-* conditions in the portable Mongo-query subset become `where`. A deny whose
-* condition does not import keeps its effect without the condition, so the
-* import can only deny more, never less.
+* CASL rules per role, as PermDock roles: `inverted` rules are denies, `manage`
+* and `all` expand to every action and subject the rules name, and conditions
+* in the portable Mongo-query subset become `where`. A deny whose condition
+* does not import keeps its effect without the condition, so the import can
+* only deny more, never less.
 */
 function importCasl(rulesByRole) {
 	const parsed = [];
@@ -249,7 +255,10 @@ function importCasl(rulesByRole) {
 		skipped
 	};
 }
-/** `permdock casl import`: CASL rules per role into a `permissions` and `policy` module. */
+/**
+* `permdock casl import`: CASL rules per role into a `permissions` and `policy`
+* module.
+*/
 function runCaslImport(input) {
 	if (input.rules === void 0 || input.out === void 0) return {
 		code: 2,

package/dist/catalog/index.d.ts

@@ -1,8 +1,8 @@
-import { T as Policy, rr as Principal } from "../policy-types-n0uRTsW8.js";
-import { a as PolicyDocument } from "../hosted-BPk51-kX.js";
-import { a as CatalogDocument, c as CatalogOperation, d as CatalogRole, f as CatalogScope, h as CatalogValidity, i as CatalogDelegation, l as CatalogPermission, m as CatalogUsage, n as CatalogApproval, o as CatalogGrant, p as CatalogSupportAccess, r as CatalogBreakGlass, s as CatalogOAuthScope, t as CatalogActivation, u as CatalogResource } from "../types-Druu9wLM.js";
-import { a as CatalogFinding, i as CatalogEventData } from "../sink-4-eQIRWf.js";
-import { a as pushedPolicy, i as parsePushedPolicy, n as PushedGrant, r as PushedPolicy, t as PUSHED_POLICY_SCHEMA } from "../pushed-policy-DCW91KQU.js";
+import { T as Policy, a as ApprovalRequirement, sr as Principal } from "../policy-types-CCiDRZBH.js";
+import { c as checkHostedGrant, n as HostedGrantCheck, o as PolicyDocument } from "../hosted-Cmtxogd0.js";
+import { a as CatalogDocument, c as CatalogOperation, d as CatalogRole, f as CatalogScope, h as CatalogValidity, i as CatalogDelegation, l as CatalogPermission, m as CatalogUsage, n as CatalogApproval, o as CatalogGrant, p as CatalogSupportAccess, r as CatalogBreakGlass, s as CatalogOAuthScope, t as CatalogActivation, u as CatalogResource } from "../types-ZzRGoViD.js";
+import { a as CatalogFinding, i as CatalogEventData } from "../sink-Dvi7YZG_.js";
+import { a as pushedPolicy, i as parsePushedPolicy, n as PushedGrant, r as PushedPolicy, t as PUSHED_POLICY_SCHEMA } from "../pushed-policy-D1Eoi6NM.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/catalog/drift.d.ts
 /**
@@ -14,7 +14,10 @@ export declare function hostedGrantFindings(policy: Policy, document: PolicyDocu
 type CatalogDriftInput = {
   readonly previous: CatalogDocument;
   readonly next: CatalogDocument;
-  /** The policy rebuilt from `next` (`policyFromCatalog`), which live hosted grants must still pass. */
+  /**
+   * The policy rebuilt from `next` (`policyFromCatalog`), which live hosted
+   * grants must still pass.
+   */
   readonly policy: Policy;
   /** The live hosted grants; absent or `null` when the environment has none. */
   readonly document?: PolicyDocument | null;
@@ -26,12 +29,76 @@ type CatalogDriftInput = {
  */
 export declare function catalogDrift(input: CatalogDriftInput): CatalogEventData;
 //#endregion
+//#region src/catalog/hosted-options.d.ts
+/**
+ * The declared roles held at one scope: a scope name as declared, `resource`,
+ * or `global` for a role with no `on`.
+ */
+type HostedGrantRoleOption = {
+  readonly scope: string;
+  readonly roles: readonly string[];
+};
+type HostedGrantRelationOption = {
+  readonly relation: string;
+  /** Present when the grant may walk the resource's own parent chain. */
+  readonly through?: "parent";
+};
+/**
+ * What a hosted grant on one hostable permission may say; any other value is
+ * dropped by `mergeHostedGrants`.
+ */
+type HostedGrantOption = {
+  readonly permission: string;
+  readonly resource: string;
+  readonly scope: string;
+  readonly effects: readonly ("allow" | "deny")[];
+  readonly grantees: {
+    readonly roles: readonly HostedGrantRoleOption[];
+    readonly plans: readonly string[];
+    readonly relations: readonly HostedGrantRelationOption[];
+  };
+  readonly approval: {
+    /**
+     * `true` when a code allow carries an approval: a hosted allow without one
+     * at least as strict is dropped (`weaker-approval`).
+     */
+    readonly required: boolean;
+    /** The approvals code allows carry; a hosted allow must meet each. */
+    readonly meets: readonly ("human" | ApprovalRequirement)[];
+    /**
+     * `human` is `approval: 'human'`; `any` is the object form, any one
+     * approver per approval. `all` and `sequential` stages are never accepted.
+     */
+    readonly modes: readonly ("human" | "any")[];
+    /** The object-form fields a hosted approval may set. */
+    readonly fields: readonly string[];
+    /** The grantee kinds `by` and `escalation.to` may name. */
+    readonly approvers: readonly ("role" | "plan" | "authenticated")[];
+  };
+  readonly conditions: {
+    /** `where` and `check` accept the portable condition subset only. */
+    readonly portable: true;
+    /**
+     * The resource's top-level fields, from its JSON Schema; `null` when the
+     * schema exposes none.
+     */
+    readonly fields: readonly string[] | null;
+  };
+};
+/**
+ * What a hosted grant may say on each permission the policy marks `hostable`,
+ * in `hostable` order: the grantees, approval forms and conditions
+ * `mergeHostedGrants` accepts. For an authoring form; every grant it builds
+ * from these still goes through `checkHostedGrant`.
+ */
+export declare function hostedGrantOptions(policy: Policy): readonly HostedGrantOption[];
+//#endregion
 //#region src/catalog/json-schema-validator.d.ts
 /**
  * A Standard Schema that validates against a catalog resource's JSON Schema.
  * `null` (no JSON Schema in the catalog) gives `undefined`. A schema that uses
- * a keyword outside the supported subset rejects every value, so a hosted
- * check never validates less than the code did.
+ * a keyword outside the supported subset rejects every value, so a hosted check
+ * never validates less than the code did.
  */
 export declare function resourceSchemaFromJson(json: unknown): StandardSchemaV1 | undefined;
 //#endregion
@@ -46,19 +113,33 @@ type OperationCatalog = {
 };
 /**
  * Operations, matched by name, whose `meta.risk` rose or whose permission
- * stopped requiring approval between two catalogs. A new or removed
- * operation is not a finding.
+ * stopped requiring approval between two catalogs. A new or removed operation
+ * is not a finding.
  */
 export declare function operationFindings(previous: OperationCatalog, next: OperationCatalog): readonly CatalogFinding[];
 //#endregion
+//#region src/catalog/references.d.ts
+/** A permission `meta` field `parseCatalog` can require. */
+type CatalogMetaField = "title" | "risk" | "effects";
+//#endregion
 //#region src/catalog/parse.d.ts
+type ParseCatalogOptions = {
+  /** Permission `meta` fields every permission must carry; none by default. */
+  readonly requireMeta?: readonly CatalogMetaField[];
+};
+/**
+ * Reads a `permissions.catalog.json` document (parsed, or the JSON text),
+ * validates it against `schemas/catalog-v1.json`, then checks its references:
+ * role scopes, the permission keys operations, grants, delegations and OAuth
+ * scopes name, unique keys, and `requireMeta`. Returns a deep-frozen copy built
+ * from own keys; throws `PermDockValidationError` with every issue, each with
+ * its `path`.
+ */
+export declare function parseCatalog(json: unknown, options?: ParseCatalogOptions): CatalogDocument;
 /**
- * Reads a `permissions.catalog.json` document (parsed, or the JSON text) and
- * validates it against `schemas/catalog-v1.json`. Returns a deep-frozen copy
- * built from own keys; throws `PermDockValidationError` with every issue.
+ * Keys of the permissions the catalog marks `rowConditions: true`: the SQL
+ * helpers alone cannot enforce them.
  */
-export declare function parseCatalog(json: unknown): CatalogDocument;
-/** Keys of the permissions the catalog marks `rowConditions: true`: the SQL helpers alone cannot enforce them. */
 export declare function rowConditionKeys(catalog: CatalogDocument): ReadonlySet<string>;
 //#endregion
 //#region src/catalog/policy-from-catalog.d.ts
@@ -70,15 +151,15 @@ type PolicyFromCatalogOptions<TUser = unknown> = {
  * Rebuilds an evaluable `Policy` from a catalog (`permissions.catalog.json`)
  * and the policy `permdock cloud push` sent with it, for a service that holds
  * no application code: the hosted AuthZEN endpoint or a `mergeHostedGrants`
- * pre-check. Throws `PermDockValidationError` when either input is malformed
- * or the two disagree.
+ * pre-check. Throws `PermDockValidationError` when either input is malformed or
+ * the two disagree.
  *
- * What only code can answer fails closed: an allow whose condition is a
- * closure never grants and such a deny always applies; a resource schema
- * keyword outside the supported JSON Schema subset rejects every value; a
- * support role has no one who may consent. Grant levels and OAuth scopes
- * are not in a catalog, so the rebuilt policy has none.
+ * What only code can answer fails closed: an allow whose condition is a closure
+ * never grants and such a deny always applies; a resource schema keyword
+ * outside the supported JSON Schema subset rejects every value; a support role
+ * has no one who may consent. Grant levels and OAuth scopes are not in a
+ * catalog, so the rebuilt policy has none.
  */
 export declare function policyFromCatalog<TUser = unknown>(catalogInput: unknown, pushedInput: unknown, options?: PolicyFromCatalogOptions<TUser>): Policy<TUser>;
 //#endregion
-export { type CatalogActivation, type CatalogApproval, type CatalogBreakGlass, type CatalogDelegation, type CatalogDocument, type CatalogDriftInput, type CatalogGrant, type CatalogOAuthScope, type CatalogOperation, type CatalogPermission, type CatalogResource, type CatalogRole, type CatalogScope, type CatalogSupportAccess, type CatalogUsage, type CatalogValidity, PUSHED_POLICY_SCHEMA, type PolicyFromCatalogOptions, type PushedGrant, type PushedPolicy, parsePushedPolicy, pushedPolicy };
+export { type CatalogActivation, type CatalogApproval, type CatalogBreakGlass, type CatalogDelegation, type CatalogDocument, type CatalogDriftInput, type CatalogGrant, type CatalogMetaField, type CatalogOAuthScope, type CatalogOperation, type CatalogPermission, type CatalogResource, type CatalogRole, type CatalogScope, type CatalogSupportAccess, type CatalogUsage, type CatalogValidity, type HostedGrantCheck, type HostedGrantOption, type HostedGrantRelationOption, type HostedGrantRoleOption, PUSHED_POLICY_SCHEMA, type ParseCatalogOptions, type PolicyFromCatalogOptions, type PushedGrant, type PushedPolicy, checkHostedGrant, parsePushedPolicy, pushedPolicy };

package/dist/catalog/index.js

@@ -1,11 +1,19 @@
-import { n as freezeDeep } from "../freeze-CrU8nQeX.js";
-import { t as hostedGrantDrops } from "../hosted-B46-5LYE.js";
-import { n as rowConditionKeys, t as parseCatalog } from "../parse-Cxq0WxrA.js";
-import { t as operationFindings } from "../operation-findings-DgATDpvh.js";
-import { n as resourceSchemaFromJson, t as policyFromCatalog } from "../policy-from-catalog-C2gMa2Dj.js";
-import { n as parsePushedPolicy, r as pushedPolicy, t as PUSHED_POLICY_SCHEMA } from "../pushed-policy-CqtxkV4G.js";
+import { r as isRecord } from "../compact-CAf557ZB.js";
+import { n as freezeDeep } from "../freeze-jjan0lCv.js";
+import { a as getResource, n as findPermission } from "../permission-registry-B8tYxPIt.js";
+import { d as isSelfParented } from "../resource-relations-8-pCScBO.js";
+import { _ as listPlans, m as findRole } from "../grantee-Dke-9rd1.js";
+import { n as declaredRoleNames } from "../policy-CLQ8__GF.js";
+import { i as hostedGrantDrops, n as codeApprovals, r as declaredGrantee, t as checkHostedGrant } from "../hosted-D0IzESu_.js";
+import { n as rowConditionKeys, t as parseCatalog } from "../parse-1_ZheTW5.js";
+import { t as operationFindings } from "../operation-findings-CXtFzlKJ.js";
+import { n as resourceSchemaFromJson, t as policyFromCatalog } from "../policy-from-catalog-CJgOm6aq.js";
+import { n as parsePushedPolicy, r as pushedPolicy, t as PUSHED_POLICY_SCHEMA } from "../pushed-policy-ITwYKvvH.js";
 //#region src/catalog/drift.ts
-/** The finding a drop reason becomes; `null` for a reason the catalog did not cause. */
+/**
+* The finding a drop reason becomes; `null` for a reason the catalog did not
+* cause.
+*/
 function findingCode(reason) {
 	switch (reason) {
 		case "unknown-permission": return "permission-removed";
@@ -48,4 +56,105 @@ function catalogDrift(input) {
 	});
 }
 //#endregion
-export { PUSHED_POLICY_SCHEMA, catalogDrift, hostedGrantFindings, operationFindings, parseCatalog, parsePushedPolicy, policyFromCatalog, pushedPolicy, resourceSchemaFromJson, rowConditionKeys };
+//#region src/catalog/hosted-options.ts
+function roleScope(policy, name) {
+	const on = policy.rolesByName.get(name)?.on ?? findRole(policy.vocabulary.roles, name)?.on;
+	if (on === void 0) return "global";
+	return typeof on === "string" ? on : "resource";
+}
+function schemaFields(node) {
+	const output = (node?.schema)?.["~standard"]?.jsonSchema?.output;
+	if (typeof output !== "function") return null;
+	try {
+		const json = output({ target: "draft-2020-12" });
+		const properties = isRecord(json) ? json["properties"] : void 0;
+		return isRecord(properties) ? Object.keys(properties).toSorted() : null;
+	} catch {
+		return null;
+	}
+}
+function optionFor(policy, key) {
+	const leaf = findPermission(policy.permissions, key);
+	if (leaf === void 0) return null;
+	const accepts = (grantee) => declaredGrantee(policy, grantee, leaf.resource);
+	const byScope = /* @__PURE__ */ new Map();
+	for (const role of declaredRoleNames(policy)) {
+		const scope = roleScope(policy, role);
+		if (accepts({
+			kind: "role",
+			role,
+			scope
+		})) byScope.set(scope, [...byScope.get(scope) ?? [], role]);
+	}
+	const plans = listPlans(policy.vocabulary.plans).map((plan) => plan.key).filter((plan) => accepts({
+		kind: "plan",
+		plan
+	}));
+	const node = getResource(policy.permissions, leaf.resource);
+	const relations = Object.keys(node?.relations ?? {}).toSorted().flatMap((relation) => {
+		const direct = {
+			kind: "relation",
+			resource: leaf.resource,
+			relation
+		};
+		if (!accepts(direct)) return [];
+		return isSelfParented(node) && accepts({
+			...direct,
+			through: "parent"
+		}) ? [{
+			relation,
+			through: "parent"
+		}] : [{ relation }];
+	});
+	const meets = codeApprovals(policy, key).filter((approval) => approval !== void 0);
+	return {
+		permission: key,
+		resource: leaf.resource,
+		scope: leaf.scope,
+		effects: ["allow", "deny"],
+		grantees: {
+			roles: [...byScope].map(([scope, roles]) => ({
+				scope,
+				roles
+			})),
+			plans,
+			relations
+		},
+		approval: {
+			required: meets.length > 0,
+			meets,
+			modes: ["human", "any"],
+			fields: [
+				"by",
+				"distinct",
+				"escalation",
+				"quorum",
+				...node?.version === void 0 ? [] : ["staleOn"],
+				"ttl"
+			],
+			approvers: [
+				...byScope.size > 0 ? ["role"] : [],
+				...plans.length > 0 ? ["plan"] : [],
+				"authenticated"
+			]
+		},
+		conditions: {
+			portable: true,
+			fields: schemaFields(node)
+		}
+	};
+}
+/**
+* What a hosted grant may say on each permission the policy marks `hostable`,
+* in `hostable` order: the grantees, approval forms and conditions
+* `mergeHostedGrants` accepts. For an authoring form; every grant it builds
+* from these still goes through `checkHostedGrant`.
+*/
+function hostedGrantOptions(policy) {
+	return freezeDeep(policy.hostable.flatMap((key) => {
+		const option = optionFor(policy, key);
+		return option === null ? [] : [option];
+	}));
+}
+//#endregion
+export { PUSHED_POLICY_SCHEMA, catalogDrift, checkHostedGrant, hostedGrantFindings, hostedGrantOptions, operationFindings, parseCatalog, parsePushedPolicy, policyFromCatalog, pushedPolicy, resourceSchemaFromJson, rowConditionKeys };

package/dist/{catalog-HD2gf5mY.js → catalog-BFpz2EmT.js}

@@ -1,9 +1,10 @@
 import { r as isRecord } from "./compact-CAf557ZB.js";
-import { r as listSourceFiles, t as defaultSrcPath } from "./files-D_JIzUrP.js";
-import { a as formatCatalogJson, i as catalogSchemaDocument, o as formatCatalogMarkdown, t as buildCatalog } from "./catalog-doc-Cdn7-0pQ.js";
-import { a as loadModule, i as loadConfiguredPolicy, r as leavesOf, s as pickNamed, t as asPermissionTree } from "./load-DFS_ry0W.js";
-import { a as loadConfiguredOperations, i as scanSources, r as runCollect } from "./collect-mLTY4nwb.js";
-import { n as fileSummary, t as applyFiles } from "./files-C5ZI27eV.js";
+import { r as listSourceFiles, t as defaultSrcPath } from "./files-BSjrtIHw.js";
+import { a as catalogSchemaDocument, n as catalogForCompare, o as formatCatalogJson, r as catalogForDrift, s as formatCatalogMarkdown, t as buildCatalog } from "./catalog-doc-DjMKzJp9.js";
+import { a as loadModule, i as loadConfiguredPolicy, r as leavesOf, s as pickNamed, t as asPermissionTree } from "./load-DjSU5KXO.js";
+import { t as loadConfiguredOperations } from "./catalog-operations-Dadrl7Z-.js";
+import { i as scanSources, r as runCollect } from "./collect-B7ZFAJU3.js";
+import { n as fileSummary, t as applyFiles } from "./files-B3AA05f1.js";
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 //#region src/cli/catalog.ts
@@ -14,18 +15,7 @@ async function runCatalog(input) {
 	};
 	const from = input.from ?? input.config.permissions;
 	let document;
-	if (from !== void 0) {
-		const abs = resolve(input.cwd, from);
-		if (!existsSync(abs)) return {
-			code: 2,
-			output: `PermDock CLI: module not found: ${from}`
-		};
-		const tree = asPermissionTree(pickNamed(await loadModule(abs), ["permissions"]));
-		const srcPath = input.config.collect?.srcPath ?? defaultSrcPath();
-		const files = listSourceFiles(input.cwd, srcPath);
-		const scan = scanSources(input.cwd, files, new Set(leavesOf(tree).map((leaf) => leaf.key)));
-		document = buildCatalog(tree, scan, input.now.toISOString(), await loadConfiguredPolicy(input.cwd, input.config.policy), await loadConfiguredOperations(input.cwd, input.config.operations));
-	} else {
+	if (from === void 0) {
 		const collected = await runCollect({
 			cwd: input.cwd,
 			config: input.config,
@@ -39,6 +29,17 @@ async function runCatalog(input) {
 			output: collected.message
 		};
 		document = collected.document;
+	} else {
+		const abs = resolve(input.cwd, from);
+		if (!existsSync(abs)) return {
+			code: 2,
+			output: `PermDock CLI: module not found: ${from}`
+		};
+		const tree = asPermissionTree(pickNamed(await loadModule(abs), ["permissions"]));
+		const srcPath = input.config.collect?.srcPath ?? defaultSrcPath();
+		const files = listSourceFiles(input.cwd, srcPath);
+		const scan = scanSources(input.cwd, files, new Set(leavesOf(tree).map((leaf) => leaf.key)));
+		document = buildCatalog(tree, scan, input.now.toISOString(), await loadConfiguredPolicy(input.cwd, input.config.policy), await loadConfiguredOperations(input.cwd, input.config.operations));
 	}
 	const filtered = input.include.length === 0 ? document : {
 		...document,
@@ -53,18 +54,30 @@ async function runCatalog(input) {
 		output: formatCatalogJson(filtered)
 	};
 }
-/** The comparable form of a catalog file: without the fields every run changes. */
+/**
+* The comparable forms of a catalog file: without the fields every run changes,
+* then also without `usages[].line`.
+*/
 function comparable(text) {
 	try {
 		const parsed = JSON.parse(text);
 		if (isRecord(parsed)) {
-			const { generatedAt: _generatedAt, generator: _generator, ...rest } = parsed;
-			return JSON.stringify(rest);
+			const doc = parsed;
+			return {
+				full: catalogForCompare(doc),
+				drift: catalogForDrift(doc)
+			};
 		}
 	} catch {}
-	return text;
+	return {
+		full: text,
+		drift: text
+	};
 }
-/** `catalog --out`: writes the export, or with `--check` exits 1 when the file differs. */
+/**
+* `catalog --out`: writes the export, or with `--check` exits 1 when the file
+* differs by more than usage line numbers.
+*/
 function catalogFile(cwd, out, text, check) {
 	if (check) {
 		const path = resolve(cwd, out);
@@ -76,13 +89,31 @@ function catalogFile(cwd, out, text, check) {
 				stale: true
 			}
 		};
-		const stale = comparable(readFileSync(path, "utf8")) !== comparable(text);
+		const onDisk = comparable(readFileSync(path, "utf8"));
+		const generated = comparable(text);
+		if (onDisk.full === generated.full) return {
+			code: 0,
+			output: `${out} is up to date`,
+			data: {
+				out,
+				stale: false
+			}
+		};
+		if (onDisk.drift === generated.drift) return {
+			code: 0,
+			output: `catalog usages moved (lines only): ${out}; run permdock collect to refresh`,
+			data: {
+				out,
+				stale: false,
+				positionsMoved: true
+			}
+		};
 		return {
-			code: stale ? 1 : 0,
-			output: stale ? `catalog stale: ${out}` : `${out} is up to date`,
+			code: 1,
+			output: `catalog stale: ${out}`,
 			data: {
 				out,
-				stale
+				stale: true
 			}
 		};
 	}

package/dist/{catalog-DZVbrF-z.js → catalog-DCspHDc8.js}

@@ -1,6 +1,6 @@
-import { c as missingInput } from "./errors-CWTY6uih.js";
+import { c as missingInput } from "./errors-Vpu6rKHl.js";
 import { t as defineLeaf } from "./command-L8EstFNm.js";
-import { c as given, l as outFlag, t as checkFlag, u as permissionsFlag } from "./flags-C3DktBDY.js";
+import { c as given, l as outFlag, t as checkFlag, u as permissionsFlag } from "./flags-DXjoTVbS.js";
 //#region src/cli/commands/catalog.ts
 const RUN_FORMAT = {
 	catalog: "json",
@@ -30,7 +30,7 @@ const catalog = defineLeaf({
 		...checkFlag
 	},
 	async run(ctx, { flags }) {
-		const { catalogFile, runCatalog } = await import("./catalog-BoWglDPI.js");
+		const { catalogFile, runCatalog } = await import("./catalog-mRQQQhNK.js");
 		const result = await runCatalog({
 			cwd: ctx.cwd,
 			config: ctx.config,

package/dist/{catalog-doc-Cdn7-0pQ.js → catalog-doc-DjMKzJp9.js}

@@ -1,19 +1,24 @@
-import { a as getResource, c as listPermissions, h as formerKeys } from "./permission-registry-Br4jSNVi.js";
-import { t as canonicalJson } from "./canonical-json-BC8_nMTw.js";
-import { m as findRole, v as listRoles } from "./grantee-hxrUsbpM.js";
-import { i as wireValidity } from "./validity-CZ7-y0Cj.js";
-import { t as byCodePoint } from "./compare-pfyVnBjE.js";
-import { t as catalogFingerprint } from "./catalog-fingerprint-CCP0-yQS.js";
-import { t as catalogSchema } from "./schema-B4v0Qrac.js";
-import { t as policyRowConditionKeys } from "./row-conditions-h2HythXQ.js";
-import { c as generatorBanner, n as CATALOG_SCHEMA } from "./version-CEbQ5UeM.js";
+import { r as isRecord } from "./compact-CAf557ZB.js";
+import { a as getResource, c as listPermissions, h as formerKeys } from "./permission-registry-B8tYxPIt.js";
+import { t as canonicalJson } from "./canonical-json-DwilZ1iB.js";
+import { m as findRole, v as listRoles } from "./grantee-Dke-9rd1.js";
+import { i as wireValidity } from "./validity-Buc7w8E9.js";
+import { t as byCodePoint } from "./compare-DTfyUunF.js";
+import { t as catalogFingerprint } from "./catalog-fingerprint-e6aCWosn.js";
+import { t as catalogSchema } from "./schema-BOJjqlWL.js";
+import { t as policyRowConditionKeys } from "./row-conditions-BAGHOmVq.js";
+import { c as generatorBanner, n as CATALOG_SCHEMA } from "./version-DMQ0dnN5.js";
 //#region src/cli/catalog-doc.ts
 function leafLevels(tree, leaf) {
 	if (leaf.kind !== "instance") return;
 	const names = Object.keys({ ...getResource(tree, leaf.resource)?.levels });
 	return names.length === 0 ? void 0 : names;
 }
-/** With `policy`, permissions carry `hostable` and a known `rowConditions` (without, it is `true`), and roles carry `on`, `assignable` and their ownership rules. */
+/**
+* With `policy`, permissions carry `hostable` and a known `rowConditions`
+* (without, it is `true`), and roles carry `on`, `assignable` and their
+* ownership rules.
+*/
 function buildCatalog(tree, scan, generatedAt, policy, operations) {
 	const hostable = new Set(policy?.hostable ?? []);
 	const rowConditions = policy === void 0 ? void 0 : policyRowConditionKeys(policy);
@@ -50,6 +55,7 @@ function buildCatalog(tree, scan, generatedAt, policy, operations) {
 			usages: scan.usages[leaf.key] ?? [],
 			renamedFrom: formerKeys(leaf).length === 0 ? void 0 : formerKeys(leaf),
 			levels: leafLevels(tree, leaf),
+			orderedLevels: leaf.kind === "instance" && getResource(tree, leaf.resource)?.orderedLevels === true ? true : void 0,
 			hostable: hostable.has(leaf.key) ? true : void 0,
 			rowConditions: rowConditions?.has(leaf.key) ?? true,
 			approvals: approvals.get(leaf.key),
@@ -94,8 +100,8 @@ function catalogApproval(approval) {
 /**
 * Every code grant in canonical order: by permission, allows before denies,
 * then by role (top-level grants last) and finally by canonical JSON, so two
-* catalogs of the same policy list the same grants in the same order
-* whatever the declaration order was.
+* catalogs of the same policy list the same grants in the same order whatever
+* the declaration order was.
 */
 function catalogGrant(grant) {
 	const limit = grant.limit === void 0 ? void 0 : withDefined({
@@ -124,7 +130,10 @@ function catalogGrant(grant) {
 		})
 	};
 }
-/** The sort key of a catalog grant: permission, allows first, role (top-level last), then the canonical JSON. */
+/**
+* The sort key of a catalog grant: permission, allows first, role (top-level
+* last), then the canonical JSON.
+*/
 function catalogGrantKey(grant) {
 	return [
 		grant.permission,
@@ -144,7 +153,10 @@ function catalogGrants(policy) {
 		return left < right ? -1 : left > right ? 1 : 0;
 	});
 }
-/** Every policy delegation, sorted by canonical JSON so declaration order does not matter. */
+/**
+* Every policy delegation, sorted by canonical JSON so declaration order does
+* not matter.
+*/
 function catalogDelegations(policy) {
 	return (policy.delegations ?? []).map((delegation) => withDefined({
 		from: delegation.from,
@@ -163,7 +175,10 @@ function catalogOAuthScopes(declared) {
 		permissions: [...new Set(entry.permissions)].toSorted(byCodePoint)
 	})).toSorted((a, b) => byCodePoint(a.scope, b.scope));
 }
-/** Per permission key, the distinct approvals the code allows require, in policy order. */
+/**
+* Per permission key, the distinct approvals the code allows require, in policy
+* order.
+*/
 function codeApprovals(policy) {
 	const out = /* @__PURE__ */ new Map();
 	const seen = /* @__PURE__ */ new Set();
@@ -292,6 +307,28 @@ function catalogForCompare(doc) {
 	const { generatedAt: _generatedAt, generator: _generator, ...rest } = doc;
 	return `${JSON.stringify(rest, null, 2)}\n`;
 }
+/**
+* `catalogForCompare` without `usages[].line`: an edit above a call site moves
+* its line without changing the contract, so `--check` does not fail on it.
+*/
+function catalogForDrift(doc) {
+	const permissions = doc.permissions;
+	if (!Array.isArray(permissions)) return catalogForCompare(doc);
+	const { generatedAt: _generatedAt, generator: _generator, ...rest } = doc;
+	const stripped = {
+		...rest,
+		permissions: permissions.map((permission) => {
+			if (!isRecord(permission) || !Array.isArray(permission["usages"])) return permission;
+			const usages = permission["usages"].map((usage) => {
+				if (!isRecord(usage)) return usage;
+				const { line: _line, ...position } = usage;
+				return position;
+			});
+			return Object.assign({}, permission, { usages });
+		})
+	};
+	return `${JSON.stringify(stripped, null, 2)}\n`;
+}
 function formatCatalogMarkdown(doc) {
 	const lines = ["# Permissions", ""];
 	const byResource = /* @__PURE__ */ new Map();
@@ -312,4 +349,4 @@ function catalogSchemaDocument() {
 	return catalogSchema;
 }
 //#endregion
-export { formatCatalogJson as a, catalogSchemaDocument as i, catalogForCompare as n, formatCatalogMarkdown as o, catalogOAuthScopes as r, jsonSchemaOf as s, buildCatalog as t };
+export { catalogSchemaDocument as a, jsonSchemaOf as c, catalogOAuthScopes as i, catalogForCompare as n, formatCatalogJson as o, catalogForDrift as r, formatCatalogMarkdown as s, buildCatalog as t };