@aventara/access 0.0.0-stage → 0.1.0-rc.0

package/dist/generator/client.emitter.d.ts

@@ -0,0 +1,28 @@
+import type { AccessLock } from "../lock/lock-contract.js";
+import type { AccessDenyRule, AccessPolicies } from "../policies-contract.js";
+import type { ClientTranslator } from "./orm.translator.js";
+/** What a generated client is made from. */
+type ClientInput = {
+    /** The pulled policies file, checked and held to the lock. */
+    readonly policies: AccessPolicies;
+    /** The denies the org's pulled guardrails add to it, composed from both files' canonical forms (none when the lock pins none). */
+    readonly guardrailDenies: readonly AccessDenyRule[];
+    readonly lock: AccessLock;
+    readonly translator: ClientTranslator;
+    /** The command that regenerates the file, as the banner prints it. */
+    readonly command: string;
+    /** The `@aventara/access` version whose decisions the file carries. */
+    readonly version: string;
+    /** How `avAccess.ts` names `avAccess.internal.ts`: `./avAccess.internal.js`, as the project's tsconfig asks. */
+    readonly internalSpecifier: string;
+};
+/** The two files of a generated client. */
+type ClientFiles = {
+    /** `avAccess.ts`: `access` and the client's types. */
+    readonly client: string;
+    /** `avAccess.internal.ts`: the copied decisions and translator. */
+    readonly internal: string;
+};
+/** The generated client's two files. */
+export declare const emitClient: (input: ClientInput) => Promise<ClientFiles>;
+export {};

package/dist/generator/client.emitter.js

