@owlmeans/server-planning 0.1.18-rc.21 → 0.1.18-rc.22

package/build/utils/request/types.d.ts

@@ -0,0 +1,23 @@
+import type { PlanningScope, TransitionActor } from '@owlmeans/planning';
+import type { PlanningAccess } from '../../types.js';
+/** One request's identity as planning reads it — built at the top of a handler, never stored. */
+export interface RequestScope {
+    /** The authenticated subject of a request, as a transition names it. */
+    actorOf: () => TransitionActor;
+    /**
+     * The scope a request reads and writes as.
+     *
+     * `entityId` is `requireEntityKey(req)` — the resolved organization id, never a value from the
+     * body or the query — and `extra` cannot replace it; `extra` adds what the deployment derives
+     * (a `channel`, a `service`). The actor is the authenticated subject plus that channel.
+     *
+     * @throws {AuthorizationError} when the request carries no organization
+     */
+    scopeOf: (extra?: Partial<PlanningScope>) => PlanningScope;
+    /**
+     * The scope of a request under a resolved {@link PlanningAccess}: the organization is the
+     * resolver's — never the token's, never `extra`'s — and `projects` narrows it.
+     */
+    accessScopeOf: (access: PlanningAccess, extra?: Partial<PlanningScope>) => PlanningScope;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/utils/request/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/utils/request/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAEpD,iGAAiG;AACjG,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,OAAO,EAAE,MAAM,eAAe,CAAA;IAC9B;;;;;;;;OAQG;IACH,OAAO,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,KAAK,aAAa,CAAA;IAC1D;;;OAGG;IACH,aAAa,EAAE,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,KAAK,aAAa,CAAA;CACzF"}

package/build/utils/request/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/utils/request/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/utils/request/types.ts"],"names":[],"mappings":""}

package/build/utils/request.d.ts

@@ -0,0 +1,4 @@
+import type { AbstractRequest } from '@owlmeans/entrypoint';
+import type { RequestScope } from './request/types.js';
+export declare const makeRequestScope: (req: AbstractRequest) => RequestScope;
+//# sourceMappingURL=request.d.ts.map

package/build/utils/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/utils/request.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAG3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAMtD,eAAO,MAAM,gBAAgB,QAAS,eAAe,KAAG,YA6BvD,CAAA"}

package/build/utils/request.js

@@ -0,0 +1,27 @@
+import { makeEntityScope } from '@owlmeans/auth-common';
+const clean = (record) => Object.fromEntries(Object.entries(record).filter(([, value]) => value != null && value !== ''));
+export const makeRequestScope = (req) => {
+    const actorOf = () => clean({
+        profileId: req.auth?.profileId,
+        userId: req.auth?.userId,
+    });
+    const scopeWith = (entityId, extra) => {
+        const subject = actorOf();
+        const channel = extra?.channel ?? extra?.actor?.channel;
+        return clean({
+            ...extra,
+            ...subject,
+            entityId,
+            channel,
+            actor: clean({ ...extra?.actor, ...subject, channel }),
+        });
+    };
+    const scopeOf = (extra) => scopeWith(makeEntityScope(req).requireEntityKey(), extra);
+    const accessScopeOf = (access, extra) => {
+        const { projects: _projects, entityId: _entityId, ...rest } = extra ?? {};
+        const scope = scopeWith(access.entityId, rest);
+        return access.projects != null ? { ...scope, projects: [...access.projects] } : scope;
+    };
+    return { actorOf, scopeOf, accessScopeOf };
+};
+//# sourceMappingURL=request.js.map

package/build/utils/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/utils/request.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEvD,MAAM,KAAK,GAAG,CAAmB,MAAS,EAAK,EAAE,CAC/C,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,IAAI,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC,CAAM,CAAA;AAEtG,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,GAAoB,EAAgB,EAAE;IACrE,MAAM,OAAO,GAAG,GAAoB,EAAE,CAAC,KAAK,CAAC;QAC3C,SAAS,EAAE,GAAG,CAAC,IAAI,EAAE,SAAS;QAC9B,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM;KACzB,CAAC,CAAA;IAEF,MAAM,SAAS,GAAG,CAAC,QAAgB,EAAE,KAA8B,EAAiB,EAAE;QACpF,MAAM,OAAO,GAAG,OAAO,EAAE,CAAA;QACzB,MAAM,OAAO,GAAG,KAAK,EAAE,OAAO,IAAI,KAAK,EAAE,KAAK,EAAE,OAAO,CAAA;QAEvD,OAAO,KAAK,CAAC;YACX,GAAG,KAAK;YACR,GAAG,OAAO;YACV,QAAQ;YACR,OAAO;YACP,KAAK,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,CAAC;SACvD,CAAkB,CAAA;IACrB,CAAC,CAAA;IAED,MAAM,OAAO,GAAG,CAAC,KAA8B,EAAiB,EAAE,CAAC,SAAS,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,gBAAgB,EAAE,EAAE,KAAK,CAAC,CAAA;IAE5H,MAAM,aAAa,GAAG,CAAC,MAAsB,EAAE,KAA8B,EAAiB,EAAE;QAC9F,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,IAAI,EAAE,CAAA;QACzE,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;QAE9C,OAAO,MAAM,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAA;IACvF,CAAC,CAAA;IAED,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,CAAA;AAC5C,CAAC,CAAA"}

package/build/utils/scope.d.ts

@@ -1,57 +1,24 @@
 import type { BasicConfig, BasicContext } from '@owlmeans/context';
 import type { AbstractRequest } from '@owlmeans/entrypoint';
-import { type PlanningFacade, type PlanningScope, type PlanningService, type TransitionActor, type Workcard } from '@owlmeans/planning';
+import type { PlanningFacade, PlanningScope, PlanningService, TransitionActor, Workcard } from '@owlmeans/planning';
 import type { PlanningAccess, PlanningAccessGrants, PlanningHandlerOptions } from '../types.js';
 import type { HandlerScope } from './types.js';
-/** The authenticated subject of a request, as a transition names it. */
+/** @deprecated compat:factory-refactor — use `makeRequestScope(req).actorOf()` */
 export declare const actorOf: (req: AbstractRequest) => TransitionActor;
-/**
- * The scope a request reads and writes as.
- *
- * `entityId` is `requireEntityKey(req)` — the resolved organization id, never a value from the
- * body or the query — and `extra` cannot replace it; `extra` adds what the deployment derives
- * (a `channel`, a `service`). The actor is the authenticated subject plus that channel.
- *
- * @throws {AuthorizationError} when the request carries no organization
- */
+/** @deprecated compat:factory-refactor — use `makeRequestScope(req).scopeOf(…)` */
 export declare const scopeOf: (req: AbstractRequest, extra?: Partial<PlanningScope>) => PlanningScope;
-/**
- * The scope of a request under a resolved {@link PlanningAccess}: the organization is the
- * resolver's — never the token's, never `extra`'s — and `projects` narrows it.
- */
+/** @deprecated compat:factory-refactor — use `makeRequestScope(req).accessScopeOf(…)` */
 export declare const accessScopeOf: (req: AbstractRequest, access: PlanningAccess, extra?: Partial<PlanningScope>) => PlanningScope;
+/** @deprecated compat:factory-refactor — use `planningHandlerOf(ctx).planningServiceOf(…)` */
 export declare const planningServiceOf: (ctx: BasicContext<BasicConfig>, opts?: Pick<PlanningHandlerOptions, 'service'>) => PlanningService;
-/**
- * The facade a handler works through, and the access it was resolved under.
- *
- * Without `opts.access` it is exactly the request's scope plus what `opts.scope` derives. With it,
- * the resolver names the organization and the visible projects; a throw from the resolver is the
- * request's error.
- */
+/** @deprecated compat:factory-refactor — use `planningHandlerOf(ctx).handlerScopeOf(…)` */
 export declare const handlerScopeOf: (ctx: BasicContext<BasicConfig>, req: AbstractRequest, opts?: PlanningHandlerOptions) => Promise<HandlerScope>;
-/** The facade a handler works through: the request's scope plus what `opts.scope` derives. */
+/** @deprecated compat:factory-refactor — use `planningHandlerOf(ctx).handlerFacade(…)` */
 export declare const handlerFacade: (ctx: BasicContext<BasicConfig>, req: AbstractRequest, opts?: PlanningHandlerOptions) => Promise<PlanningFacade>;
-/**
- * Refuse a write the access does not grant. No access, or access without `grants`, gates nothing;
- * a `grants` object refuses every flag it leaves out. `true` grants everything; a list grants the
- * project ids it names — `target` is the project the write is about (`undefined` for the
- * organization's root, which only `true` reaches).
- *
- * @throws {PlanningForbidden}
- */
+/** @deprecated compat:factory-refactor — use `makePlanningAccessModel(access).assertGranted(…)` */
 export declare const assertGranted: (access: PlanningAccess | undefined, grant: keyof PlanningAccessGrants, target?: string) => void;
-/**
- * A card the access's `writes` admits — the rule a narrowed read admits, over `writes`: a project
- * it names, or a card whose `parents` name one. A specification is admitted through its parent card
- * by the caller. No `writes` admits everything.
- */
+/** @deprecated compat:factory-refactor — use `makePlanningAccessModel(access).writableIn(…)` */
 export declare const writableIn: (access: PlanningAccess | undefined, card: Pick<Workcard, 'id' | 'parents'>) => boolean;
-/**
- * Refuse a write into a project the access's `writes` leaves out. No `writes` refuses nothing;
- * `target` is the project the write is in (`undefined` for the organization's root, which a set
- * `writes` never admits).
- *
- * @throws {PlanningForbidden}
- */
+/** @deprecated compat:factory-refactor — use `makePlanningAccessModel(access).assertWrites(…)` */
 export declare const assertWrites: (access: PlanningAccess | undefined, target?: string) => void;
 //# sourceMappingURL=scope.d.ts.map

package/build/utils/scope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../src/utils/scope.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,EAAuC,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC5K,OAAO,KAAK,EACV,cAAc,EAAE,oBAAoB,EAAE,sBAAsB,EAC7D,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAK9C,wEAAwE;AACxE,eAAO,MAAM,OAAO,QAAS,eAAe,KAAG,eAG7C,CAAA;AAeF;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,QAAS,eAAe,UAAU,OAAO,CAAC,aAAa,CAAC,KAAG,aACjC,CAAA;AAE9C;;;GAGG;AACH,eAAO,MAAM,aAAa,QACnB,eAAe,UAAU,cAAc,UAAU,OAAO,CAAC,aAAa,CAAC,KAC3E,aAKF,CAAA;AAED,eAAO,MAAM,iBAAiB,QACvB,YAAY,CAAC,WAAW,CAAC,SAAS,IAAI,CAAC,sBAAsB,EAAE,SAAS,CAAC,KAC7E,eAAsF,CAAA;AAEzF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,QACpB,YAAY,CAAC,WAAW,CAAC,OAAO,eAAe,SAAS,sBAAsB,KAClF,OAAO,CAAC,YAAY,CAQtB,CAAA;AAED,8FAA8F;AAC9F,eAAO,MAAM,aAAa,QACnB,YAAY,CAAC,WAAW,CAAC,OAAO,eAAe,SAAS,sBAAsB,KAClF,OAAO,CAAC,cAAc,CAAkD,CAAA;AAE3E;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,WAChB,cAAc,GAAG,SAAS,SAAS,MAAM,oBAAoB,WAAW,MAAM,KACrF,IASF,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,WAAY,cAAc,GAAG,SAAS,QAAQ,IAAI,CAAC,QAAQ,EAAE,IAAI,GAAG,SAAS,CAAC,KAAG,OAMvG,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,WAAY,cAAc,GAAG,SAAS,WAAW,MAAM,KAAG,IAKlF,CAAA"}
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../src/utils/scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AACnH,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAI/F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,kFAAkF;AAClF,eAAO,MAAM,OAAO,QAAS,eAAe,KAAG,eAAkD,CAAA;AAEjG,mFAAmF;AACnF,eAAO,MAAM,OAAO,QAAS,eAAe,UAAU,OAAO,CAAC,aAAa,CAAC,KAAG,aACzC,CAAA;AAEtC,yFAAyF;AACzF,eAAO,MAAM,aAAa,QACnB,eAAe,UAAU,cAAc,UAAU,OAAO,CAAC,aAAa,CAAC,KAC3E,aAAmE,CAAA;AAEtE,8FAA8F;AAC9F,eAAO,MAAM,iBAAiB,QACvB,YAAY,CAAC,WAAW,CAAC,SAAS,IAAI,CAAC,sBAAsB,EAAE,SAAS,CAAC,KAC7E,eAAiE,CAAA;AAEpE,2FAA2F;AAC3F,eAAO,MAAM,cAAc,QACpB,YAAY,CAAC,WAAW,CAAC,OAAO,eAAe,SAAS,sBAAsB,KAClF,OAAO,CAAC,YAAY,CAA2D,CAAA;AAElF,0FAA0F;AAC1F,eAAO,MAAM,aAAa,QACnB,YAAY,CAAC,WAAW,CAAC,OAAO,eAAe,SAAS,sBAAsB,KAClF,OAAO,CAAC,cAAc,CAA0D,CAAA;AAEnF,mGAAmG;AACnG,eAAO,MAAM,aAAa,WAChB,cAAc,GAAG,SAAS,SAAS,MAAM,oBAAoB,WAAW,MAAM,KACrF,IAAoE,CAAA;AAEvE,gGAAgG;AAChG,eAAO,MAAM,UAAU,WAAY,cAAc,GAAG,SAAS,QAAQ,IAAI,CAAC,QAAQ,EAAE,IAAI,GAAG,SAAS,CAAC,KAAG,OACtD,CAAA;AAElD,kGAAkG;AAClG,eAAO,MAAM,YAAY,WAAY,cAAc,GAAG,SAAS,WAAW,MAAM,KAAG,IAC7B,CAAA"}

package/build/utils/scope.js

@@ -1,100 +1,22 @@
-import { requireEntityKey } from '@owlmeans/auth-common';
-import { PLANNING_SERVICE, PlanningForbidden } from '@owlmeans/planning';
-const clean = (record) => Object.fromEntries(Object.entries(record).filter(([, value]) => value != null && value !== ''));
-/** The authenticated subject of a request, as a transition names it. */
-export const actorOf = (req) => clean({
-    profileId: req.auth?.profileId,
-    userId: req.auth?.userId,
-});
-const scopeWith = (req, entityId, extra) => {
-    const subject = actorOf(req);
-    const channel = extra?.channel ?? extra?.actor?.channel;
-    return clean({
-        ...extra,
-        ...subject,
-        entityId,
-        channel,
-        actor: clean({ ...extra?.actor, ...subject, channel }),
-    });
-};
-/**
- * The scope a request reads and writes as.
- *
- * `entityId` is `requireEntityKey(req)` — the resolved organization id, never a value from the
- * body or the query — and `extra` cannot replace it; `extra` adds what the deployment derives
- * (a `channel`, a `service`). The actor is the authenticated subject plus that channel.
- *
- * @throws {AuthorizationError} when the request carries no organization
- */
-export const scopeOf = (req, extra) => scopeWith(req, requireEntityKey(req), extra);
-/**
- * The scope of a request under a resolved {@link PlanningAccess}: the organization is the
- * resolver's — never the token's, never `extra`'s — and `projects` narrows it.
- */
-export const accessScopeOf = (req, access, extra) => {
-    const { projects: _projects, entityId: _entityId, ...rest } = extra ?? {};
-    const scope = scopeWith(req, access.entityId, rest);
-    return access.projects != null ? { ...scope, projects: [...access.projects] } : scope;
-};
-export const planningServiceOf = (ctx, opts) => ctx.service(opts?.service ?? PLANNING_SERVICE);
-/**
- * The facade a handler works through, and the access it was resolved under.
- *
- * Without `opts.access` it is exactly the request's scope plus what `opts.scope` derives. With it,
- * the resolver names the organization and the visible projects; a throw from the resolver is the
- * request's error.
- */
-export const handlerScopeOf = async (ctx, req, opts) => {
-    const extra = await opts?.scope?.(req, ctx);
-    if (opts?.access == null) {
-        return { facade: planningServiceOf(ctx, opts).for(scopeOf(req, extra ?? undefined)) };
-    }
-    const access = await opts.access(req, ctx);
-    return { facade: planningServiceOf(ctx, opts).for(accessScopeOf(req, access, extra ?? undefined)), access };
-};
-/** The facade a handler works through: the request's scope plus what `opts.scope` derives. */
-export const handlerFacade = async (ctx, req, opts) => (await handlerScopeOf(ctx, req, opts)).facade;
-/**
- * Refuse a write the access does not grant. No access, or access without `grants`, gates nothing;
- * a `grants` object refuses every flag it leaves out. `true` grants everything; a list grants the
- * project ids it names — `target` is the project the write is about (`undefined` for the
- * organization's root, which only `true` reaches).
- *
- * @throws {PlanningForbidden}
- */
-export const assertGranted = (access, grant, target) => {
-    if (access?.grants == null) {
-        return;
-    }
-    const granted = access.grants[grant];
-    if (granted === true || (Array.isArray(granted) && target != null && granted.includes(target))) {
-        return;
-    }
-    throw new PlanningForbidden(`${grant}:${target ?? 'root'}`);
-};
-/**
- * A card the access's `writes` admits — the rule a narrowed read admits, over `writes`: a project
- * it names, or a card whose `parents` name one. A specification is admitted through its parent card
- * by the caller. No `writes` admits everything.
- */
-export const writableIn = (access, card) => {
-    const writes = access?.writes;
-    if (writes == null) {
-        return true;
-    }
-    return (card.id != null && writes.includes(card.id)) || card.parents.some(parent => writes.includes(parent));
-};
-/**
- * Refuse a write into a project the access's `writes` leaves out. No `writes` refuses nothing;
- * `target` is the project the write is in (`undefined` for the organization's root, which a set
- * `writes` never admits).
- *
- * @throws {PlanningForbidden}
- */
-export const assertWrites = (access, target) => {
-    if (access?.writes == null || (target != null && access.writes.includes(target))) {
-        return;
-    }
-    throw new PlanningForbidden(`writes:${target ?? 'root'}`);
-};
+import { makePlanningAccessModel } from './access.js';
+import { planningHandlerOf } from './handler.js';
+import { makeRequestScope } from './request.js';
+/** @deprecated compat:factory-refactor — use `makeRequestScope(req).actorOf()` */
+export const actorOf = (req) => makeRequestScope(req).actorOf();
+/** @deprecated compat:factory-refactor — use `makeRequestScope(req).scopeOf(…)` */
+export const scopeOf = (req, extra) => makeRequestScope(req).scopeOf(extra);
+/** @deprecated compat:factory-refactor — use `makeRequestScope(req).accessScopeOf(…)` */
+export const accessScopeOf = (req, access, extra) => makeRequestScope(req).accessScopeOf(access, extra);
+/** @deprecated compat:factory-refactor — use `planningHandlerOf(ctx).planningServiceOf(…)` */
+export const planningServiceOf = (ctx, opts) => planningHandlerOf(ctx).planningServiceOf(opts);
+/** @deprecated compat:factory-refactor — use `planningHandlerOf(ctx).handlerScopeOf(…)` */
+export const handlerScopeOf = async (ctx, req, opts) => await planningHandlerOf(ctx).handlerScopeOf(req, opts);
+/** @deprecated compat:factory-refactor — use `planningHandlerOf(ctx).handlerFacade(…)` */
+export const handlerFacade = async (ctx, req, opts) => await planningHandlerOf(ctx).handlerFacade(req, opts);
+/** @deprecated compat:factory-refactor — use `makePlanningAccessModel(access).assertGranted(…)` */
+export const assertGranted = (access, grant, target) => makePlanningAccessModel(access).assertGranted(grant, target);
+/** @deprecated compat:factory-refactor — use `makePlanningAccessModel(access).writableIn(…)` */
+export const writableIn = (access, card) => makePlanningAccessModel(access).writableIn(card);
+/** @deprecated compat:factory-refactor — use `makePlanningAccessModel(access).assertWrites(…)` */
+export const assertWrites = (access, target) => makePlanningAccessModel(access).assertWrites(target);
 //# sourceMappingURL=scope.js.map

package/build/utils/scope.js.map

@@ -1 +1 @@
-{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../src/utils/scope.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scope.js","sourceRoot":"","sources":["../../src/utils/scope.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAG/C,kFAAkF;AAClF,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,GAAoB,EAAmB,EAAE,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAA;AAEjG,mFAAmF;AACnF,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,GAAoB,EAAE,KAA8B,EAAiB,EAAE,CAC7F,gBAAgB,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AAEtC,yFAAyF;AACzF,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,GAAoB,EAAE,MAAsB,EAAE,KAA8B,EAC7D,EAAE,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;AAEtE,8FAA8F;AAC9F,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,GAA8B,EAAE,IAA8C,EAC7D,EAAE,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAA;AAEpE,2FAA2F;AAC3F,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,EACjC,GAA8B,EAAE,GAAoB,EAAE,IAA6B,EAC5D,EAAE,CAAC,MAAM,iBAAiB,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;AAElF,0FAA0F;AAC1F,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAChC,GAA8B,EAAE,GAAoB,EAAE,IAA6B,EAC1D,EAAE,CAAC,MAAM,iBAAiB,CAAC,GAAG,CAAC,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;AAEnF,mGAAmG;AACnG,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,MAAkC,EAAE,KAAiC,EAAE,MAAe,EAChF,EAAE,CAAC,uBAAuB,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;AAEvE,gGAAgG;AAChG,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,MAAkC,EAAE,IAAsC,EAAW,EAAE,CAChH,uBAAuB,CAAC,MAAM,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA;AAElD,kGAAkG;AAClG,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAkC,EAAE,MAAe,EAAQ,EAAE,CACxF,uBAAuB,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-planning",
-  "version": "0.1.18-rc.21",
+  "version": "0.1.18-rc.22",
   "license": "MIT",
   "description": "The general planning implementation — the planning service and its plugin/middleware registry, the transition executor, the in-memory store, the protocol handlers and the commit feed.",
   "type": "module",
@@ -44,22 +44,22 @@
     }
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.18-rc.39",
-    "@owlmeans/auth-common": "^0.1.18-rc.46",
-    "@owlmeans/basic-ids": "^0.1.18-rc.36",
-    "@owlmeans/context": "^0.1.18-rc.33",
-    "@owlmeans/entrypoint": "^0.1.18-rc.40",
-    "@owlmeans/error": "^0.1.18-rc.37",
-    "@owlmeans/planning": "^0.1.18-rc.18",
-    "@owlmeans/queue": "^0.1.18-rc.40",
-    "@owlmeans/resource": "^0.1.18-rc.39",
-    "@owlmeans/log": "^0.1.18-rc.1",
-    "@owlmeans/route": "^0.1.18-rc.34",
-    "@owlmeans/server-api": "^0.1.18-rc.50",
-    "@owlmeans/server-context": "^0.1.18-rc.42",
-    "@owlmeans/server-entrypoint": "^0.1.18-rc.39",
-    "@owlmeans/server-socket": "^0.1.18-rc.53",
-    "@owlmeans/socket": "^0.1.18-rc.39"
+    "@owlmeans/auth": "^0.1.18-rc.40",
+    "@owlmeans/auth-common": "^0.1.18-rc.47",
+    "@owlmeans/basic-ids": "^0.1.18-rc.37",
+    "@owlmeans/context": "^0.1.18-rc.34",
+    "@owlmeans/entrypoint": "^0.1.18-rc.41",
+    "@owlmeans/error": "^0.1.18-rc.38",
+    "@owlmeans/planning": "^0.1.18-rc.19",
+    "@owlmeans/queue": "^0.1.18-rc.41",
+    "@owlmeans/resource": "^0.1.18-rc.40",
+    "@owlmeans/log": "^0.1.18-rc.2",
+    "@owlmeans/route": "^0.1.18-rc.35",
+    "@owlmeans/server-api": "^0.1.18-rc.51",
+    "@owlmeans/server-context": "^0.1.18-rc.43",
+    "@owlmeans/server-entrypoint": "^0.1.18-rc.40",
+    "@owlmeans/server-socket": "^0.1.18-rc.54",
+    "@owlmeans/socket": "^0.1.18-rc.40"
   },
   "peerDependencies": {
     "ajv": "*",
@@ -67,7 +67,7 @@
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@owlmeans/test": "^0.1.18-rc.34",
+    "@owlmeans/test": "^0.1.18-rc.35",
     "@types/bun": "^1.4.2",
     "@types/node": "^26.6.4",
     "ajv": "^8.20.0",

package/src/actions/apply-schema-request.ts

@@ -0,0 +1,35 @@
+import { SchemaWriteMode, type PlanningDefinitions, type SchemaDefineReply, type SchemaDefineRequest, type ScopedSchemaRecord } from '@owlmeans/planning'
+
+/**
+ * Apply one `schema.define` request to a facade's definitions: the declarations in the request's
+ * mode (flows before types), then the retirements — answering what was written and the layer as it
+ * resolves afterwards.
+ */
+export const applySchemaRequest = async (
+  definitions: PlanningDefinitions, request: SchemaDefineRequest
+): Promise<SchemaDefineReply> => {
+  const layer = request.project != null ? { project: request.project } : {}
+  const declarations = { types: request.types ?? [], flows: request.flows ?? [] }
+  const records: ScopedSchemaRecord[] = []
+
+  switch (request.mode ?? SchemaWriteMode.Define) {
+    case SchemaWriteMode.Put:
+      for (const flow of declarations.flows) {
+        records.push(await definitions.putFlow(flow, layer))
+      }
+      for (const type of declarations.types) {
+        records.push(await definitions.putType(type, layer))
+      }
+      break
+    case SchemaWriteMode.Seed:
+      records.push(...await definitions.seed(declarations, layer))
+      break
+    default:
+      records.push(...await definitions.define(declarations, layer))
+  }
+  for (const key of request.retire ?? []) {
+    records.push(await definitions.retire(key.kind, key.key, layer))
+  }
+
+  return { records, bundle: await definitions.bundle(request.project) }
+}

package/src/actions/commit.ts

@@ -2,7 +2,9 @@ import { handlers } from '@owlmeans/server-api'
 import { CommitState, MAX_COMMIT_POLL } from '@owlmeans/planning'
 import type { CommitStatus, PlanningProtocols } from '@owlmeans/planning'
 import type { Context, PlanningHandlerOptions } from '../types.js'
-import { clampSeconds, concealed, handlerFacade } from '../utils/index.js'
+import { guardHelper } from '../utils/guard.js'
+import { planningHandlerOf } from '../utils/handler.js'
+import type { RequestHandler } from './types.js'
 
 /**
  * The poll tool: a commit's status, held open up to `wait` seconds (clamped to `maxPoll`).
@@ -15,13 +17,13 @@ import { clampSeconds, concealed, handlerFacade } from '../utils/index.js'
  */
 export const getCommit = (
   protocol: PlanningProtocols['commit']['get'], opts?: PlanningHandlerOptions
-): ReturnType<ReturnType<typeof handlers<Context>>['request']> =>
-  handlers<Context>().request(protocol, async (req, ctx) => concealed(async (): Promise<CommitStatus> => {
-    const facade = await handlerFacade(ctx, req, opts)
+): RequestHandler =>
+  handlers<Context>().request(protocol, async (req, ctx) => guardHelper.concealed(async (): Promise<CommitStatus> => {
+    const facade = await planningHandlerOf(ctx).handlerFacade(req, opts)
     const transition = `${req.params.transition}`
 
     let status = await facade.commits.status(transition)
-    const wait = clampSeconds(req.query?.wait, opts?.maxPoll ?? MAX_COMMIT_POLL)
+    const wait = guardHelper.clampSeconds(req.query?.wait, opts?.maxPoll ?? MAX_COMMIT_POLL)
     if (status.state !== CommitState.Pending || wait <= 0) {
       return status
     }

package/src/actions/define-schemas.ts

@@ -0,0 +1,34 @@
+import { handlers } from '@owlmeans/server-api'
+import { PlanningUnsupported, type PlanningProtocols, type SchemaDefineReply, type SchemaDefineRequest } from '@owlmeans/planning'
+import type { Context, PlanningHandlerOptions } from '../types.js'
+import { makePlanningAccessModel } from '../utils/access.js'
+import { guardHelper } from '../utils/guard.js'
+import { planningHandlerOf } from '../utils/handler.js'
+import { applySchemaRequest } from './apply-schema-request.js'
+import type { RequestHandler } from './types.js'
+
+/**
+ * The write of data-defined types and flows. A project layer needs the project in the access's
+ * `writes` when the resolver answers it; then `grants.defineSchemas` gates when the resolver answers
+ * grants (the organization-wide layer needs `true`, a project layer its id).
+ *
+ * @throws {PlanningUnsupported} where the store holds no data-defined schemas
+ * @throws {PlanningForbidden | SchemaConflict | SchemaSealed | SchemaInvalid | SchemaInUse | WorkcardNotFound}
+ */
+export const defineSchemas = (
+  protocol: NonNullable<PlanningProtocols['schema']['define']>, opts?: PlanningHandlerOptions
+): RequestHandler =>
+  handlers<Context>().request(protocol, async (req, ctx) => guardHelper.concealed(async (): Promise<SchemaDefineReply> => {
+    const { facade, access } = await planningHandlerOf(ctx).handlerScopeOf(req, opts)
+    const request = (req.body ?? {}) as SchemaDefineRequest
+    if (facade.definitions == null) {
+      throw new PlanningUnsupported('definitions')
+    }
+    const model = makePlanningAccessModel(access)
+    if (request.project != null) {
+      model.assertWrites(request.project)
+    }
+    model.assertGranted('defineSchemas', request.project)
+
+    return await applySchemaRequest(facade.definitions, request)
+  }))

package/src/actions/execute.ts

@@ -1,130 +1,45 @@
 import { handlers } from '@owlmeans/server-api'
-import {
-  DEFAULT_COMMIT_TIMEOUT, isProject, isSpecification, MAX_COMMIT_POLL, normalizeParents, PlanningForbidden,
-  TransitionAction, WorkcardKind,
-} from '@owlmeans/planning'
+import { MAX_COMMIT_POLL } from '@owlmeans/planning'
 import type {
   ExecuteOptions, ExecuteRequest, PlanningFacade, PlanningProtocols, PlanningScope, TransitionExecution,
-  TransitionReceiptView, Workcard,
+  TransitionReceiptView,
 } from '@owlmeans/planning'
-import { withCreator } from '../executor/creator.js'
 import type { Context, PlanningAccess, PlanningHandlerOptions } from '../types.js'
-import { assertGranted, concealed, handlerScopeOf, writableIn } from '../utils/index.js'
-
-/**
- * What a wire execution may say. `actor` is dropped — the scope names the writer — and a create's
- * `createdBy` claim is dropped too: the executor's {@link withCreator} stamps the authenticated
- * subject, the same rule an in-process create follows. Applied here as well, so the returned
- * execution already carries it. A `createdBy` in `changes` or `unset` is not dropped: the executor
- * refuses it on every action (`assertCreatorFixed`), so no body moves an owner.
- */
-export const wireExecution = (body: ExecuteRequest, scope: PlanningScope): TransitionExecution => {
-  const { wait: _wait, timeout: _timeout, actor: _actor, ...exec } = body
-  if (exec.action === TransitionAction.Create && exec.card != null && typeof exec.card === 'object') {
-    const { createdBy: _createdBy, ...draft } = exec.card
-    exec.card = draft
-  }
-  return withCreator(exec, scope)
-}
-
-/** `wait`/`timeout` as a server grants them: the timeout never holds a request past `maxPoll`. */
-export const executeOptionsOf = (body: Pick<ExecuteRequest, 'wait' | 'timeout'>, maxPoll: number): ExecuteOptions => {
-  const ceiling = maxPoll * 1000
-  if (body.wait !== true) {
-    return {}
-  }
-  const asked = Number(body.timeout ?? DEFAULT_COMMIT_TIMEOUT)
-  return { wait: true, timeout: Math.min(Number.isFinite(asked) && asked > 0 ? asked : DEFAULT_COMMIT_TIMEOUT, ceiling) }
-}
-
-/**
- * Refuse an execution outside the access's `writes`: the card it acts on (a specification through
- * its parent card), or every parent a create names, must be one {@link writableIn} admits. A create
- * of a project is `grants.createProjects`' alone. A card or parent this scope cannot see is left to
- * the executor, which answers it as absent.
- *
- * @throws {PlanningForbidden}
- */
-export const assertExecutionWrites = async (
-  facade: PlanningFacade, exec: TransitionExecution, access?: PlanningAccess
-): Promise<void> => {
-  if (access?.writes == null) {
-    return
-  }
-  const admitted = async (card: Workcard): Promise<boolean> => {
-    if (writableIn(access, card)) {
-      return true
-    }
-    if (!isSpecification(card) || card.parent == null) {
-      return false
-    }
-    const parent = await facade.cards.load(card.parent)
-    return parent == null || writableIn(access, parent)
-  }
-
-  if (exec.action === TransitionAction.Create && exec.card != null && typeof exec.card === 'object') {
-    if (exec.card.kind === WorkcardKind.Project) {
-      return
-    }
-    const parents = normalizeParents(exec.card.parent, exec.card.parents)
-    if (parents.length === 0) {
-      throw new PlanningForbidden('writes:root')
-    }
-    for (const id of parents) {
-      const parent = await facade.cards.load(id)
-      if (parent != null && !await admitted(parent)) {
-        throw new PlanningForbidden(`writes:${id}`)
-      }
-    }
-    return
-  }
-  if (typeof exec.card === 'string' && exec.card !== '') {
-    const card = await facade.cards.load(exec.card)
-    if (card != null && !await admitted(card)) {
-      throw new PlanningForbidden(`writes:${exec.card}`)
-    }
-  }
-}
-
-/**
- * The access a wire execution needs. `writes` first ({@link assertExecutionWrites}); then the
- * grants: `createProjects` for a project create (its primary parent, or the root),
- * `deleteProjects` for the delete of a project card. A card this scope cannot see is left to the
- * executor, which answers it as absent.
- *
- * @throws {PlanningForbidden}
- */
-export const assertExecutionGranted = async (
-  facade: PlanningFacade, exec: TransitionExecution, access?: PlanningAccess
-): Promise<void> => {
-  await assertExecutionWrites(facade, exec, access)
-  if (access?.grants == null) {
-    return
-  }
-  if (exec.action === TransitionAction.Create && typeof exec.card === 'object' && exec.card?.kind === WorkcardKind.Project) {
-    assertGranted(access, 'createProjects', normalizeParents(exec.card.parent, exec.card.parents)[0])
-    return
-  }
-  if (exec.action === TransitionAction.Delete && typeof exec.card === 'string') {
-    const card = await facade.cards.load(exec.card)
-    if (card != null && isProject(card)) {
-      assertGranted(access, 'deleteProjects', card.id)
-    }
-  }
-}
+import { guardHelper } from '../utils/guard.js'
+import { planningHandlerOf } from '../utils/handler.js'
+import { executionHelper } from './execution.js'
+import type { RequestHandler } from './types.js'
 
 /** The one write route. */
 export const executePlanning = (
   protocol: PlanningProtocols['execute'], opts?: PlanningHandlerOptions
-): ReturnType<ReturnType<typeof handlers<Context>>['request']> =>
-  handlers<Context>().request(protocol, async (req, ctx) => concealed(async (): Promise<TransitionReceiptView> => {
-    const { facade, access } = await handlerScopeOf(ctx, req, opts)
+): RequestHandler =>
+  handlers<Context>().request(protocol, async (req, ctx) => guardHelper.concealed(async (): Promise<TransitionReceiptView> => {
+    const { facade, access } = await planningHandlerOf(ctx).handlerScopeOf(req, opts)
     const body = (req.body ?? {}) as ExecuteRequest
-    const exec = wireExecution(body, facade.scope)
-    await assertExecutionGranted(facade, exec, access)
-    const receipt = await facade.execute(exec, executeOptionsOf(body, opts?.maxPoll ?? MAX_COMMIT_POLL))
+    const exec = executionHelper.wireExecution(body, facade.scope)
+    await executionHelper.assertExecutionGranted(facade, exec, access)
+    const receipt = await facade.execute(exec, executionHelper.executeOptionsOf(body, opts?.maxPoll ?? MAX_COMMIT_POLL))
 
     return receipt.card !== undefined
       ? { transition: receipt.transition, card: receipt.card }
       : { transition: receipt.transition }
   }))
+
+/** @deprecated compat:factory-refactor — use `executionHelper.wireExecution(…)` */
+export const wireExecution = (body: ExecuteRequest, scope: PlanningScope): TransitionExecution =>
+  executionHelper.wireExecution(body, scope)
+
+/** @deprecated compat:factory-refactor — use `executionHelper.executeOptionsOf(…)` */
+export const executeOptionsOf = (body: Pick<ExecuteRequest, 'wait' | 'timeout'>, maxPoll: number): ExecuteOptions =>
+  executionHelper.executeOptionsOf(body, maxPoll)
+
+/** @deprecated compat:factory-refactor — use `executionHelper.assertExecutionWrites(…)` */
+export const assertExecutionWrites = async (
+  facade: PlanningFacade, exec: TransitionExecution, access?: PlanningAccess
+): Promise<void> => await executionHelper.assertExecutionWrites(facade, exec, access)
+
+/** @deprecated compat:factory-refactor — use `executionHelper.assertExecutionGranted(…)` */
+export const assertExecutionGranted = async (
+  facade: PlanningFacade, exec: TransitionExecution, access?: PlanningAccess
+): Promise<void> => await executionHelper.assertExecutionGranted(facade, exec, access)