@owlmeans/planning 0.1.18-rc.2 → 0.1.18-rc.21

package/src/aliases.ts

@@ -0,0 +1,31 @@
+import type { PlanningAliases, PlanningAliasHelper, PlanningDefinitionAliases } from './aliases/types.js'
+
+export const createPlanningAliasHelper = (): PlanningAliasHelper => {
+  const planningAliases = (base: string): PlanningAliases => Object.freeze({
+    base,
+    schema: Object.freeze({ list: `${base}:schema:list` }),
+    card: Object.freeze({
+      list: `${base}:card:list`,
+      summary: `${base}:card:summary`,
+      get: `${base}:card:get`,
+      transitions: `${base}:card:transitions`,
+      specifications: `${base}:card:specifications`,
+    }),
+    spec: Object.freeze({
+      get: `${base}:specification:get`,
+      revisions: `${base}:specification:revisions`,
+    }),
+    link: Object.freeze({ list: `${base}:link:list` }),
+    transition: Object.freeze({ get: `${base}:transition:get` }),
+    execute: `${base}:execute`,
+    commit: Object.freeze({ get: `${base}:commit:get`, events: `${base}:commit:events` }),
+  })
+
+  const planningDefinitionAliases = (base: string): PlanningDefinitionAliases => Object.freeze({
+    define: `${base}:schema:define`,
+  })
+
+  return { planningAliases, planningDefinitionAliases }
+}
+
+export const planningAliasHelper = createPlanningAliasHelper()

package/src/consts.ts

@@ -65,6 +65,32 @@ export enum CodeScope {
   Entity = 'entity',
 }
 
+/** What a data-defined schema record declares: a card type or a status flow. */
+export enum PlanningSchemaKind {
+  Type = 'type',
+  Flow = 'flow',
+}
+
+/**
+ * The layer a resolved type or flow comes from. `code` is the in-process registry (plugins),
+ * `entity` an organization-wide record, `project` a record scoped to one project card.
+ */
+export enum SchemaOrigin {
+  Code = 'code',
+  Entity = 'entity',
+  Project = 'project',
+}
+
+/** How a `schema.define` request writes its declarations. */
+export enum SchemaWriteMode {
+  /** Each declaration lands at its layer's next version. */
+  Define = 'define',
+  /** Compare-and-set: each declaration's `version` must be its layer's next version. */
+  Put = 'put',
+  /** Only keys the layer lacks are written, at version 1. */
+  Seed = 'seed',
+}
+
 /** Service alias of the planning facade host. Identical on the server and in a client. */
 export const PLANNING_SERVICE = 'planning'
 
@@ -109,28 +135,3 @@ export const QUERY_TEXT_MAX = 256
 /** The longest list a wire query carries in one value (ids, parents). */
 export const MAX_QUERY_LIST = 500
 
-/**
- * The aliases one planning tree answers under, derived from the mount's base alias.
- *
- * Two mounts of the tree in one deployment are two base aliases, never two copies of this table —
- * which is why nothing here is a global constant.
- */
-export const planningAliases = (base: string) => Object.freeze({
-  base,
-  schema: Object.freeze({ list: `${base}:schema:list` }),
-  card: Object.freeze({
-    list: `${base}:card:list`,
-    summary: `${base}:card:summary`,
-    get: `${base}:card:get`,
-    transitions: `${base}:card:transitions`,
-    specifications: `${base}:card:specifications`,
-  }),
-  spec: Object.freeze({
-    get: `${base}:specification:get`,
-    revisions: `${base}:specification:revisions`,
-  }),
-  link: Object.freeze({ list: `${base}:link:list` }),
-  transition: Object.freeze({ get: `${base}:transition:get` }),
-  execute: `${base}:execute`,
-  commit: Object.freeze({ get: `${base}:commit:get`, events: `${base}:commit:events` }),
-})

package/src/entrypoints/types.ts

