@astrale-os/sdk 0.5.0-beta.8 → 0.5.0-beta.80

package/dist/application/query/execution/execute.js

@@ -0,0 +1,74 @@
+import { COLLECTION_QUERY_LIMITS } from '../collection/limits.js';
+import { compileCollectionUnion, partitionCollectionUnion } from '../collection/union.js';
+import { createQueryComposition, executeQueryPlan } from '../composite/index.js';
+import { realizeQuery } from '../define.js';
+import { queryFailure } from '../failure.js';
+import { completeSelection, queryResult } from '../single/index.js';
+import { executePages } from './pages.js';
+export async function executeQuery(client, domain, query, input) {
+    if (client === null || typeof client !== 'object' || typeof client.query !== 'function') {
+        throw new TypeError('Query execution requires a Client query capability.');
+    }
+    const execute = (ast, options) => client.query(ast, { ...options, expected: domain.closure });
+    const operation = realizeQuery(query, domain);
+    try {
+        if (operation.kind === 'single') {
+            return (await runSingle(execute, operation, input));
+        }
+        const prepared = operation.prepare?.(input) ?? input;
+        const session = createQueryComposition();
+        const composed = operation.compose(session.builder, prepared);
+        if (isPromiseLike(composed))
+            throw new TypeError('Composite Query composition must be synchronous.');
+        const plan = session.close(composed);
+        const result = await executeQueryPlan(plan, (child, childInput) => runSingle(execute, realizeSingle(child, domain), childInput), (definitions, outputPath) => runCollectionUnion(execute, domain, definitions, outputPath));
+        return (operation.project === undefined ? result : operation.project(result, prepared));
+    }
+    catch (cause) {
+        const expected = queryFailure(cause);
+        if (operation.reject !== undefined && expected !== undefined) {
+            return operation.reject(expected);
+        }
+        throw cause;
+    }
+}
+async function runCollectionUnion(execute, domain, definitions, outputPath) {
+    const compiled = compileCollectionUnion(domain, definitions, outputPath);
+    const pages = await executePages(execute, compiled.ast, { size: COLLECTION_QUERY_LIMITS.pageSize }, { maximumPages: COLLECTION_QUERY_LIMITS.maximumPages });
+    const context = outputPath.length === 0 ? 'collection union' : outputPath.join('.');
+    const values = compiled.kind === 'node'
+        ? queryResult.completeNodeValues(pages, context)
+        : Object.freeze(pages.flatMap((page) => queryResult.edgeItems(page, context).map((item) => {
+            if (item.edge.kind !== 'value') {
+                throw new TypeError(`${context} must project Edge values.`);
+            }
+            return item.edge.value;
+        })));
+    return partitionCollectionUnion(domain, compiled, values);
+}
+function realizeSingle(definition, domain) {
+    const operation = realizeQuery(definition, domain);
+    if (operation.kind !== 'single')
+        throw new TypeError('Composite Query leaves must be single.');
+    return operation;
+}
+async function runSingle(execute, definition, input) {
+    const prepared = definition.prepare?.(input) ?? input;
+    const ast = definition.build(prepared);
+    if (definition.pagination !== undefined) {
+        const collected = await executePages(execute, ast, definition.page, definition.pagination);
+        return definition.project(collected, prepared, {
+            ast,
+            complete: completeSelection(collected),
+        });
+    }
+    const response = await execute(ast, { page: definition.page });
+    return definition.project === undefined
+        ? response.result
+        : definition.project(response.result, prepared, { ast });
+}
+function isPromiseLike(input) {
+    return (input !== null &&
+        (typeof input === 'object' || typeof input === 'function') &&
+        typeof input.then === 'function');
+}

package/dist/application/query/execution/executor.d.ts