@@ -0,0 +1,411 @@
+// The generated client's text: two TypeScript files a service that does not run on
+// Aventara decides with, and nothing else of Access.
+//
+// - `avAccess.ts`, the file the service imports: the banner (generated, do not edit,
+//   the command that regenerates it, the pinned files), the namespace's Resource
+//   types, the pulled policies file as a constant with the guardrails' denies beside
+//   it, then `access`: `can`, `scopeOf`, `fieldsOf` (ORM-neutral, answering in
+//   Aventara's `where`), `checkBeacons` and the translator's functions. It exports
+//   `access` and the client's types only. When the rules read other namespaces'
+//   Resources as foreign, `access` decides nothing until
+//   `access.checkBeacons(reader, pins)` has passed at startup.
+// - `avAccess.internal.ts` beside it: the banner, then the copied decision modules
+//   and the translator's module, as they are. Their names stay exported there (the
+//   client imports them, and a declaration nothing reads would fail
+//   `noUnusedLocals`), and none of them is reachable from `avAccess.ts`.
+//
+// The texts are a function of their input alone: the same pulled files, translator,
+// command, package version and import spelling give the same bytes. Every list they
+// write is sorted, and the policies file is written in its canonical member order.
+import { foreignOwnersOf } from "../lock/lock.verifier.js";
+import { canonicalPolicies } from "../policies.hash.js";
+import { DECISION_MODULES, readCopiedModules, } from "./copied-modules.reader.js";
+import { namespaceFactsOf, propertyKey, } from "./namespace.facts.js";
+import { typescriptLiteral } from "./typescript-literal.writer.js";
+/** What the client file reads from the internal one, besides the translator's names. */
+const DECISION_IMPORTS = {
+    values: [
+        "beaconMismatch",
+        "beaconProblem",
+        "createDecider",
+        "grantsQuestionProblem",
+        "newTrace",
+    ],
+    types: [
+        "AccessAction",
+        "AccessBeaconPins",
+        "AccessBeaconReader",
+        "AccessCanQuestion",
+        "AccessDenyRule",
+        "AccessFields",
+        "AccessGrantsQuestion",
+        "AccessOrigin",
+        "AccessPolicies",
+        "AccessWhere",
+    ],
+};
+const RULE = "// ---------------------------------------------------------------------------";
+const section = (title) => `${RULE}\n// ${title}\n${RULE}`;
+/** What ends a comment's line: control characters and the line separators. */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: the characters it removes
+const BREAKS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g;
+/**
+ * Text from the project (a path, the command line) as a comment carries it: no line
+ * break, which would end a `//` comment, and no star followed by a slash, which
+ * would end a block comment, so nothing in it becomes code.
+ */
+const inComment = (text) => text.replace(BREAKS, " ").replace(/\*\//g, "*\\/");
+const banner = (input, file) => {
+    const { lock } = input;
+    const pins = [
+        `//     ${inComment(lock.policies.path)}  ${lock.policies.hash}`,
+        lock.guardrails === null
+            ? "//     (the lock pins no guardrails)"
+            : `//     ${inComment(lock.guardrails.path)}  ${lock.guardrails.hash}`,
+    ];
+    return [
+        "// biome-ignore-all format: generated output",
+        "// biome-ignore-all lint: generated output",
+        "/* eslint-disable */",
+        `// Generated by \`avaccess generate\` (@aventara/access ${input.version}). Do not edit this`,
+        "// file: change the rules where they are authored, push them, pull them, and",
+        "// regenerate it with",
+        "//",
+        `//     ${inComment(input.command)}`,
+        "//",
+        `// Namespace ${JSON.stringify(lock.namespace)}, from avAccess.lock.json:`,
+        ...pins,
+        "//",
+        ...(file === "client"
+            ? [
+                "// It decides from the pulled files with a copy of Access's decisions, kept in",
+                `// ${JSON.stringify(input.internalSpecifier)} beside it, and imports nothing else: no @aventara`,
+                `// package and no ${input.translator.title ?? "ORM"} module. The scope covers the queries you pass it`,
+                "// to, and only those.",
+            ]
+            : [
+                "// The copy of Access's decisions and translator the client beside it imports.",
+                "// Import `access` and its types from the client; nothing here is its API.",
+            ]),
+    ].join("\n");
+};
+const rowTypes = (namespace) => {
+    const known = new Set(namespace.resources.map((resource) => resource.name));
+    const rows = namespace.resources.map((resource) => {
+        const members = [
+            ...resource.fields.map((field) => `\t\treadonly ${propertyKey(field)}?: unknown;`),
+            // A relation to a Resource the file does not list (a trimmed model) is typed
+            // `unknown`: there is no row type to name.
+            ...resource.relations.map((relation) => `\t\treadonly ${propertyKey(relation.name)}?: ${!known.has(relation.target)
+                ? "unknown"
+                : relation.cardinality === "one"
+                    ? `ResourceRows[${JSON.stringify(relation.target)}] | null`
+                    : `readonly ResourceRows[${JSON.stringify(relation.target)}][]`};`),
+        ];
+        return `\treadonly ${propertyKey(resource.name)}: {\n${members.join("\n")}\n\t};`;
+    });
+    const fields = namespace.resources.map((resource) => `\treadonly ${propertyKey(resource.name)}: ${resource.fields.length === 0
+        ? "never"
+        : resource.fields.map((field) => JSON.stringify(field)).join(" | ")};`);
+    const names = namespace.resources
+        .map((resource) => JSON.stringify(resource.name))
+        .join(" | ");
+    return `/** The Resources the rules name: the namespace's own, and the ones they read from another namespace. */
+export type ResourceName = ${names === "" ? "never" : names};
+
+/**
+ * A row of each Resource as \`can\` reads it: any of its fields. A relation on it is
+ * accepted, so a row your ORM returns fits, and never read: a relation condition is
+ * asked through \`exists\`. Never put relation data a client sent on a row. The
+ * policies file names fields, not their types, so each is \`unknown\`.
+ */
+export type ResourceRows = {
+${rows.join("\n")}
+};
+
+/** The scalar fields of each Resource. */
+export type ResourceFields = {
+${fields.join("\n")}
+};`;
+};
+const API = `/** Who asks about one of the namespace's Resources, and through which layer. */
+export type QuestionOf<R extends ResourceName> = {
+	/** Your principal: an object the rules read (\`me.<path>\`, its \`claims\`), or \`null\` for anyone signed out. */
+	readonly principal: unknown;
+	/** The layer the request came through: \`"client"\` for a user's request, \`"agent"\` for an AI agent's, \`"application"\` for the service's own. */
+	readonly origin: AccessOrigin;
+	readonly resource: R;
+};
+
+/** \`can\`: without a row, whether the principal could ever do \`action\`; with one, whether it may on this row. */
+export type CanQuestionOf<R extends ResourceName> = QuestionOf<R> &
+	(
+		| {
+				readonly action: "update";
+				/**
+				 * On an update with a \`row\` only: what \`grantsOf\` answered about the row before
+				 * the update, asked before you wrote it. The grant that covers \`row\` must then be
+				 * one of these. With \`before\` too, each one's \`where\` is checked on it in memory;
+				 * a relation condition on it is not asked again, so it is the one the database
+				 * held before the update.
+				 */
+				readonly beforeGrants?: readonly string[];
+		  }
+		| {
+				readonly action: Exclude<AccessAction, "update">;
+				/** An update's only. */
+				readonly beforeGrants?: undefined;
+		  }
+	) & {
+	/**
+	 * The row a create inserts, an update leaves, or a read or delete is about. For an
+	 * update, limit the update itself to the rows \`scopeOf({ action: "update" })\`
+	 * returns.
+	 */
+	readonly row?: ResourceRows[R];
+	/**
+	 * On an update with a \`row\` only: the row as it was before the update. One update
+	 * grant must then cover both rows, its \`where\` this one and its \`where\` and
+	 * \`after\` the row the update leaves, so no update moves a row from the rows one
+	 * grant reaches to another's. Without it, \`can\` checks only the row the update
+	 * leaves.
+	 */
+	readonly before?: ResourceRows[R];
+	/** Whether a row of \`resource\` meets \`where\`, unscoped: what \`row\` does not carry is asked through it. */
+	readonly exists?: (
+		resource: ResourceName,
+		where: AccessWhere,
+	) => Promise<boolean>;
+};
+
+/** \`grantsOf\`: the update grants that cover \`row\`, the row you are about to update, as it is now. */
+export type GrantsQuestionOf<R extends ResourceName> = QuestionOf<R> & {
+	readonly action: "update";
+	readonly row: ResourceRows[R];
+	/** Whether a row of \`resource\` meets \`where\`, unscoped: what \`row\` does not carry is asked through it. */
+	readonly exists?: (
+		resource: ResourceName,
+		where: AccessWhere,
+	) => Promise<boolean>;
+};
+
+/** \`scopeOf\`: the rows the principal may read, update or delete. */
+export type ScopeQuestionOf<R extends ResourceName> = QuestionOf<R> & {
+	readonly action: "read" | "update" | "delete";
+};
+
+/** \`fieldsOf\`: the fields the principal may read, or write by one action. */
+export type FieldsQuestionOf<R extends ResourceName> = QuestionOf<R> &
+	(
+		| { readonly access: "read" }
+		| { readonly access: "write"; readonly action?: "create" | "update" }
+	);
+
+/** Whether the principal may do \`action\`; on \`row\` when one is given. Default deny, any grant allows, any deny wins. */
+const can = <R extends ResourceName>(
+	question: CanQuestionOf<R>,
+): boolean | Promise<boolean> =>
+	decider.can(question as AccessCanQuestion, newTrace());
+
+/**
+ * The update grants that cover \`row\` before you update it: opaque keys, no rule data.
+ * Ask it before the write, in the update's transaction, and pass the answer to \`can\`
+ * as \`beforeGrants\` with the row the update leaves.
+ */
+const grantsOf = <R extends ResourceName>(
+	question: GrantsQuestionOf<R>,
+): readonly string[] | Promise<readonly string[]> =>
+	decider.grantsOf(question as AccessGrantsQuestion);
+
+/** The rows the principal may \`action\`: every row (\`true\`), none (\`false\`), or the rows a \`where\` matches. */
+const scopeOf = <R extends ResourceName>(
+	question: ScopeQuestionOf<R>,
+): boolean | AccessWhere => decider.scopeOf(question);
+
+/** The fields usable on every reachable row (\`always\`), and those usable on some rows only (\`perRow\`, with their \`where\`). */
+const fieldsOf = <R extends ResourceName>(
+	question: FieldsQuestionOf<R>,
+): AccessFields => decider.fieldsOf(question);
+
+/**
+ * The startup check that this service reaches the database of each namespace whose
+ * Resources the rules read as foreign: its row in \`_aventara_beacon\`, read through
+ * \`reader\` (this service's own connection), hashes to its pin in \`pins\`, the pins of
+ * \`environment\` (avAccess.beacons.<environment>.json). Await it before the service
+ * takes requests: while the rules read another namespace, \`access\` answers nothing
+ * until it has passed, and nothing once a check has failed, for good (an error with
+ * \`code: "ACCESS_BEACON_MISMATCH"\`); calls run one after another. With none read it
+ * passes at once.
+ */
+const checkBeacons = (
+	reader: AccessBeaconReader,
+	pins: AccessBeaconPins,
+	environment: string,
+): Promise<void> => {
+	const run = async (): Promise<void> => {
+		if (foreignOwners.length === 0) {
+			return;
+		}
+		if (failed !== undefined) {
+			throw beaconMismatch(
+				\`a beacon check failed before, and the client stays shut: \${failed}\`,
+			);
+		}
+		const problem = await beaconProblem(
+			pulledPolicies.namespace ?? "",
+			foreignOwners,
+			pins,
+			environment,
+			reader,
+		);
+		if (problem !== undefined) {
+			failed = problem;
+			refusal = problem;
+			throw beaconMismatch(problem);
+		}
+		refusal = undefined;
+	};
+	const result = checking.then(run);
+	checking = result.catch(() => undefined);
+	return result;
+};`;
+const copied = (modules) => modules
+    .map((module) => `${section(`${module.path.replace(/^src\//, "")}, from @aventara/access`)}\n\n${module.text}`)
+    .join("\n");
+/** The client file's one import, and its re-export of the translator's types. */
+const imports = (input, ormPart) => {
+    const entries = [];
+    // Sorted by name, case aside (as Biome's import organizer sorts them), so a
+    // project that formats generated files finds nothing to change.
+    for (const part of [DECISION_IMPORTS, ormPart.imports]) {
+        for (const name of part.values) {
+            entries.push(`${name.toLowerCase()} ${name}`);
+        }
+        for (const name of part.types) {
+            entries.push(`${name.toLowerCase()} type ${name}`);
+        }
+    }
+    entries.sort();
+    let list = "";
+    for (const entry of entries) {
+        list += `\t${entry.slice(entry.indexOf(" ") + 1)},\n`;
+    }
+    const specifier = JSON.stringify(input.internalSpecifier);
+    const reexport = ormPart.exports.length === 0
+        ? ""
+        : `\n\nexport type { ${[...ormPart.exports].sort().join(", ")} } from ${specifier};`;
+    return `import {\n${list}} from ${specifier};${reexport}`;
+};
+/** The generated client's two files. */
+export const emitClient = async (input) => {
+    const modules = await readCopiedModules([
+        ...DECISION_MODULES,
+        ...input.translator.modules,
+    ]);
+    const namespace = namespaceFactsOf(input.lock.namespace, input.policies);
+    const ormPart = input.translator.clientPart(namespace);
+    const pulled = JSON.parse(canonicalPolicies(input.policies));
+    const members = [
+        "can",
+        "grantsOf",
+        "scopeOf",
+        "fieldsOf",
+        "checkBeacons",
+        ...ormPart.members,
+    ];
+    const internal = `${banner(input, "internal")}
+
+${copied(modules)}`;
+    const client = `${banner(input, "client")}
+
+${imports(input, ormPart)}
+
+${section(`Namespace ${JSON.stringify(namespace.namespace)}`)}
+
+${rowTypes(namespace)}
+
+/** The namespace's policies file, as \`avaccess pull\` wrote it (${inComment(input.lock.policies.path)}). */
+const pulledPolicies: AccessPolicies = ${typescriptLiteral(pulled)};
+
+/** The denies the org's guardrails add to the namespace's rules${input.lock.guardrails === null ? " (the lock pins none)" : ` (${inComment(input.lock.guardrails.path)})`}. */
+const guardrailDenies: readonly AccessDenyRule[] = ${typescriptLiteral(input.guardrailDenies)};
+
+/** The file the decisions run from: the namespace's rules, narrowed by the guardrails. */
+const policies: AccessPolicies = {
+	...pulledPolicies,
+	denies: [...pulledPolicies.denies, ...guardrailDenies],
+};
+
+/**
+ * The namespaces whose Resources the rules read as foreign: \`checkBeacons\` holds each
+ * one's row in \`_aventara_beacon\`, read through this service's connection, to its pin.
+ */
+const foreignOwners: readonly string[] = ${typescriptLiteral(foreignOwnersOf(input.policies))};
+
+/** Why the client answers nothing yet: \`undefined\` once the beacons have passed, or when the rules read no other namespace. */
+let refusal: string | undefined =
+	foreignOwners.length === 0
+		? undefined
+		: "the rules read other namespaces' Resources as foreign, and the beacons were not checked: \`await access.checkBeacons(reader, pins, environment)\` when the service starts, before it takes requests, with this environment's avAccess.beacons.<environment>.json";
+
+/** A failed beacon check: no later check opens the client again. */
+let failed: string | undefined;
+
+/** The beacon checks, one after another. */
+let checking: Promise<void> = Promise.resolve();
+
+const open = (): void => {
+	if (refusal !== undefined) {
+		throw beaconMismatch(refusal);
+	}
+};
+
+const decided = createDecider(policies);
+
+/** The decisions, each refused while the beacons the lock pins have not passed. */
+const decider: typeof decided = {
+	...decided,
+	can: (question, trace) => {
+		open();
+		return decided.can(question, trace);
+	},
+	grantsOf: (question) => {
+		open();
+		const problem = grantsQuestionProblem(question);
+		if (problem !== undefined) {
+			// Shaped as the engine's \`AccessError\`: the client imports nothing.
+			throw Object.assign(new Error(\`Aventara Access: \${problem}\`), {
+				name: "AccessError",
+				code: "ACCESS_QUESTION_INVALID" as const,
+			});
+		}
+		return decided.grantsOf(question);
+	},
+	scopeOf: (question) => {
+		open();
+		return decided.scopeOf(question);
+	},
+	fieldsOf: (question) => {
+		open();
+		return decided.fieldsOf(question);
+	},
+};
+
+${section("Decisions")}
+
+${API}
+
+${input.translator.title === undefined
+        ? ""
+        : `${section(`The ${input.translator.title} translator`)}
+
+${ormPart.text}
+`}/** Access's decisions for namespace ${JSON.stringify(namespace.namespace)}, ${input.translator.title === undefined
+        ? "answering in Aventara's `where`"
+        : `with the ${input.translator.title} translator`}. */
+export const access = {
+${members.map((member) => `\t${member},`).join("\n")}
+};
+`;
+    return { client, internal };
+};

package/dist/generator/copied-modules.reader.d.ts

@@ -0,0 +1,14 @@
+/** The decision modules every generated client carries, in an order that defines each name before it is read. */
+export declare const DECISION_MODULES: readonly string[];
+/** One module's text as the generated client carries it. */
+export type CopiedModule = {
+    /** Its path in the package, `src/scope.resolver.ts`. */
+    readonly path: string;
+    /** Its declarations: the text without its header comment and its imports. */
+    readonly text: string;
+};
+/**
+ * Reads `paths` (package paths, in order) as the generated client carries them.
+ * Throws when a module imports something that is not among `paths` before it.
+ */
+export declare const readCopiedModules: (paths: readonly string[]) => Promise<readonly CopiedModule[]>;

package/dist/generator/copied-modules.reader.js

@@ -0,0 +1,80 @@
+// The modules `avaccess generate` copies into a generated client, read from the
+// package's own TypeScript sources: the policies file's types, the principal fold,
+// Aventara's `where`, the row evaluator and the decisions, then the chosen ORM
+// translator's module. One source: the engine runs these modules, and the generated
+// client carries a copy of the same text, so the two decide alike.
+//
+// The package ships these sources beside `dist/` (its `files`), and this reader finds
+// them two directories up from itself, which is the package's root from `src/generator/`
+// and from `dist/generator/` alike. Each module's header comment and imports are left
+// out of the copy; an import of anything but another copied module is refused, so a
+// copied module can never pull a dependency into a service's generated file.
+import { readFile } from "node:fs/promises";
+/** The decision modules every generated client carries, in an order that defines each name before it is read. */
+export const DECISION_MODULES = [
+    "src/policies-contract.ts",
+    "src/scope.resolver.ts",
+    "src/aventara-where.translator.ts",
+    "src/predicate.evaluator.ts",
+    "src/canonical-json.writer.ts",
+    "src/sha256.digest.ts",
+    "src/policies.decider.ts",
+    "src/beacon/beacon.check.ts",
+];
+const IMPORT = /^import\s[^;]*?\sfrom\s+"([^"]+)";\n/gm;
+/** Any other way to load a module: a re-export, an import left over, `import()`, `require`. */
+const LEFT_IMPORT = /^\s*(?:import|export)\s[^;]*?\sfrom\s+"|^\s*import\s+"|\bimport\s*\(|\brequire\s*\(/m;
+/** The package's root: `src/generator/` and `dist/generator/` are both two levels below it. */
+const packageFile = (path) => decodeURIComponent(new URL(`../../${path}`, import.meta.url).pathname);
+/** The package path an import names, from the module at `from`; `undefined` when it leaves the package's sources. */
+const resolveImport = (from, specifier) => {
+    if (!specifier.startsWith("./") && !specifier.startsWith("../")) {
+        return undefined;
+    }
+    const parts = from.split("/").slice(0, -1);
+    for (const part of specifier.split("/")) {
+        if (part === "..") {
+            parts.pop();
+        }
+        else if (part !== ".") {
+            parts.push(part);
+        }
+    }
+    return parts.join("/").replace(/\.js$/, ".ts");
+};
+/** The header comment: the comment lines, and the blank lines, before the first line of code. */
+const withoutHeader = (text) => {
+    const lines = text.split("\n");
+    let first = 0;
+    while (first < lines.length &&
+        ((lines[first] ?? "").startsWith("//") || (lines[first] ?? "") === "")) {
+        first += 1;
+    }
+    return lines.slice(first).join("\n");
+};
+/**
+ * Reads `paths` (package paths, in order) as the generated client carries them.
+ * Throws when a module imports something that is not among `paths` before it.
+ */
+export const readCopiedModules = async (paths) => {
+    const modules = [];
+    for (const [index, path] of paths.entries()) {
+        const source = await readFile(packageFile(path), "utf8");
+        const earlier = new Set(paths.slice(0, index));
+        const text = withoutHeader(source)
+            .replace(IMPORT, (_statement, specifier) => {
+            const target = resolveImport(path, specifier);
+            if (target === undefined || !earlier.has(target)) {
+                throw new Error(`Aventara Access: ${path} imports ${JSON.stringify(specifier)}, and a module copied into a generated client imports only the copied modules before it (${[...earlier].join(", ") || "none"})`);
+            }
+            return "";
+        })
+            .replace(/^\n+/, "")
+            .replace(/\n+$/, "\n");
+        if (LEFT_IMPORT.test(text)) {
+            throw new Error(`Aventara Access: ${path} loads a module in a form the generator does not copy (a re-export, \`import()\` or \`require\`); a module copied into a generated client imports only the copied modules before it`);
+        }
+        modules.push({ path, text });
+    }
+    return modules;
+};

package/dist/generator/namespace.facts.d.ts

@@ -0,0 +1,28 @@
+import type { AccessPolicies } from "../policies-contract.js";
+/** One relation of a Resource, as the generated row types follow it. */
+type RelationFacts = {
+    readonly name: string;
+    readonly target: string;
+    readonly cardinality: "one" | "many";
+};
+/** One Resource of the namespace. */
+export type ResourceFacts = {
+    readonly name: string;
+    /** The namespace that owns it, when it is not this file's. */
+    readonly foreign: string | undefined;
+    /** Its scalar fields, sorted. */
+    readonly fields: readonly string[];
+    /** Its relations, sorted by name. */
+    readonly relations: readonly RelationFacts[];
+};
+/** The namespace a generated client decides for. */
+export type NamespaceFacts = {
+    readonly namespace: string;
+    /** Its Resources, sorted by name. */
+    readonly resources: readonly ResourceFacts[];
+};
+/** The facts of a pulled policies file. */
+export declare const namespaceFactsOf: (namespace: string, policies: AccessPolicies) => NamespaceFacts;
+/** A property key as TypeScript writes it: bare when it is an identifier, quoted otherwise. */
+export declare const propertyKey: (name: string) => string;
+export {};

package/dist/generator/namespace.facts.js

@@ -0,0 +1,32 @@
+// What a generated client says about its namespace, read from the pulled policies
+// file alone: its Resources (its own and the foreign ones its rules read), each
+// one's scalar fields and relations. The policies file names fields, never their
+// types, so neither does the generated client. Every list is sorted, so the client's
+// text depends on the file's content and never on its member order.
+const byCodeUnit = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+/** The facts of a pulled policies file. */
+export const namespaceFactsOf = (namespace, policies) => ({
+    namespace,
+    resources: Object.keys(policies.schema)
+        .sort(byCodeUnit)
+        .map((name) => {
+        const facts = policies.schema[name];
+        const relations = facts?.relations ?? {};
+        return {
+            name,
+            foreign: facts?.foreign,
+            fields: (facts?.fields ?? [])
+                .filter((field) => relations[field] === undefined)
+                .sort(byCodeUnit),
+            relations: Object.keys(relations)
+                .sort(byCodeUnit)
+                .map((relation) => ({
+                name: relation,
+                target: relations[relation]?.target ?? "",
+                cardinality: relations[relation]?.cardinality ?? "one",
+            })),
+        };
+    }),
+});
+/** A property key as TypeScript writes it: bare when it is an identifier, quoted otherwise. */
+export const propertyKey = (name) => /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);

package/dist/generator/orm.translator.d.ts

@@ -0,0 +1,48 @@
+import type { AccessSchema } from "../access-schema.js";
+import type { NamespaceFacts } from "./namespace.facts.js";
+/** What `avaccess schema` read: the `AccessSchema`, and what it left out and why. */
+export type OrmSchemaReading = {
+    readonly schema: AccessSchema;
+    readonly skipped: readonly string[];
+};
+/** The typed functions a translator adds to the generated client. */
+export type OrmClientPart = {
+    /** Their declarations, in TypeScript. */
+    readonly text: string;
+    /** The names they add to the generated `access` object, in order. */
+    readonly members: readonly string[];
+    /** What they read from the translator's copied module, in the internal file. */
+    readonly imports: {
+        readonly values: readonly string[];
+        readonly types: readonly string[];
+    };
+    /** The copied module's types the client file re-exports. */
+    readonly exports: readonly string[];
+};
+/** What `avaccess generate` reads of a translator: `none`, or an ORM's. */
+export type ClientTranslator = {
+    /** The `--orm` value: `none`, or the ORM and its major, `prisma7`. */
+    readonly orm: string;
+    /** The ORM's name and major as a reader says them, `Prisma 7`; `undefined` for `none`. */
+    readonly title: string | undefined;
+    /** The package paths of the translator's own modules, copied after the decisions. */
+    readonly modules: readonly string[];
+    /** The functions the generated client adds for this ORM. */
+    clientPart(namespace: NamespaceFacts): OrmClientPart;
+};
+/** One ORM's translator: its client part, and its schema reader. */
+export type OrmTranslator = ClientTranslator & {
+    readonly title: string;
+    /** The schema `avaccess schema` reads when `--schema` is not given, from the project's root. */
+    readonly defaultSchema: string;
+    /** `avaccess schema`: the ORM's schema at `path` as an `AccessSchema`. */
+    readSchema(path: string): Promise<OrmSchemaReading>;
+};
+/** Every ORM translator, by its `--orm` value: what `avaccess schema` reads with. */
+export declare const ORM_TRANSLATORS: {
+    readonly [orm: string]: OrmTranslator;
+};
+/** Every translator `avaccess generate` takes, by its `--orm` value. */
+export declare const CLIENT_TRANSLATORS: {
+    readonly [orm: string]: ClientTranslator;
+};

package/dist/generator/orm.translator.js

@@ -0,0 +1,29 @@
+// The translator seam: one translator per ORM major, chosen with `--orm`. A client
+// translator gives `avaccess generate` the modules it copies after the decisions and
+// the typed functions the generated client adds for its ORM; an ORM translator also
+// gives `avaccess schema` the reader that turns its ORM's schema into an
+// `AccessSchema`. The decisions stay ORM-neutral: they answer in Aventara's `where`,
+// and only a translator speaks an ORM's words.
+//
+// `none` (the default for `generate`, ruled 2026-10-23) adds nothing: the client
+// answers in the neutral `where` and names no ORM. Prisma 7 is the first ORM
+// (`prisma7`). Drizzle follows as `drizzle1` once Drizzle ORM v1 is stable.
+import { prisma7Translator } from "./prisma7/prisma7.translator.js";
+/** Every ORM translator, by its `--orm` value: what `avaccess schema` reads with. */
+export const ORM_TRANSLATORS = {
+    prisma7: prisma7Translator,
+};
+/** `--orm none`: a client that answers in the neutral `where` and names no ORM. */
+const NO_TRANSLATOR = {
+    orm: "none",
+    title: undefined,
+    modules: [],
+    clientPart: () => ({
+        text: "",
+        members: [],
+        imports: { values: [], types: [] },
+        exports: [],
+    }),
+};
+/** Every translator `avaccess generate` takes, by its `--orm` value. */
+export const CLIENT_TRANSLATORS = { none: NO_TRANSLATOR, ...ORM_TRANSLATORS };