@@ -0,0 +1,68 @@
+import type { EntrypointProtocol, OpenRequest, OpenValue } from '@owlmeans/entrypoint'
+import type { ListResult } from '@owlmeans/resource'
+import type { RouteParent } from '@owlmeans/route'
+import type {
+  CommitEvent, CommitFeedQuery, CommitQuery, CommitStatus, ExecuteRequest, Relationship, RelationshipQueryWire,
+  RevisionsQuery, SchemaDefineReply, SchemaDefineRequest, SchemaListQuery, ScopedSchemaBundle, Specification,
+  SpecificationQueryWire, SpecificationRevisionList, SummaryQueryWire, SummaryView, Transition, TransitionParams,
+  TransitionQueryWire, TransitionReceiptView, Workcard, WorkcardParams, WorkcardQueryWire,
+} from '../types.js'
+
+export interface PlanningBaseOptions {
+  /** The base alias every leaf alias derives from (`planningAliases`). */
+  alias: string
+  /** Defaults to `PLANNING_PATH`. */
+  path?: string
+  parent?: RouteParent
+  service?: string
+}
+
+export interface PlanningProtocolOptions {
+  base: PlanningBaseOptions
+  /** The guard(s) the base carries; every HTTP leaf inherits them. */
+  guards: string | readonly string[]
+  gate?: { alias: string, params?: string | readonly string[] }
+  /**
+   * The socket base the commit feed hangs under. The feed inherits THAT base's guards; the
+   * planning base when omitted.
+   */
+  socketBase?: RouteParent
+  /**
+   * Declare the data-defined schema surface: `schema.list` takes a `project` query and answers
+   * that layer's scoped bundle, and `schema.define` writes. Off by default — a tree without it
+   * declares exactly the other leaves.
+   */
+  definitions?: boolean
+}
+
+export interface PlanningProtocols {
+  base: EntrypointProtocol<OpenRequest, OpenValue>
+  schema: {
+    /** The plain bundle — or, on a tree declared with `definitions`, a layer's scoped one. */
+    list: EntrypointProtocol<{ query?: SchemaListQuery }, ScopedSchemaBundle>
+    /** Present on a tree declared with `definitions` only. */
+    define?: EntrypointProtocol<{ body: SchemaDefineRequest }, SchemaDefineReply>
+  }
+  card: {
+    list: EntrypointProtocol<{ query: WorkcardQueryWire }, ListResult<Workcard>>
+    summary: EntrypointProtocol<{ query: SummaryQueryWire }, SummaryView>
+    get: EntrypointProtocol<{ params: WorkcardParams }, Workcard>
+    transitions: EntrypointProtocol<{ params: WorkcardParams, query: TransitionQueryWire }, ListResult<Transition>>
+    specifications: EntrypointProtocol<{ params: WorkcardParams, query: SpecificationQueryWire }, ListResult<Specification>>
+  }
+  spec: {
+    get: EntrypointProtocol<{ params: WorkcardParams }, Specification>
+    revisions: EntrypointProtocol<{ params: WorkcardParams, query: RevisionsQuery }, SpecificationRevisionList>
+  }
+  link: {
+    list: EntrypointProtocol<{ query: RelationshipQueryWire }, ListResult<Relationship>>
+  }
+  transition: {
+    get: EntrypointProtocol<{ params: TransitionParams }, Transition>
+  }
+  execute: EntrypointProtocol<{ body: ExecuteRequest }, TransitionReceiptView>
+  commit: {
+    get: EntrypointProtocol<{ params: TransitionParams, query: CommitQuery }, CommitStatus>
+    events: EntrypointProtocol<{ query: CommitFeedQuery }, CommitEvent>
+  }
+}

package/src/entrypoints.ts

@@ -1,19 +1,20 @@
 import { contract, openProtocol, protocol, typed } from '@owlmeans/entrypoint'
 import type { ListResult } from '@owlmeans/resource'
-import { backend, route, RouteMethod, socket } from '@owlmeans/route'
-import type { RouteOptions } from '@owlmeans/route'
-import { PLANNING_PATH, planningAliases } from './consts.js'
+import { backend, route, RouteMethod, socket, type RouteOptions } from '@owlmeans/route'
+import { PLANNING_PATH } from './consts.js'
+import { planningAliasHelper } from './aliases.js'
 import {
   CommitQuerySchema, ExecuteRequestSchema, RelationshipQuerySchema, RevisionsQuerySchema,
-  SpecificationQuerySchema, SummaryQuerySchema, TransitionParamsSchema, TransitionQuerySchema,
-  WorkcardParamsSchema, WorkcardQuerySchema,
+  SchemaDefineRequestSchema, SchemaListQuerySchema, SpecificationQuerySchema, SummaryQuerySchema,
+  TransitionParamsSchema, TransitionQuerySchema, WorkcardParamsSchema, WorkcardQuerySchema,
 } from './schemas.js'