@@ -0,0 +1,14 @@
+import type { Domain, schema } from '../../../platform/schema/index.js';
+import type { QueryDefinition } from '../query.js';
+import type { QueryClient } from './execute.js';
+/** Invocation-bound executor for authored Query definitions. */
+export interface QueryExecutor<DomainValue extends Domain = Domain> {
+    <Output>(query: QueryDefinition<DomainValue, void, Output>): Promise<Output>;
+    <Input, Output>(query: QueryDefinition<DomainValue, Input, Output>, input: Input): Promise<Output>;
+}
+type ExecutableDomain<DomainValue extends Domain> = DomainValue extends {
+    readonly source: infer Source extends schema.DomainSchema;
+} ? Extract<schema.DomainOf<Source>, Domain> : DomainValue;
+/** Private Runtime binding to one Client and the exact loaded root Domain. */
+export declare function bindQuery<DomainValue extends Domain>(client: QueryClient, domain: DomainValue): QueryExecutor<ExecutableDomain<DomainValue>>;
+export {};

package/dist/application/query/execution/executor.js

@@ -0,0 +1,7 @@
+import { executeQuery } from './execute.js';
+/** Private Runtime binding to one Client and the exact loaded root Domain. */
+export function bindQuery(client, domain) {
+    const executable = domain;
+    const execute = (query, input) => executeQuery(client, executable, query, input);
+    return execute;
+}

package/dist/application/query/execution/index.d.ts

@@ -0,0 +1,2 @@
+export { executeQuery, type QueryClient } from './execute.js';
+export type { QueryExecutor } from './executor.js';

package/dist/application/query/execution/index.js

@@ -0,0 +1 @@
+export { executeQuery } from './execute.js';

package/dist/application/query/execution/pages.d.ts

@@ -0,0 +1 @@
+export { pages as executePages } from '../single/pagination.js';

package/dist/application/query/execution/pages.js

@@ -0,0 +1 @@
+export { pages as executePages } from '../single/pagination.js';

package/dist/application/query/execution/projection.d.ts

@@ -0,0 +1,3 @@
+import type { QueryAST, QueryResultFor } from '@astrale-os/kernel-core/graph/query';
+import type { ProjectedQuery, QueryProjectionContext } from '../single/index.js';
+export declare function projectQuery<Input, Output, Ast extends QueryAST>(definition: ProjectedQuery<Input, Output, Ast>, result: QueryResultFor<Ast>, input: Input, context: QueryProjectionContext<Ast>): Output;

package/dist/application/query/execution/projection.js

@@ -0,0 +1,3 @@
+export function projectQuery(definition, result, input, context) {
+    return definition.project(result, input, context);
+}

package/dist/application/query/failure.d.ts

@@ -0,0 +1,10 @@
+export interface QueryFailure extends Error {
+    readonly code: string;
+}
+export type QueryPaginationErrorCode = 'QUERY_PAGINATION_LIMIT' | 'QUERY_PAGINATION_CURSOR_REPEATED';
+export declare class QueryPaginationError extends Error implements QueryFailure {
+    readonly code: QueryPaginationErrorCode;
+    readonly name = "QueryPaginationError";
+    constructor(code: QueryPaginationErrorCode, message: string);
+}
+export declare function queryFailure(input: unknown): QueryFailure | undefined;

package/dist/application/query/failure.js

