@owlmeans/server-planning 0.1.18-rc.8 → 0.1.18

package/src/actions/execution.ts

@@ -0,0 +1,100 @@
+import {
+  cardHelper, DEFAULT_COMMIT_TIMEOUT, PlanningForbidden, TransitionAction, WorkcardKind,
+} from '@owlmeans/planning'
+import type {
+  ExecuteOptions, ExecuteRequest, PlanningFacade, PlanningScope, TransitionExecution, Workcard,
+} from '@owlmeans/planning'
+import { creatorHelper } from '../executor/creator.js'
+import type { PlanningAccess } from '../types.js'
+import { makePlanningAccessModel } from '../utils/access.js'
+import type { ExecutionHelper } from './execution/types.js'
+
+export const createExecutionHelper = (): ExecutionHelper => {
+  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 creatorHelper.withCreator(exec, scope)
+  }
+
+  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) }
+  }
+
+  const assertExecutionWrites = async (
+    facade: PlanningFacade, exec: TransitionExecution, access?: PlanningAccess
+  ): Promise<void> => {
+    if (access?.writes == null) {
+      return
+    }
+    const model = makePlanningAccessModel(access)
+    const admitted = async (card: Workcard, seen = new Set<string>()): Promise<boolean> => {
+      if (model.writableIn(card)) return true
+      if (card.id != null && seen.has(card.id)) return false
+      if (card.id != null) seen.add(card.id)
+      for (const id of card.parents) {
+        const parent = await facade.cards.load(id)
+        if (parent != null && await admitted(parent, seen)) return true
+      }
+      return false
+    }
+
+    if (exec.action === TransitionAction.Create && exec.card != null && typeof exec.card === 'object') {
+      if (exec.card.kind === WorkcardKind.Project) {
+        return
+      }
+      const parents = cardHelper.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
+    }
+    for (const id of cardHelper.normalizeParents(exec.changes?.parent, exec.changes?.parents)) {
+      const target = await facade.cards.load(id)
+      if (target != null && !await admitted(target)) throw new PlanningForbidden(`writes:destination:${id}`)
+    }
+    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}`)
+      }
+    }
+  }
+
+  const assertExecutionGranted = async (
+    facade: PlanningFacade, exec: TransitionExecution, access?: PlanningAccess
+  ): Promise<void> => {
+    await assertExecutionWrites(facade, exec, access)
+    if (access?.grants == null) {
+      return
+    }
+    const model = makePlanningAccessModel(access)
+    if (exec.action === TransitionAction.Create && typeof exec.card === 'object' && exec.card?.kind === WorkcardKind.Project) {
+      model.assertGranted('createProjects', cardHelper.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 && cardHelper.isProject(card)) {
+        model.assertGranted('deleteProjects', card.id)
+      }
+    }
+  }
+
+  return { wireExecution, executeOptionsOf, assertExecutionWrites, assertExecutionGranted }
+}
+
+export const executionHelper = createExecutionHelper()

package/src/actions/get-card.ts

@@ -0,0 +1,14 @@
+import { handlers } from '@owlmeans/server-api'
+import type { PlanningProtocols } from '@owlmeans/planning'
+import type { Context, PlanningHandlerOptions } from '../types.js'
+import { guardHelper } from '../utils/guard.js'
+import { planningHandlerOf } from '../utils/handler.js'
+import type { RequestHandler } from './types.js'
+
+/** @throws {WorkcardNotFound} for an absent card and for another entity's alike */
+export const getCard = (protocol: PlanningProtocols['card']['get'], opts?: PlanningHandlerOptions): RequestHandler =>
+  handlers<Context>().request(protocol, async (req, ctx) => guardHelper.reply(async () => {
+    const facade = await planningHandlerOf(ctx).handlerFacade(req, opts)
+
+    return await facade.cards.get(`${req.params.id}`)
+  }))

package/src/actions/get-specification.ts

@@ -0,0 +1,14 @@
+import { handlers } from '@owlmeans/server-api'
+import type { PlanningProtocols } from '@owlmeans/planning'
+import type { Context, PlanningHandlerOptions } from '../types.js'
+import { guardHelper } from '../utils/guard.js'
+import { planningHandlerOf } from '../utils/handler.js'
+import type { RequestHandler } from './types.js'
+
+/** @throws {WorkcardNotFound} */
+export const getSpecification = (protocol: PlanningProtocols['spec']['get'], opts?: PlanningHandlerOptions): RequestHandler =>
+  handlers<Context>().request(protocol, async (req, ctx) => guardHelper.reply(async () => {
+    const facade = await planningHandlerOf(ctx).handlerFacade(req, opts)
+
+    return await facade.specifications.get(`${req.params.id}`)
+  }))

package/src/actions/index.ts

@@ -1,8 +1,18 @@
-export * from './cards.js'
+export type * from './execution/types.js'
+
+export * from './apply-schema-request.js'
 export * from './commit.js'
+export * from './define-schemas.js'
 export * from './execute.js'
+export * from './execution.js'
+export * from './get-card.js'
+export * from './get-specification.js'
 export * from './links.js'
-export * from './schemas.js'
-export * from './specs.js'
+export * from './list-card-specifications.js'
+export * from './list-card-transitions.js'
+export * from './list-cards.js'
+export * from './list-schemas.js'
+export * from './list-specification-revisions.js'
+export * from './summarize-cards.js'
 export * from './transitions.js'
 export * from './watch.js'

package/src/actions/links.ts

@@ -1,14 +1,16 @@
 import { handlers } from '@owlmeans/server-api'
-import { decodeRelationshipQuery } from '@owlmeans/planning'
+import { wireHelper } from '@owlmeans/planning'
 import type { PlanningProtocols } from '@owlmeans/planning'
 import type { Context, PlanningHandlerOptions } from '../types.js'
-import { concealed, handlerFacade } from '../utils/index.js'
+import { guardHelper } from '../utils/guard.js'
+import { planningHandlerOf } from '../utils/handler.js'
+import type { RequestHandler } from './types.js'
 
 export const listLinks = (
   protocol: PlanningProtocols['link']['list'], opts?: PlanningHandlerOptions
-): ReturnType<ReturnType<typeof handlers<Context>>['request']> =>
-  handlers<Context>().request(protocol, async (req, ctx) => concealed(async () => {
-    const facade = await handlerFacade(ctx, req, opts)
+): RequestHandler =>
+  handlers<Context>().request(protocol, async (req, ctx) => guardHelper.reply(async () => {
+    const facade = await planningHandlerOf(ctx).handlerFacade(req, opts)
 
-    return await facade.relationships.list(decodeRelationshipQuery(req.query))
+    return await facade.relationships.list(wireHelper.decodeRelationshipQuery(req.query))
   }))

package/src/actions/list-card-specifications.ts

@@ -0,0 +1,15 @@
+import { handlers } from '@owlmeans/server-api'
+import { wireHelper, type PlanningProtocols } from '@owlmeans/planning'
+import type { Context, PlanningHandlerOptions } from '../types.js'
+import { guardHelper } from '../utils/guard.js'
+import { planningHandlerOf } from '../utils/handler.js'
+import type { RequestHandler } from './types.js'
+
+/** One card's specifications — the current document per category unless `all`. */
+export const listCardSpecifications = (protocol: PlanningProtocols['card']['specifications'], opts?: PlanningHandlerOptions): RequestHandler =>
+  handlers<Context>().request(protocol, async (req, ctx) => guardHelper.reply(async () => {
+    const facade = await planningHandlerOf(ctx).handlerFacade(req, opts)
+    const card = await facade.cards.get(`${req.params.id}`)
+
+    return await facade.specifications.list(card.id!, wireHelper.decodeSpecificationQuery(req.query))
+  }))

package/src/actions/list-card-transitions.ts

@@ -0,0 +1,15 @@
+import { handlers } from '@owlmeans/server-api'
+import { wireHelper, type PlanningProtocols } from '@owlmeans/planning'
+import type { Context, PlanningHandlerOptions } from '../types.js'
+import { guardHelper } from '../utils/guard.js'
+import { planningHandlerOf } from '../utils/handler.js'
+import type { RequestHandler } from './types.js'
+
+/** One card's log. */
+export const listCardTransitions = (protocol: PlanningProtocols['card']['transitions'], opts?: PlanningHandlerOptions): RequestHandler =>
+  handlers<Context>().request(protocol, async (req, ctx) => guardHelper.reply(async () => {
+    const facade = await planningHandlerOf(ctx).handlerFacade(req, opts)
+    const card = await facade.cards.get(`${req.params.id}`)
+
+    return await facade.transitions.list({ ...wireHelper.decodeTransitionQuery(req.query), card: card.id })
+  }))

package/src/actions/list-cards.ts

@@ -0,0 +1,14 @@
+import { handlers } from '@owlmeans/server-api'
+import { wireHelper, type PlanningProtocols } from '@owlmeans/planning'
+import type { Context, PlanningHandlerOptions } from '../types.js'
+import { guardHelper } from '../utils/guard.js'
+import { planningHandlerOf } from '../utils/handler.js'
+import type { RequestHandler } from './types.js'
+
+/** Cards of the caller's entity; the query arrives in its wire shape and is decoded here. */
+export const listCards = (protocol: PlanningProtocols['card']['list'], opts?: PlanningHandlerOptions): RequestHandler =>
+  handlers<Context>().request(protocol, async (req, ctx) => guardHelper.reply(async () => {
+    const facade = await planningHandlerOf(ctx).handlerFacade(req, opts)
+
+    return await facade.cards.list(wireHelper.decodeWorkcardQuery(req.query))
+  }))

package/src/actions/list-schemas.ts

@@ -0,0 +1,29 @@
+import { handlers } from '@owlmeans/server-api'
+import type { PlanningProtocols, ScopedSchemaBundle } from '@owlmeans/planning'
+import type { Context, PlanningHandlerOptions } from '../types.js'
+import { guardHelper } from '../utils/guard.js'
+import { planningHandlerOf } from '../utils/handler.js'
+import type { RequestHandler } from './types.js'
+
+const text = (value: unknown): string | undefined =>
+  value == null || value === '' ? undefined : `${Array.isArray(value) ? value[0] : value}`
+
+/**
+ * The schema bundle — what a client loads to answer `can()` with no round trip. Scoped like every
+ * other leaf (no organization, no bundle). Where the store holds data-defined schemas it is the
+ * resolved layer of the organization, or of the project the `project` query names (a project this
+ * scope can see); otherwise the service's code bundle.
+ *
+ * @throws {WorkcardNotFound} for a project this scope cannot see
+ */
+export const listSchemas = (
+  protocol: PlanningProtocols['schema']['list'], opts?: PlanningHandlerOptions
+): RequestHandler =>
+  handlers<Context>().request(protocol, async (req, ctx) => guardHelper.reply(async (): Promise<ScopedSchemaBundle> => {
+    const { facade } = await planningHandlerOf(ctx).handlerScopeOf(req, opts)
+    if (facade.definitions == null) {
+      return facade.schemas.bundle()
+    }
+
+    return await facade.definitions.bundle(text((req.query as { project?: unknown } | undefined)?.project))
+  }))

package/src/actions/list-specification-revisions.ts

@@ -0,0 +1,15 @@
+import { handlers } from '@owlmeans/server-api'
+import type { PlanningProtocols } from '@owlmeans/planning'
+import type { Context, PlanningHandlerOptions } from '../types.js'
+import { guardHelper } from '../utils/guard.js'
+import { planningHandlerOf } from '../utils/handler.js'
+import type { RequestHandler } from './types.js'
+
+/** A document's history, newest first, replayed from its log. */
+export const listSpecificationRevisions = (protocol: PlanningProtocols['spec']['revisions'], opts?: PlanningHandlerOptions): RequestHandler =>
+  handlers<Context>().request(protocol, async (req, ctx) => guardHelper.reply(async () => {
+    const facade = await planningHandlerOf(ctx).handlerFacade(req, opts)
+    const limit = req.query?.limit == null ? undefined : Number(req.query.limit)
+
+    return { items: await facade.specifications.revisions(`${req.params.id}`, Number.isFinite(limit) ? limit : undefined) }
+  }))

package/src/actions/resources.ts

@@ -0,0 +1,79 @@
+import { handlers } from '@owlmeans/server-api'
+import { bind } from '@owlmeans/server-entrypoint'
+import { FieldsInvalid, PlanningForbidden } from '@owlmeans/planning'
+import type { AssigneeDraft, TeamDraft, CommentDraft, PlanningProtocols, PlanningResourceCommand, PlanningResourceReply } from '@owlmeans/planning'
+import type { Context, PlanningHandlerOptions } from '../types.js'
+import { guardHelper } from '../utils/guard.js'
+import { planningHandlerOf } from '../utils/handler.js'
+import { makePlanningAccessModel } from '../utils/access.js'
+import { executionHelper } from './execution.js'
+
+/** Dispatch the opt-in resources; attribution is taken only from the verified handler scope. */
+export const servePlanningResources = (protocols: PlanningProtocols, opts?: PlanningHandlerOptions) =>
+  (['assignees', 'teams', 'comments', 'mentions'] as const).flatMap(name => {
+    const tree = protocols[name]
+    if (tree == null) return []
+    return [
+      bind(tree.get, handlers<Context>().request(tree.get as any, async (req, ctx) => guardHelper.reply(async () => {
+        const facade = await planningHandlerOf(ctx).handlerFacade(req, opts)
+        return await facade[name].get((req.params as { id: string }).id)
+      }))),
+      bind(tree.list, handlers<Context>().request(tree.list as any, async (req, ctx) => guardHelper.reply(async () => {
+        const facade = await planningHandlerOf(ctx).handlerFacade(req, opts)
+        let query: unknown = {}
+        try { query = JSON.parse((req.query as { query?: string })?.query ?? '{}') } catch { throw new FieldsInvalid('resource:query') }
+        if (query == null || typeof query !== 'object' || Array.isArray(query)) throw new FieldsInvalid('resource:query')
+        // entityId is never read from the wire; the scoped facade owns it.
+        return await facade[name].list(query as never)
+      }))),
+      bind(tree.write, handlers<Context>().request(tree.write as any, async (req, ctx) => guardHelper.reply(async (): Promise<PlanningResourceReply> => {
+        const { facade, access } = await planningHandlerOf(ctx).handlerScopeOf(req, opts)
+        const body = req.body as PlanningResourceCommand
+        const reading = ['members', 'projects', 'assignees'].includes(body.action)
+        const id = (): string => { if (!body.id) throw new FieldsInvalid('resource:id'); return body.id }
+        const version = (): { version: number } => {
+          if (!Number.isSafeInteger(body.version) || body.version! < 1) throw new FieldsInvalid('resource:version')
+          return { version: body.version! }
+        }
+        if (!reading && name === 'assignees') makePlanningAccessModel(access).assertGranted('manageAssignees')
+        if (!reading && name === 'teams') makePlanningAccessModel(access).assertGranted('manageTeams')
+        if (name === 'comments' || name === 'mentions') {
+          const card = body.action === 'create' ? body.draft?.card : (await facade.comments.get(id())).card
+          if (card == null) throw new FieldsInvalid('comment:card')
+          await executionHelper.assertExecutionWrites(facade, { card, action: 'update' as any }, access)
+        }
+        if (name === 'teams' && ['attach', 'detach'].includes(body.action)) {
+          if (!body.project) throw new FieldsInvalid('team:project')
+          await executionHelper.assertExecutionWrites(facade, { card: body.project, action: 'update' as any }, access)
+        }
+        switch (name) {
+          case 'assignees':
+            if (body.action === 'create') return await facade.assignees.create(body.draft as AssigneeDraft)
+            if (body.action === 'update') return await facade.assignees.update(id(), body.draft ?? {}, version())
+            if (body.action === 'retire') return await facade.assignees.retire(id(), version())
+            break
+          case 'teams':
+            if (body.action === 'create') return await facade.teams.create(body.draft as TeamDraft)
+            if (body.action === 'update') return await facade.teams.update(id(), body.draft ?? {}, version())
+            if (body.action === 'remove') { await facade.teams.remove(id(), version()); return null }
+            if (body.action === 'members') return await facade.teams.members(id())
+            if (body.action === 'projects') return await facade.teams.projects(id())
+            if (body.action === 'assignees') return await facade.teams.assignees(id())
+            if (body.action === 'addMember' || body.action === 'removeMember') {
+              if (!body.assignee) throw new FieldsInvalid('team:assignee')
+              await facade.teams[body.action](id(), body.assignee); return null
+            }
+            if (body.action === 'attach' || body.action === 'detach') { await facade.teams[body.action](id(), body.project!); return null }
+            break
+          case 'comments':
+            if (body.action === 'create') return await facade.comments.create(body.draft as CommentDraft)
+            if (body.action === 'update') return await facade.comments.update(id(), { body: body.draft?.body! }, version())
+            if (body.action === 'remove') { await facade.comments.remove(id(), version()); return null }
+            break
+          case 'mentions':
+            if (body.action === 'rebuild') return await facade.mentions.rebuild(id())
+        }
+        throw new PlanningForbidden(`resource:action:${name}:${body.action}`)
+      }))),
+    ]
+  })

package/src/actions/summarize-cards.ts

@@ -0,0 +1,15 @@
+import { handlers } from '@owlmeans/server-api'
+import { wireHelper, type PlanningProtocols } from '@owlmeans/planning'
+import type { Context, PlanningHandlerOptions } from '../types.js'
+import { guardHelper } from '../utils/guard.js'
+import { planningHandlerOf } from '../utils/handler.js'
+import type { RequestHandler } from './types.js'
+
+/** Intrinsic counts of DIRECT children per parent. */
+export const summarizeCards = (protocol: PlanningProtocols['card']['summary'], opts?: PlanningHandlerOptions): RequestHandler =>
+  handlers<Context>().request(protocol, async (req, ctx) => guardHelper.reply(async () => {
+    const facade = await planningHandlerOf(ctx).handlerFacade(req, opts)
+    const { parents, ...query } = wireHelper.decodeSummaryQuery(req.query)
+
+    return await facade.cards.summary(parents, query)
+  }))

package/src/actions/transitions.ts

@@ -1,14 +1,16 @@
 import { handlers } from '@owlmeans/server-api'
 import type { PlanningProtocols } from '@owlmeans/planning'
 import type { Context, PlanningHandlerOptions } from '../types.js'
-import { concealed, handlerFacade } from '../utils/index.js'
+import { guardHelper } from '../utils/guard.js'
+import { planningHandlerOf } from '../utils/handler.js'
+import type { RequestHandler } from './types.js'
 
 /** @throws {WorkcardNotFound} for an absent transition and for another entity's alike */
 export const getTransition = (
   protocol: PlanningProtocols['transition']['get'], opts?: PlanningHandlerOptions
-): ReturnType<ReturnType<typeof handlers<Context>>['request']> =>
-  handlers<Context>().request(protocol, async (req, ctx) => concealed(async () => {
-    const facade = await handlerFacade(ctx, req, opts)
+): RequestHandler =>
+  handlers<Context>().request(protocol, async (req, ctx) => guardHelper.reply(async () => {
+    const facade = await planningHandlerOf(ctx).handlerFacade(req, opts)
 
     return await facade.transitions.get(`${req.params.transition}`)
   }))

package/src/actions/types.ts

@@ -0,0 +1,5 @@
+import type { EntrypointProtocolDeclaration } from '@owlmeans/entrypoint'
+import type { BoundEntrypointHandler } from '@owlmeans/server-entrypoint'
+
+/** A handler bound to one protocol leaf — what `handlers().request()` and `connection()` answer. */
+export interface RequestHandler extends BoundEntrypointHandler<EntrypointProtocolDeclaration> {}

package/src/actions/watch.ts

@@ -1,10 +1,14 @@
-import { PLANNING_COMMIT_EVENT } from '@owlmeans/planning'
+import { logger } from '@owlmeans/log'
+import { planningReplyHelper, PLANNING_COMMIT_EVENT } from '@owlmeans/planning'
 import type { CommitEvent, CommitFeedQuery, PlanningProtocols } from '@owlmeans/planning'
 import { connection } from '@owlmeans/server-socket'
 import type { EventMessage } from '@owlmeans/socket'
 import { MessageType } from '@owlmeans/socket'
 import type { Context, PlanningHandlerOptions } from '../types.js'
-import { handlerFacade } from '../utils/index.js'
+import { planningHandlerOf } from '../utils/handler.js'
+import type { RequestHandler } from './types.js'
+
+const log = logger('planning:watch')
 
 const text = (value: unknown): string | undefined =>
   value == null || value === '' ? undefined : `${value}`
@@ -18,8 +22,8 @@ const text = (value: unknown): string | undefined =>
  */
 export const watchCommits = (
   protocol: PlanningProtocols['commit']['events'], opts?: PlanningHandlerOptions
-): ReturnType<typeof connection> => connection<typeof protocol, Context>(protocol, async (conn, ctx, req) => {
-  const facade = await handlerFacade(ctx, req, opts)
+): RequestHandler => connection<typeof protocol, Context>(protocol, async (conn, ctx, req) => {
+  const facade = await planningHandlerOf(ctx).handlerFacade(req, opts)
   const query = (req.query ?? {}) as CommitFeedQuery
   const frame = opts?.event ?? PLANNING_COMMIT_EVENT
   const filter = {
@@ -30,9 +34,9 @@ export const watchCommits = (
   const unsubscribe = await facade.commits.subscribe(async (event: CommitEvent) => {
     try {
       const enriched = event.record !== undefined ? event : { ...event, record: await facade.cards.load(event.card) }
-      await conn.notify(frame, enriched)
+      await conn.notify(frame, planningReplyHelper.project(enriched))
     } catch (e) {
-      console.error('Planning commit notify error:', e)
+      log.warn('Planning commit notify failed', e)
     }
   }, filter)
 
@@ -45,7 +49,7 @@ export const watchCommits = (
       try {
         unsubscribe()
       } catch (e) {
-        console.error('Planning commit unsubscribe error:', e)
+        log.warn('Planning commit unsubscribe failed', e)
       }
     }
   })

package/src/conformance/assert/types.ts

@@ -0,0 +1,16 @@
+/** The expectations a conformance case states — each throws `ConformanceFailure` when it does not hold. */
+export interface AssertHelper {
+  /** @throws {ConformanceFailure} */
+  check: (condition: unknown, message: string) => void
+  /** Structural equality over JSON values. @throws {ConformanceFailure} */
+  same: (actual: unknown, expected: unknown, message: string) => void
+  /** The same members in any order. @throws {ConformanceFailure} */
+  sameSet: (actual: readonly unknown[], expected: readonly unknown[], message: string) => void
+  /**
+   * The promise rejects with an error of the class (matched by instance or by its registered type
+   * name, so a duplicate module copy counts). Answers the error.
+   *
+   * @throws {ConformanceFailure}
+   */
+  rejects: (run: Promise<unknown> | (() => Promise<unknown>), expected: { typeName: string }, message: string) => Promise<Error>
+}

package/src/conformance/assert.ts

@@ -0,0 +1,67 @@
+import { changesHelper } from '@owlmeans/planning'
+import type { AssertHelper } from './assert/types.js'
+import { ConformanceFailure } from './errors.js'
+
+export { ConformanceFailure } from './errors.js'
+
+const show = (value: unknown): string => {
+  try {
+    return JSON.stringify(value)
+  } catch {
+    return `${value}`
+  }
+}
+
+export const createAssertHelper = (): AssertHelper => {
+  const check = (condition: unknown, message: string): void => {
+    if (condition !== true) {
+      throw new ConformanceFailure(message)
+    }
+  }
+
+  const same = (actual: unknown, expected: unknown, message: string): void => {
+    if (!changesHelper.sameValue(actual, expected)) {
+      throw new ConformanceFailure(`${message}: expected ${show(expected)}, got ${show(actual)}`)
+    }
+  }
+
+  const sameSet = (actual: readonly unknown[], expected: readonly unknown[], message: string): void => {
+    const sort = (values: readonly unknown[]) => [...values].map(show).sort()
+    same(sort(actual), sort(expected), message)
+  }
+
+  const rejects = async (
+    run: Promise<unknown> | (() => Promise<unknown>), expected: { typeName: string }, message: string
+  ): Promise<Error> => {
+    try {
+      await (typeof run === 'function' ? run() : run)
+    } catch (error) {
+      const type = (error as { type?: unknown } | null)?.type
+      if (error instanceof (expected as unknown as abstract new (...args: never[]) => unknown)
+        || (typeof type === 'string' && type === expected.typeName)) {
+        return error as Error
+      }
+      throw new ConformanceFailure(`${message}: expected ${expected.typeName}, got ${show((error as Error)?.message ?? error)}`)
+    }
+    throw new ConformanceFailure(`${message}: expected ${expected.typeName}, nothing was thrown`)
+  }
+
+  return { check, same, sameSet, rejects }
+}
+
+export const assertHelper = createAssertHelper()
+
+/** @deprecated compat:factory-refactor — use `assertHelper.check(…)` */
+export const check = (condition: unknown, message: string): void => assertHelper.check(condition, message)
+
+/** @deprecated compat:factory-refactor — use `assertHelper.same(…)` */
+export const same = (actual: unknown, expected: unknown, message: string): void => assertHelper.same(actual, expected, message)
+
+/** @deprecated compat:factory-refactor — use `assertHelper.sameSet(…)` */
+export const sameSet = (actual: readonly unknown[], expected: readonly unknown[], message: string): void =>
+  assertHelper.sameSet(actual, expected, message)
+
+/** @deprecated compat:factory-refactor — use `assertHelper.rejects(…)` */
+export const rejects = async (
+  run: Promise<unknown> | (() => Promise<unknown>), expected: { typeName: string }, message: string
+): Promise<Error> => await assertHelper.rejects(run, expected, message)