+import type { PlanningProtocolOptions, PlanningProtocols } from './entrypoints/types.js'
 import type {
-  CommitEvent, CommitFeedQuery, CommitQuery, CommitStatus, ExecuteRequest, PlanningProtocolOptions,
-  PlanningProtocols, PlanningSchemaBundle, Relationship, RelationshipQueryWire, RevisionsQuery,
-  Specification, SpecificationQueryWire, SpecificationRevisionList, SummaryQueryWire, SummaryView,
-  Transition, TransitionParams, TransitionQueryWire, TransitionReceiptView, Workcard, WorkcardParams,
-  WorkcardQueryWire,
+  CommitEvent, CommitFeedQuery, CommitQuery, CommitStatus, ExecuteRequest,
+  PlanningSchemaBundle, Relationship, RelationshipQueryWire, RevisionsQuery,
+  SchemaDefineReply, SchemaDefineRequest, SchemaListQuery, ScopedSchemaBundle, Specification, SpecificationQueryWire,
+  SpecificationRevisionList, SummaryQueryWire, SummaryView, Transition, TransitionParams,
+  TransitionQueryWire, TransitionReceiptView, Workcard, WorkcardParams, WorkcardQueryWire,
 } from './types.js'
 
 /**
@@ -26,9 +27,13 @@ import type {
  *
  * Queries travel as their `*Wire` shapes: encode with `encode*Query` before a call, decode with
  * `decode*Query` in a handler.
+ *
+ * `definitions: true` adds the data-defined schema surface: `schema.list` takes a `project` query
+ * and answers that layer's scoped bundle, and `schema.define` (POST `/schemas`) writes. Without it
+ * the tree declares exactly the other leaves.
  */
 export const makePlanningProtocols = (opts: PlanningProtocolOptions): PlanningProtocols => {
-  const aliases = planningAliases(opts.base.alias)
+  const aliases = planningAliasHelper.planningAliases(opts.base.alias)
   const mount: Partial<RouteOptions> = {
     ...(opts.base.parent != null ? { parent: opts.base.parent } : {}),
     ...(opts.base.service != null ? { service: opts.base.service } : {}),
@@ -40,12 +45,27 @@ export const makePlanningProtocols = (opts: PlanningProtocolOptions): PlanningPr
   })
   const get = (alias: string, path: string) => route(alias, path, backend({ parent: base }, RouteMethod.GET))
 