@@ -0,0 +1,14 @@
+export class QueryPaginationError extends Error {
+    code;
+    name = 'QueryPaginationError';
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function queryFailure(input) {
+    if (!(input instanceof Error))
+        return undefined;
+    const code = input.code;
+    return typeof code === 'string' && code.startsWith('QUERY_') ? input : undefined;
+}

package/dist/application/query/index.d.ts

@@ -0,0 +1,10 @@
+export { defineCollectionQuery, defineCompositeQuery, defineQuery, realizeQuery } from './define.js';
+export type { CollectionQuerySpec } from './collection/metadata.js';
+export { executeQuery, type QueryClient, type QueryExecutor } from './execution/index.js';
+export { QueryPaginationError, type QueryFailure, type QueryPaginationErrorCode, } from './failure.js';
+export type { CollectionQueryDefinition, CollectionValue, CompositeQueryDefinition, QueryAstOf, QueryDefinition, QueryInputOf, QueryOutputOf, SingleQueryDefinition, } from './query.js';
+export { queryResult } from './single/index.js';
+export type { CompleteQueryProjectionContext, PaginatedQuery, ProjectedQuery, QueryPages, QueryPagination, QueryProjectionContext, RawQuery, SingleQuery, } from './single/index.js';
+export type { CompositeQuery, ProjectedCompositeQuery, QueryComposition, QueryPlan, QueryPlanInput, QueryPlanOutput, QueryPlanValue, RawCompositeQuery, } from './composite/index.js';
+/** Canonical Query language and authoring values accept DSL ResolvedClass directly. */
+export * from '@astrale-os/kernel-core/graph/query';

package/dist/application/query/index.js

@@ -0,0 +1,6 @@
+export { defineCollectionQuery, defineCompositeQuery, defineQuery, realizeQuery } from './define.js';
+export { executeQuery } from './execution/index.js';
+export { QueryPaginationError, } from './failure.js';
+export { queryResult } from './single/index.js';
+/** Canonical Query language and authoring values accept DSL ResolvedClass directly. */
+export * from '@astrale-os/kernel-core/graph/query';

package/dist/application/query/query.d.ts

@@ -0,0 +1,35 @@
+import type { QueryAST, QueryResult } from '@astrale-os/kernel-core/graph/query';
+import type { AnyResolvedClass, ResolvedClass } from '@astrale-os/kernel-dsl/v1';
+import type { Edge } from '../../platform/graph/edge/index.js';
+import type { Node } from '../../platform/graph/node/index.js';
+import type { Domain } from '../../platform/schema/index.js';
+import type { CompositeQuery } from './composite/index.js';
+import type { QueryLifecycle, SingleQuery } from './single/index.js';
+declare const QUERY_DOMAIN: unique symbol;
+declare const QUERY_INPUT: unique symbol;
+declare const QUERY_OUTPUT: unique symbol;
+declare const COLLECTION_QUERY_CLASS: unique symbol;
+/** Inert Domain-bound Query recipe. Its projector is retained privately by the SDK. */
+export interface QueryDefinition<DomainValue extends Domain = Domain, Input = unknown, Output = QueryResult> {
+    readonly kind: 'query' | 'composite-query';
+    readonly [QUERY_DOMAIN]: (domain: DomainValue) => DomainValue;
+    readonly [QUERY_INPUT]?: Input;
+    readonly [QUERY_OUTPUT]?: Output;
+}
+export interface SingleQueryDefinition<DomainValue extends Domain = Domain, Input = unknown, Output = QueryResult> extends QueryDefinition<DomainValue, Input, Output> {
+    readonly kind: 'query';
+}
+export type CollectionValue<Class extends AnyResolvedClass> = Class extends ResolvedClass<'node'> ? Node : Class extends ResolvedClass<'edge'> ? Edge : never;
+/** Closed complete-Class Query recipe admitted for explicit physical union planning. */
+export interface CollectionQueryDefinition<DomainValue extends Domain = Domain, Class extends AnyResolvedClass = AnyResolvedClass> extends SingleQueryDefinition<DomainValue, void, readonly CollectionValue<Class>[]> {
+    readonly [COLLECTION_QUERY_CLASS]: Class;
+}
+export interface CompositeQueryDefinition<DomainValue extends Domain = Domain, Input = unknown, Output = unknown> extends QueryDefinition<DomainValue, Input, Output> {
+    readonly kind: 'composite-query';
+}
+/** Canonical admitted operation produced by realizing one Query recipe. */
+export type RealizedQuery<Input, Output = QueryResult, Ast extends QueryAST = QueryAST> = SingleQuery<Input, Output, Ast> | CompositeQuery<Input, unknown, Output, Domain>;
+export type QueryInputOf<Value> = Value extends QueryDefinition<infer _Domain, infer Input, infer _Output> ? Input : Value extends QueryLifecycle<infer Input, infer _Output> ? Input : never;
+export type QueryOutputOf<Value> = Value extends QueryDefinition<infer _Domain, infer _Input, infer Output> ? Output : Value extends QueryLifecycle<infer _Input, infer Output> ? Output : never;
+export type QueryAstOf<Value> = Value extends RealizedQuery<unknown, unknown, infer Ast> ? Ast : never;
+export {};

package/dist/application/query/query.js

@@ -0,0 +1 @@
+export {};

package/dist/application/query/single/index.d.ts

@@ -0,0 +1,4 @@
+export { queryResult } from './node.js';
+export { pages, type QueryPageExecutor } from './pagination.js';
+export { completeSelection } from './selection.js';
+export type { AuthoredSingleQuery, CompleteQueryProjectionContext, PaginatedQuery, ProjectedQuery, QueryLifecycle, QueryPages, QueryPagination, QueryProjectionContext, RawQuery, SingleQuery, } from './query.js';

package/dist/application/query/single/index.js

@@ -0,0 +1,3 @@
+export { queryResult } from './node.js';
+export { pages } from './pagination.js';
+export { completeSelection } from './selection.js';

package/dist/application/query/single/node.d.ts

@@ -0,0 +1,18 @@
+import type { Node, NodeId } from '@astrale-os/kernel-core/graph/node';
+import type { QueryEdgeItemFor, QueryEdgeProjection, QueryResult } from '@astrale-os/kernel-core/graph/query';
+declare function nodeValues(result: QueryResult, context: string): readonly Node[];
+declare function nodeIds(result: QueryResult, context: string): readonly NodeId[];
+declare function edgeItems(result: QueryResult, context: string): readonly QueryEdgeItemFor<QueryEdgeProjection>[];
+export declare const queryResult: Readonly<{
+    nodeValues: typeof nodeValues;
+    completeNodeValues: (results: readonly QueryResult[], context: string) => readonly Node[];
+    nodeIds: typeof nodeIds;
+    completeNodeIds: (results: readonly QueryResult[], context: string) => readonly NodeId[];
+    exactlyOneNode(result: QueryResult, context: string): Node;
+    optionalNode(result: QueryResult, context: string): Node | undefined;
+    edgeItems: typeof edgeItems;
+    optionalEdgeTarget(result: QueryResult, context: string): Node | undefined;
+    exactlyOneEdgeTarget(result: QueryResult, context: string): Node;
+    exactlyOneEdgeSource(result: QueryResult, context: string): Node;
+}>;
+export {};

package/dist/application/query/single/node.js

@@ -0,0 +1,86 @@
+function nodeValues(result, context) {
+    if (result.kind === 'graph') {
+        if (result.selection.kind !== 'node')
+            invalid(`Expected a Node ${context} query result.`);
+        const byId = new Map(result.graph.nodes.map((node) => [node.id, node]));
+        return Object.freeze(result.selection.ids.map((id) => {
+            const node = byId.get(id);
+            if (node === undefined)
+                invalid(`${context} graph omits selected Node ${id}.`);
+            return node;
+        }));
+    }
+    if (result.kind !== 'nodes')
+        invalid(`Expected a Node ${context} query result.`);
+    return Object.freeze(result.nodes.map((projection) => {
+        if (projection.kind !== 'value')
+            invalid(`Expected ${context} query to project Node values.`);
+        return projection.value;
+    }));
+}
+function nodeIds(result, context) {
+    if (result.kind === 'graph') {
+        if (result.selection.kind !== 'node')
+            invalid(`Expected a Node ${context} query result.`);
+        return result.selection.ids;
+    }
+    if (result.kind !== 'nodes')
+        invalid(`Expected a Node ${context} query result.`);
+    return Object.freeze(result.nodes.map((projection) => projection.value.id));
+}
+function edgeItems(result, context) {
+    if (result.kind !== 'edges')
+        invalid(`Expected an Edge ${context} query result.`);
+    return result.edges;
+}
+export const queryResult = Object.freeze({
+    nodeValues,
+    completeNodeValues: (results, context) => Object.freeze(results.flatMap((result) => nodeValues(result, context))),
+    nodeIds,
+    completeNodeIds: (results, context) => Object.freeze(results.flatMap((result) => nodeIds(result, context))),
+    exactlyOneNode(result, context) {
+        const values = nodeValues(result, context);
+        if (values.length !== 1)
+            invalid(`${context} must resolve exactly one Node.`);
+        return values[0];
+    },
+    optionalNode(result, context) {
+        const values = nodeValues(result, context);
+        if (values.length > 1)
+            invalid(`${context} must resolve at most one Node.`);
+        return values[0];
+    },
+    edgeItems,
+    optionalEdgeTarget(result, context) {
+        const items = edgeItems(result, context);
+        if (items.length > 1)
+            invalid(`${context} must resolve at most one Edge.`);
+        const target = items[0]?.target;
+        if (target === undefined)
+            return undefined;
+        if (target.kind !== 'value')
+            invalid(`${context} must project its target value.`);
+        return target.value;
+    },
+    exactlyOneEdgeTarget(result, context) {
+        const items = edgeItems(result, context);
+        if (items.length !== 1)
+            invalid(`${context} must resolve exactly one Edge.`);
+        const target = items[0].target;
+        if (target.kind !== 'value')
+            invalid(`${context} must project its target value.`);
+        return target.value;
+    },
+    exactlyOneEdgeSource(result, context) {
+        const items = edgeItems(result, context);
+        if (items.length !== 1)
+            invalid(`${context} must resolve exactly one Edge.`);
+        const source = items[0].source;
+        if (source.kind !== 'value')
+            invalid(`${context} must project its source value.`);
+        return source.value;
+    },
+});
+function invalid(message) {
+    throw new TypeError(message);
+}

package/dist/application/query/single/pagination.d.ts

@@ -0,0 +1,9 @@
+import type { QueryPageRequest, QueryResponse } from '@astrale-os/kernel-client/graph';
+import type { QueryAST, QueryResultFor } from '@astrale-os/kernel-core/graph/query';
+import type { QueryPages, QueryPagination } from './query.js';
+export interface QueryPageExecutor {
+    <Query extends QueryAST>(ast: Query, options: {
+        readonly page: QueryPageRequest;
+    }): Promise<QueryResponse<QueryResultFor<Query>>>;
+}
+export declare function pages<Query extends QueryAST>(execute: QueryPageExecutor, ast: Query, page: Readonly<Pick<QueryPageRequest, 'size'>>, pagination: QueryPagination): Promise<QueryPages<Query>>;

package/dist/application/query/single/pagination.js

@@ -0,0 +1,24 @@
+import { QueryPaginationError } from '../failure.js';
+export async function pages(execute, ast, page, pagination) {
+    const collected = [];
+    const cursors = new Set();
+    let response = await execute(ast, { page });
+    const kind = response.result.kind;
+    while (true) {
+        if (response.result.kind !== kind) {
+            throw new TypeError(`Paginated Query result kind changed from ${kind} to ${response.result.kind}.`);
+        }
+        collected.push(response.result);
+        const cursor = response.page.next;
+        if (cursor === undefined)
+            return Object.freeze(collected);
+        if (cursors.has(cursor)) {
+            throw new QueryPaginationError('QUERY_PAGINATION_CURSOR_REPEATED', 'Paginated Query returned a repeated continuation cursor.');
+        }
+        cursors.add(cursor);
+        if (collected.length >= pagination.maximumPages) {
+            throw new QueryPaginationError('QUERY_PAGINATION_LIMIT', `Paginated Query exceeded its ${pagination.maximumPages}-page bound.`);
+        }
+        response = await execute(ast, { page: { size: page.size, after: cursor } });
+    }
+}

package/dist/application/query/single/query.d.ts

@@ -0,0 +1,47 @@
+import type { QueryPageRequest } from '@astrale-os/kernel-client/graph';
+import type { QueryAST, QueryResult, QueryResultFor, QuerySelectionFor } from '@astrale-os/kernel-core/graph/query';
+import type { QueryFailure } from '../failure.js';
+declare const QUERY_INPUT: unique symbol;
+declare const QUERY_OUTPUT: unique symbol;
+export interface QueryLifecycle<Input, Output> {
+    readonly id: string;
+    readonly [QUERY_INPUT]?: Input;
+    readonly [QUERY_OUTPUT]?: Output;
+    prepare?(input: Input): Input;
+    reject?(failure: QueryFailure): Output;
+}
+export interface QueryProjectionContext<Query extends QueryAST> {
+    readonly ast: Query;
+}
+export interface CompleteQueryProjectionContext<Query extends QueryAST> extends QueryProjectionContext<Query> {
+    readonly complete: QuerySelectionFor<QueryResultFor<Query>>;
+}
+export interface QueryPagination {
+    readonly maximumPages: number;
+}
+export type QueryPages<Query extends QueryAST = QueryAST> = readonly [
+    QueryResultFor<Query>,
+    ...QueryResultFor<Query>[]
+];
+export interface SingleQueryBase<Input, Output, Query extends QueryAST> extends QueryLifecycle<Input, Output> {
+    readonly kind: 'single';
+    readonly page: Readonly<Pick<QueryPageRequest, 'size'>>;
+    build(input: Input): Query;
+}
+export interface RawQuery<Input, Query extends QueryAST = QueryAST> extends SingleQueryBase<Input, QueryResultFor<Query>, Query> {
+    readonly pagination?: undefined;
+    readonly project?: undefined;
+}
+export interface ProjectedQuery<Input, Output, Query extends QueryAST = QueryAST> extends SingleQueryBase<Input, Output, Query> {
+    readonly pagination?: undefined;
+    project(result: QueryResultFor<Query>, input: Input, context: QueryProjectionContext<Query>): Output;
+}
+export interface PaginatedQuery<Input, Output, Query extends QueryAST = QueryAST> extends SingleQueryBase<Input, Output, Query> {
+    readonly pagination: QueryPagination;
+    project(pages: QueryPages<Query>, input: Input, context: CompleteQueryProjectionContext<Query>): Output;
+}
+export type SingleQuery<Input, Output = QueryResult, Query extends QueryAST = QueryAST> = RawQuery<Input, Query> | ProjectedQuery<Input, Output, Query> | PaginatedQuery<Input, Output, Query>;
+export type AuthoredSingleQuery<Input, Output, Query extends QueryAST> = Omit<SingleQuery<Input, Output, Query>, 'kind' | 'page'> & {
+    readonly page?: Readonly<Pick<QueryPageRequest, 'size'>>;
+};
+export {};

package/dist/application/query/single/query.js

@@ -0,0 +1 @@
+export {};

package/dist/application/query/single/selection.d.ts

@@ -0,0 +1,2 @@
+import type { QueryResult, QuerySelectionFor } from '@astrale-os/kernel-core/graph/query';
+export declare function completeSelection<Result extends QueryResult>(pages: readonly [Result, ...Result[]]): QuerySelectionFor<Result>;

package/dist/application/query/single/selection.js

@@ -0,0 +1,23 @@
+import { QueryResult as QueryResultValue } from '@astrale-os/kernel-core/graph/query';
+export function completeSelection(pages) {
+    const first = QueryResultValue.selection(pages[0]);
+    if (first.kind === 'node') {
+        const ids = pages.flatMap((page) => {
+            const next = QueryResultValue.selection(page);
+            if (next.kind !== 'node')
+                changed(first, next);
+            return next.ids;
+        });
+        return Object.freeze({ kind: 'node', ids: Object.freeze(ids) });
+    }
+    const keys = pages.flatMap((page) => {
+        const next = QueryResultValue.selection(page);
+        if (next.kind !== 'edge')
+            changed(first, next);
+        return next.keys;
+    });
+    return Object.freeze({ kind: 'edge', keys: Object.freeze(keys) });
+}
+function changed(first, next) {
+    throw new TypeError(`Paginated Query selection changed from ${first.kind} to ${next.kind}.`);
+}

package/dist/application/requirements/administration.d.ts

@@ -0,0 +1,7 @@
+import type { AuthorityOperation } from '../../platform/schema/index.js';
+import type { AdministrationRequirements } from './requirement.js';
+export interface AdministrationRequirementsInput {
+    readonly grant?: readonly [AuthorityOperation, ...AuthorityOperation[]];
+    readonly revoke?: readonly [AuthorityOperation, ...AuthorityOperation[]];
+}
+export declare function captureAdministration(input: AdministrationRequirementsInput | undefined): AdministrationRequirements | undefined;

package/dist/application/requirements/administration.js

@@ -0,0 +1,38 @@
+import { AuthorityOperationOrder } from '../../platform/schema/index.js';
+export function captureAdministration(input) {
+    if (input === undefined)
+        return undefined;
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        invalid();
+    const keys = Reflect.ownKeys(input);
+    if (keys.some((key) => key !== 'grant' && key !== 'revoke'))
+        invalid();
+    if (input.grant === undefined && input.revoke === undefined) {
+        throw new TypeError('Administration requirements cannot be empty.');
+    }
+    const grant = operations(input.grant, 'grant');
+    const revoke = operations(input.revoke, 'revoke');
+    return Object.freeze({
+        ...(grant === undefined ? {} : { grant }),
+        ...(revoke === undefined ? {} : { revoke }),
+    });
+}
+function operations(input, kind) {
+    if (input === undefined)
+        return undefined;
+    if (!Array.isArray(input) || input.length === 0) {
+        throw new TypeError(`Administration ${kind} operations cannot be empty.`);
+    }
+    for (const operation of input) {
+        if (!AuthorityOperationOrder.includes(operation)) {
+            throw new TypeError(`Unknown administration ${kind} operation ${String(operation)}.`);
+        }
+    }
+    if (new Set(input).size !== input.length) {
+        throw new TypeError(`Administration ${kind} operations must be unique.`);
+    }
+    return Object.freeze([...input].sort((left, right) => AuthorityOperationOrder.indexOf(left) - AuthorityOperationOrder.indexOf(right)));
+}
+function invalid() {
+    throw new TypeError('Administration requirements may contain only grant and revoke.');
+}

package/dist/application/requirements/callables.d.ts

@@ -0,0 +1,4 @@
+import type { ResolvedFunction, ResolvedMethod } from '../../platform/schema/index.js';
+import type { Key as SemanticKey } from '../../platform/schema/index.js';
+export type CallableRequirementTarget = Pick<ResolvedFunction, 'key'> | Pick<ResolvedMethod, 'key'>;
+export declare function captureCallables(input: readonly CallableRequirementTarget[] | undefined): readonly SemanticKey.Callable[];

package/dist/application/requirements/callables.js

@@ -0,0 +1,30 @@
+import { callableAddress, Key } from '../../platform/schema/index.js';
+export function captureCallables(input) {
+    if (input === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(input))
+        throw new TypeError('Requirement callables must be an array.');
+    const keys = input.map((target) => {
+        if (target === null || typeof target !== 'object' || typeof target.key !== 'string') {
+            throw new TypeError('Callable requirement target is invalid.');
+        }
+        let key;
+        try {
+            key = Key(target.key);
+            callableAddress(key);
+        }
+        catch (cause) {
+            throw new TypeError('Callable requirement target is invalid.', { cause });
+        }
+        return key;
+    });
+    unique(keys, 'Callable requirement');
+    return Object.freeze([...keys].sort(compare));
+}
+function unique(values, label) {
+    if (new Set(values).size !== values.length)
+        throw new TypeError(`${label}s must be unique.`);
+}
+function compare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}

package/dist/application/requirements/classes.d.ts

@@ -0,0 +1,9 @@
+import type { AnyResolvedClass } from '../../platform/schema/index.js';
+import type { ClassRequirement } from './requirement.js';
+export declare const ClassOperationOrder: readonly ["create", "read", "traverse", "update", "delete"];
+export type ClassOperation = (typeof ClassOperationOrder)[number];
+export interface ClassRequirementInput {
+    readonly class: Pick<AnyResolvedClass, 'ref'>;
+    readonly operations: readonly [ClassOperation, ...ClassOperation[]];
+}
+export declare function captureClasses(input: readonly ClassRequirementInput[] | undefined): readonly ClassRequirement[];

package/dist/application/requirements/classes.js

@@ -0,0 +1,52 @@
+import { acceptDefinitionRef, Key } from '../../platform/schema/index.js';
+export const ClassOperationOrder = Object.freeze([
+    'create',
+    'read',
+    'traverse',
+    'update',
+    'delete',
+]);
+export function captureClasses(input) {
+    if (input === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(input))
+        throw new TypeError('Requirement classes must be an array.');
+    const classes = input.map((entry) => {
+        if (entry === null || typeof entry !== 'object' || !Array.isArray(entry.operations)) {
+            throw new TypeError('Class requirement is invalid.');
+        }
+        let ref;
+        try {
+            const admitted = acceptDefinitionRef(entry.class?.ref);
+            if (admitted.kind !== 'class')
+                throw new TypeError('Expected Class reference.');
+            ref = admitted;
+        }
+        catch (cause) {
+            throw new TypeError('Class requirement target is invalid.', { cause });
+        }
+        if (entry.operations.length === 0) {
+            throw new TypeError('Class requirement operations cannot be empty.');
+        }
+        const operations = entry.operations.map((operation) => {
+            if (!ClassOperationOrder.includes(operation)) {
+                throw new TypeError(`Unknown Class requirement operation ${String(operation)}.`);
+            }
+            return operation;
+        });
+        unique(operations, 'Class requirement operation');
+        return Object.freeze({
+            class: ref,
+            operations: Object.freeze([...operations].sort((left, right) => ClassOperationOrder.indexOf(left) - ClassOperationOrder.indexOf(right))),
+        });
+    });
+    unique(classes.map((entry) => Key.of(entry.class)), 'Class requirement');
+    return Object.freeze([...classes].sort((left, right) => compare(Key.of(left.class), Key.of(right.class))));
+}
+function unique(values, label) {
+    if (new Set(values).size !== values.length)
+        throw new TypeError(`${label}s must be unique.`);
+}
+function compare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}