+  const schema: PlanningProtocols['schema'] = opts.definitions === true
+    ? Object.freeze({
+      list: protocol(
+        get(aliases.schema.list, '/schemas'),
+        contract.request({ query: typed<SchemaListQuery>(SchemaListQuerySchema) }, typed<ScopedSchemaBundle>())
+      ) as unknown as PlanningProtocols['schema']['list'],
+      define: protocol(
+        route(planningAliasHelper.planningDefinitionAliases(opts.base.alias).define, '/schemas', backend({ parent: base }, RouteMethod.POST)),
+        contract.request({ body: typed<SchemaDefineRequest>(SchemaDefineRequestSchema) }, typed<SchemaDefineReply>())
+      ),
+    })
+    : Object.freeze({
+      list: protocol(
+        get(aliases.schema.list, '/schemas'), contract(typed<PlanningSchemaBundle>())
+      ) as unknown as PlanningProtocols['schema']['list'],
+    })
+
   return Object.freeze({
     base,
 
-    schema: Object.freeze({
-      list: protocol(get(aliases.schema.list, '/schemas'), contract(typed<PlanningSchemaBundle>())),
-    }),
+    schema,
 
     card: Object.freeze({
       list: protocol(

package/src/errors.ts

@@ -206,6 +206,72 @@ export class PlanningScopeMismatch extends PlanningError {
   }
 }
 
+/**
+ * A data-defined schema write lost its compare-and-set: the layer's record is not at the version
+ * the write replaces. Re-read the layer and retry.
+ */
+export class SchemaConflict extends PlanningError {
+  public static override typeName: string = `${PlanningError.typeName}SchemaConflict`
+  /** The stored record moved past the expected version: answered 409. */
+  public static httpStatus = 409
+
+  constructor(message: string = 'error') {
+    super(`schema-conflict:${message}`)
+    this.type = SchemaConflict.typeName
+  }
+}
+
+/** A flow cannot be retired while a live type of an affected layer still resolves it. */
+export class SchemaInUse extends PlanningError {
+  public static override typeName: string = `${PlanningError.typeName}SchemaInUse`
+  /** Other declarations still depend on the key: answered 409. */
+  public static httpStatus = 409
+
+  constructor(message: string = 'error') {
+    super(`schema-in-use:${message}`)
+    this.type = SchemaInUse.typeName
+  }
+}
+
+/**
+ * The key is registered in code and does not declare itself `overridable` — or it is a project
+ * or specification type, which only code declares.
+ */
+export class SchemaSealed extends PlanningError {
+  public static override typeName: string = `${PlanningError.typeName}SchemaSealed`
+  /** The key cannot be declared as data: answered 422. */
+  public static httpStatus = 422
+
+  constructor(message: string = 'error') {
+    super(`schema-sealed:${message}`)
+    this.type = SchemaSealed.typeName
+  }
+}
+
+/** A data-defined declaration fails its closed-form checks. */
+export class SchemaInvalid extends PlanningError {
+  public static override typeName: string = `${PlanningError.typeName}SchemaInvalid`
+  /** The declaration's content is refused: answered 422. */
+  public static httpStatus = 422
+
+  constructor(message: string = 'error') {
+    super(`schema-invalid:${message}`)
+    this.type = SchemaInvalid.typeName
+  }
+}
+
+/** The request's access does not grant the write (creating or deleting a project, defining schemas). */
+export class PlanningForbidden extends PlanningError {
+  public static override typeName: string = `${PlanningError.typeName}Forbidden`
+  /** The caller lacks the grant the write needs: answered 403. */
+  public static httpStatus = 403
+
+  constructor(message: string = 'error') {
+    super(`forbidden:${message}`)
+    this.type = PlanningForbidden.typeName
+  }
+}
+
 /** The store behind this type cannot do what was asked (a foreign provider without a log). */
 export class PlanningUnsupported extends PlanningError {
   public static override typeName: string = `${PlanningError.typeName}Unsupported`
@@ -234,4 +300,9 @@ ResilientError.registerErrorClass(WorkcardConflict)
 ResilientError.registerErrorClass(CommitTimeout)
 ResilientError.registerErrorClass(CommitFailed)
 ResilientError.registerErrorClass(PlanningScopeMismatch)
+ResilientError.registerErrorClass(SchemaConflict)
+ResilientError.registerErrorClass(SchemaInUse)
+ResilientError.registerErrorClass(SchemaSealed)
+ResilientError.registerErrorClass(SchemaInvalid)
+ResilientError.registerErrorClass(PlanningForbidden)
 ResilientError.registerErrorClass(PlanningUnsupported)

package/src/helpers/apply/consts.local.ts

@@ -0,0 +1,10 @@
+/** Never written by a transition's `changes`: the fold takes them from the transition itself. */
+export const IDENTITY_KEYS = new Set(['id', 'kind', 'type', 'entityId', 'seq', 'head', 'createdAt'])
+
+/** Cannot be cleared: a record without them is not a record. */
+export const REQUIRED_KEYS = new Set([
+  ...IDENTITY_KEYS, 'title', 'parents', 'status', 'intrinsic', 'flows', 'labels', 'fields',
+])
+
+/** Merged shallowly into the card's own map rather than replacing it. */
+export const MERGED_KEYS = new Set(['fields', 'flows'])

package/src/helpers/apply/types.ts

@@ -0,0 +1,32 @@
+import type { Relationship, Transition, Workcard } from '../../types.js'
+
+/** The pure fold — the card and its edges after one transition. */
+export interface ApplyHelper {
+  /**
+   * THE fold: the card after one transition. Pure, total, no I/O — every store (memory, Mongo, a
+   * client mirror) folds with this and nothing else, so one log always means one card.
+   *
+   * - An already-applied transition (`seq <= card.seq`) returns the card unchanged: re-folding is
+   *   safe.
+   * - Anything but the next seq (`card.seq + 1`, or 1 for a create with no card) is refused with
+   *   `PlanningError('fold:out-of-order')`.
+   * - The log is replayed as written: a transition the executor would refuse today (an update naming
+   *   `createdBy`, appended before that refusal existed) still folds. Guards live at admission.
+   * - `create` builds the whole record from `changes` plus the transition's identity; `delete`
+   *   answers `null`; `link`/`unlink` only move `seq`/`head`/`updatedAt` (the edges are
+   *   {@link ApplyHelper.applyRelationship}'s); `update`/`transit` write `changes` — `fields` and
+   *   `flows` merge, everything else replaces — and clear `unset`.
+   * - Every result has `seq = transition.seq`, `head = max(head, seq)`, `updatedAt = transition.at`.
+   *
+   * @throws {PlanningError} `planning:fold:out-of-order:…`
+   */
+  applyTransition: <T extends Workcard = Workcard>(card: T | null | undefined, transition: Transition) => T | null
+  /**
+   * The relationships after one transition. Pure and total, like {@link ApplyHelper.applyTransition}.
+   *
+   * `create` adds its `links`, `link` adds its `link`, `unlink` removes the matching edge, and a
+   * `delete` removes every edge touching the card. An edge that already exists is kept as it is, so
+   * re-folding adds nothing. Every other action answers the list unchanged. Always a new array.
+   */
+  applyRelationship: (links: Relationship[], transition: Transition) => Relationship[]
+}