package/dist/application/requirements/index.d.ts

@@ -0,0 +1,16 @@
+import type { AdministrationRequirementsInput } from './administration.js';
+import type { CallableRequirementTarget } from './callables.js';
+import type { ClassRequirementInput } from './classes.js';
+import type { Requirements } from './requirement.js';
+export type { AdministrationRequirements, ClassRequirement, Requirements } from './requirement.js';
+export type { CallableRequirementTarget } from './callables.js';
+export { ClassOperationOrder, type ClassOperation, type ClassRequirementInput } from './classes.js';
+export type { AdministrationRequirementsInput } from './administration.js';
+export interface RequirementsInput {
+    readonly callables?: readonly CallableRequirementTarget[];
+    readonly classes?: readonly ClassRequirementInput[];
+    readonly administration?: AdministrationRequirementsInput;
+}
+/** Capture canonical dependency requirements; Build proves the pinned dependency closure. */
+export declare function requirements(input?: RequirementsInput): Requirements;
+export declare function isRequirements(input: unknown): input is Requirements;

package/dist/application/requirements/index.js

@@ -0,0 +1,29 @@
+import { captureAdministration } from './administration.js';
+import { captureCallables } from './callables.js';
+import { captureClasses } from './classes.js';
+export { ClassOperationOrder } from './classes.js';
+const admittedRequirements = new WeakSet();
+/** Capture canonical dependency requirements; Build proves the pinned dependency closure. */
+export function requirements(input = {}) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        invalid();
+    if (Reflect.ownKeys(input).some((key) => key !== 'callables' && key !== 'classes' && key !== 'administration')) {
+        invalid();
+    }
+    const callables = captureCallables(input.callables);
+    const classes = captureClasses(input.classes);
+    const administration = captureAdministration(input.administration);
+    const value = Object.freeze({
+        callables,
+        classes,
+        ...(administration === undefined ? {} : { administration }),
+    });
+    admittedRequirements.add(value);
+    return value;
+}
+export function isRequirements(input) {
+    return input !== null && typeof input === 'object' && admittedRequirements.has(input);
+}
+function invalid() {
+    throw new TypeError('Requirements definition may contain only callables, classes, and administration.');
+}