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

package/src/conformance/consts.ts

@@ -0,0 +1,165 @@
+import { type AnyTypeSchema, type PlanningPlugin, type StatusFlowSchema, type WorkcardTypeSchema, AssigneeKind, PlanningResourceKind, CodeScope, CodeStyle, IntrinsicStatus, SpecificationFormat, WorkcardKind } from '@owlmeans/planning'
+
+/**
+ * The conformance vocabulary: a lending library. Branches (projects) hold books and periodicals
+ * (cards); a book runs a circulation flow and a review flow; documents are pages.
+ */
+export const LIBRARY = Object.freeze({
+  branch: 'library:branch',
+  room: 'library:reading-room',
+  book: 'library:book',
+  section: 'library:section',
+  human: 'library:human',
+  bot: 'library:bot',
+  guest: 'library:guest',
+  periodical: 'library:periodical',
+  page: 'library:page',
+  circulation: 'library:circulation',
+  review: 'library:review',
+  branchLife: 'library:branch-life',
+  pageLife: 'library:page-life',
+})
+
+export const BOOK_TYPE: WorkcardTypeSchema = {
+  type: LIBRARY.book,
+  kind: WorkcardKind.Card,
+  version: 1,
+  fields: {
+    type: 'object',
+    properties: { genre: { type: 'string', enum: ['poetry', 'history', 'fiction'] }, signed: { type: 'boolean' } },
+    additionalProperties: false,
+  },
+  flows: [LIBRARY.circulation, LIBRARY.review],
+  specifications: [{ category: 'summary', format: SpecificationFormat.Json, revisioned: true, keepRevisions: 3 }],
+  relationships: [{ name: 'sequel-of', to: [LIBRARY.book], single: true }, { name: 'shelved-near' }],
+  labels: ['rare', 'new', 'signed'],
+  code: { prefix: 'B-', style: CodeStyle.Random, length: 5, uppercase: true, uniqueWithin: CodeScope.Parent },
+}
+
+export const PERIODICAL_TYPE: WorkcardTypeSchema = {
+  type: LIBRARY.periodical,
+  kind: WorkcardKind.Card,
+  version: 1,
+  overridable: true,
+  label: 'Periodical',
+  fields: { type: 'object', additionalProperties: true },
+  flows: [LIBRARY.circulation],
+  specifications: [],
+}
+
+const flows: StatusFlowSchema[] = [
+  {
+    id: LIBRARY.circulation,
+    version: 1,
+    statuses: [
+      { key: 'shelved', intrinsic: IntrinsicStatus.Planned, initial: true },
+      { key: 'lent', intrinsic: IntrinsicStatus.InProgress },
+      { key: 'retired', intrinsic: IntrinsicStatus.Closed, terminal: true },
+    ],
+    transitions: [
+      { name: 'lend', from: ['shelved'], to: 'lent', explicit: true },
+      { name: 'return', from: ['lent'], to: 'shelved', explicit: true },
+      { name: 'retire', from: '*', to: 'retired' },
+      { name: 'restore', from: ['retired'], to: 'shelved' },
+    ],
+  },
+  {
+    id: LIBRARY.review,
+    version: 1,
+    statuses: [
+      { key: 'unreviewed', intrinsic: IntrinsicStatus.Planned, initial: true },
+      { key: 'reviewed', intrinsic: IntrinsicStatus.Closed },
+    ],
+    transitions: [{ name: 'review', from: ['unreviewed'], to: 'reviewed' }],
+  },
+  {
+    id: LIBRARY.branchLife,
+    version: 1,
+    statuses: [
+      { key: 'open', intrinsic: IntrinsicStatus.Planned, initial: true },
+      { key: 'active', intrinsic: IntrinsicStatus.InProgress },
+    ],
+    transitions: [{ name: 'activate', from: ['open'], to: 'active' }],
+  },
+  {
+    id: LIBRARY.pageLife,
+    version: 1,
+    statuses: [{ key: 'draft', intrinsic: IntrinsicStatus.Planned, initial: true }],
+    transitions: [],
+  },
+]
+
+const types: AnyTypeSchema[] = [
+  {
+    type: LIBRARY.branch,
+    kind: WorkcardKind.Project,
+    version: 1,
+    fields: { type: 'object', additionalProperties: true },
+    flows: [LIBRARY.branchLife],
+    cardTypes: [LIBRARY.book, LIBRARY.periodical, LIBRARY.section],
+    projectTypes: [LIBRARY.branch],
+    scopedCardTypes: true,
+    specifications: [
+      { category: 'charter', format: SpecificationFormat.Markdown },
+      { category: 'notes', format: SpecificationFormat.Markdown, multiple: true },
+    ],
+    code: { style: CodeStyle.Slug, uniqueWithin: CodeScope.Entity, mutable: true },
+  },
+  {
+    type: LIBRARY.room,
+    kind: WorkcardKind.Project,
+    version: 1,
+    fields: { type: 'object', additionalProperties: true },
+    flows: [LIBRARY.branchLife],
+    cardTypes: [LIBRARY.book],
+    specifications: [],
+  },
+  {
+    type: LIBRARY.section, kind: WorkcardKind.Card, version: 1,
+    fields: { type: 'object', properties: { requester: { type: 'string' }, reviewers: { type: 'array', items: { type: 'string' }, uniqueItems: true } }, additionalProperties: false },
+    flows: [LIBRARY.circulation], specifications: [],
+    parents: { types: [LIBRARY.branch, LIBRARY.section], required: true },
+    children: { types: [LIBRARY.book, LIBRARY.section] },
+    relationships: [
+      { name: 'requested-by', field: 'requester', toKind: PlanningResourceKind.Assignee, to: [LIBRARY.human], inverse: 'requests' },
+      { name: 'reviewed-by', field: 'reviewers', multiple: true, toKind: PlanningResourceKind.Assignee },
+    ],
+  },
+  BOOK_TYPE,
+  PERIODICAL_TYPE,
+  {
+    type: LIBRARY.page,
+    kind: WorkcardKind.Specification,
+    version: 1,
+    fields: { type: 'object', additionalProperties: true },
+    flows: [LIBRARY.pageLife],
+    specifications: [],
+  },
+]
+
+/** The types and flows every conformance case runs against — register it on the service under test. */
+export const planningConformancePlugin: PlanningPlugin = Object.freeze({
+  name: 'planning-conformance',
+  order: 0,
+  schemas: { types, flows, assigneeTypes: [
+    { type: LIBRARY.human, version: 1, kind: AssigneeKind.Human, fields: { type: 'object', properties: { department: { type: 'string' } }, additionalProperties: false } },
+    { type: LIBRARY.bot, version: 1, kind: AssigneeKind.NonHuman, fields: { type: 'object', additionalProperties: true } },
+    { type: LIBRARY.guest, version: 1, kind: AssigneeKind.Human, authentication: 'optional' as const, fields: { type: 'object', additionalProperties: true } },
+  ] },
+})
+
+/**
+ * The library's own definition properties and base card fields — registered by the case that checks
+ * them for its duration only, then replaced by a plugin of the same name that declares nothing.
+ */
+export const CONFORMANCE_APP_PLUGIN: PlanningPlugin = Object.freeze({
+  name: 'planning-conformance-app',
+  order: 1,
+  schemas: {
+    app: {
+      type: { properties: { description: { type: 'string', maxLength: 200 } } },
+      flow: { properties: { description: { type: 'string', maxLength: 200 } }, required: ['description'] },
+      card: { properties: { shelfmark: { type: 'string', pattern: '^[A-Z]-[0-9]+$' } } },
+    },
+  },
+})

package/src/conformance/errors.ts

@@ -0,0 +1,7 @@
+/** A conformance expectation that did not hold. Plain `Error`, so any test runner reports it. */
+export class ConformanceFailure extends Error {
+  constructor(message: string) {
+    super(`planning conformance: ${message}`)
+    this.name = 'ConformanceFailure'
+  }
+}

package/src/conformance/fixtures/types.ts

@@ -0,0 +1,11 @@
+import type { TransitionReceipt, Workcard } from '@owlmeans/planning'
+
+/** The records a conformance case creates and moves, through one organization's facade. */
+export interface ConformanceFixtures {
+  /** A branch (project) at the root, written and committed. */
+  createBranch: (title?: string, extra?: Record<string, unknown>) => Promise<Workcard>
+  /** A book (card) under a branch, written and committed. */
+  createBook: (branch: string, title?: string, extra?: Record<string, unknown>) => Promise<Workcard>
+  /** A transit of a card, waited until it commits. */
+  transit: (card: string, transition: string, extra?: { flow?: string }) => Promise<TransitionReceipt>
+}

package/src/conformance/fixtures.ts

@@ -0,0 +1,46 @@
+import { memoHelper } from '@owlmeans/context'
+import { TransitionAction, WorkcardKind, type PlanningFacade, type TransitionReceipt, type Workcard } from '@owlmeans/planning'
+import { LIBRARY } from './consts.js'
+import type { ConformanceFixtures } from './fixtures/types.js'
+
+export const makeConformanceFixtures = (planning: PlanningFacade): ConformanceFixtures => {
+  const createBranch = async (
+    title: string = 'Riverside branch', extra: Record<string, unknown> = {}
+  ): Promise<Workcard> => (await planning.execute({
+    card: { kind: WorkcardKind.Project, type: LIBRARY.branch, title, ...extra },
+    action: TransitionAction.Create,
+  }, { wait: true })).card!
+
+  const createBook = async (
+    branch: string, title: string = 'A book', extra: Record<string, unknown> = {}
+  ): Promise<Workcard> => (await planning.execute({
+    card: { kind: WorkcardKind.Card, type: LIBRARY.book, parent: branch, title, ...extra },
+    action: TransitionAction.Create,
+  }, { wait: true })).card!
+
+  const transit = async (
+    card: string, transition: string, extra: { flow?: string } = {}
+  ): Promise<TransitionReceipt> => await planning.execute({
+    card, action: TransitionAction.Transit, transition, ...extra,
+  }, { wait: true })
+
+  return { createBranch, createBook, transit }
+}
+
+/** The fixtures of one facade — one per facade. */
+export const conformanceFixturesOf = memoHelper.oncePer(makeConformanceFixtures)
+
+/** @deprecated compat:factory-refactor — use `conformanceFixturesOf(planning).createBranch(…)` */
+export const createBranch = async (
+  planning: PlanningFacade, title: string = 'Riverside branch', extra: Record<string, unknown> = {}
+): Promise<Workcard> => await conformanceFixturesOf(planning).createBranch(title, extra)
+
+/** @deprecated compat:factory-refactor — use `conformanceFixturesOf(planning).createBook(…)` */
+export const createBook = async (
+  planning: PlanningFacade, branch: string, title: string = 'A book', extra: Record<string, unknown> = {}
+): Promise<Workcard> => await conformanceFixturesOf(planning).createBook(branch, title, extra)
+
+/** @deprecated compat:factory-refactor — use `conformanceFixturesOf(planning).transit(…)` */
+export const transit = async (
+  planning: PlanningFacade, card: string, transition: string, extra: { flow?: string } = {}
+): Promise<TransitionReceipt> => await conformanceFixturesOf(planning).transit(card, transition, extra)

package/src/conformance/index.ts

@@ -0,0 +1,14 @@
+/**
+ * The planning store conformance suite — a framework-agnostic list of named cases every
+ * `PlanningStore` answers identically. No test runner is imported: a store's own spec file loops
+ * over {@link conformanceCasesFor} and hands each case a {@link ConformanceSubject}; a case throws
+ * `ConformanceFailure` (a plain `Error`) when an expectation does not hold.
+ */
+export * from './assert.js'
+export * from './cases.js'
+export type * from './types.js'
+export type * from './assert/types.js'
+export type * from './fixtures/types.js'
+export * from './clock.js'
+export * from './fixtures.js'
+export * from './consts.js'

package/src/conformance/resources.ts

@@ -0,0 +1,227 @@
+import { idHelper } from '@owlmeans/basic-ids'
+import {
+  AssigneeKind, FieldsInvalid, mentionHelper, ParentNotFound, PlanningError, PlanningForbidden,
+  PlanningResourceKind, PlanningSchemaKind, PLANNING_ASSIGNEE, PLANNING_REPORTER, ProjectMode, RelationshipRefused,
+  SchemaInvalid, TransitionAction, WorkcardConflict, WorkcardKind, WorkcardNotFound,
+  type PlanningFacade, type Workcard,
+} from '@owlmeans/planning'
+import { assertHelper } from './assert.js'
+import { LIBRARY } from './consts.js'
+import { conformanceFixturesOf } from './fixtures.js'
+import type { ConformanceCase } from './types.js'
+
+const { same, sameSet, rejects, check } = assertHelper
+const organization = () => `resource-conformance-${idHelper.uuid()}`
+const human = async (planning: PlanningFacade, nickname = 'reader') => await planning.assignees.create({
+  nickname, type: LIBRARY.human, kind: AssigneeKind.Human, authentication: { provider: 'external-oidc', externalId: nickname }, fields: { department: 'Library' },
+})
+const section = async (planning: PlanningFacade, parent: string, extra: Record<string, unknown> = {}): Promise<Workcard> =>
+  (await planning.execute({ action: TransitionAction.Create, card: { kind: WorkcardKind.Card, type: LIBRARY.section, parent, title: 'Section', ...extra } }, { wait: true })).card!
+
+/** Shared durable-resource and hierarchy contract, run unchanged against every stock provider. */
+export const resourceConformance: readonly ConformanceCase[] = [
+  {
+    name: 'assignees use schema-validated fields, stable authentication subjects and scoped nicknames', needs: ['resources'],
+    run: async ({ facade }) => {
+      const org = organization(), p = facade(org), other = facade(organization())
+      await rejects(p.assignees.create({ nickname: 'missing-auth', type: LIBRARY.human, kind: AssigneeKind.Human }), FieldsInvalid, 'human requires authentication by default')
+      await rejects(p.assignees.create({ nickname: 'wrong-fields', type: LIBRARY.human, kind: AssigneeKind.Human, authentication: { provider: 'x', externalId: 'x' }, fields: { department: 42 } }), FieldsInvalid, 'assignee schema is enforced')
+      const actor = await human(p, 'Alice')
+      await rejects(human(p, 'aLiCe'), WorkcardConflict, 'nickname is case insensitive')
+      await rejects(p.assignees.create({ nickname: 'another', type: LIBRARY.human, kind: AssigneeKind.Human, authentication: actor.authentication }), WorkcardConflict, 'authentication subject is unique in organization')
+      await human(other, 'Alice')
+      same(await other.assignees.load(actor.id!), null, 'another organization cannot read assignee')
+      const renamed = await p.assignees.update(actor.id!, { nickname: 'Librarian' }, { version: 1 })
+      same([renamed.id, renamed.version, renamed.authentication], [actor.id, 2, actor.authentication], 'rename keeps stable identity')
+      await rejects(p.assignees.update(actor.id!, { nickname: 'stale' }, { version: 1 }), WorkcardConflict, 'assignee CAS')
+      same((await p.assignees.list({ nickname: 'LIBRARIAN' })).items[0].id, actor.id, 'normalized query')
+      const bot = await p.assignees.create({ nickname: 'bot', type: LIBRARY.bot, kind: AssigneeKind.NonHuman })
+      const guest = await p.assignees.create({ nickname: 'guest', type: LIBRARY.guest, kind: AssigneeKind.Human })
+      same([bot.authentication, guest.authentication], [undefined, undefined], 'nonhuman and optional human schemas admit unlinked identities')
+      await rejects(p.assignees.create({ nickname: 'mismatch', type: LIBRARY.bot, kind: AssigneeKind.Human }), FieldsInvalid, 'fundamental kind follows schema')
+    },
+  },
+  {
+    name: 'active assignee queries include unset and false retirement flags', needs: ['resources'],
+    run: async ({ facade, store }) => {
+      const org = organization(), p = facade(org)
+      const unset = await human(p, 'unset'), explicit = await human(p, 'explicit'), retired = await human(p, 'retired')
+      await store.assignees!.put({ ...explicit, retired: false, version: 2 })
+      await p.assignees.retire(retired.id!, { version: 1 })
+      sameSet((await p.assignees.list({ retired: false })).items.map(row => row.id), [unset.id, explicit.id], 'active means not retired')
+      sameSet((await p.assignees.list({ retired: true })).items.map(row => row.id), [retired.id], 'only retired records')
+      same((await p.assignees.list()).total, 3, 'unfiltered retains historical identities')
+      same((await p.assignees.list({ retired: false, nickname: 'UNSET', kind: AssigneeKind.Human })).items[0]?.id, unset.id, 'active filter composes with identity queries')
+      same((await facade(organization()).assignees.list({ retired: false })).total, 0, 'active filter preserves organization scope')
+    },
+  },
+  {
+    name: 'concurrent nickname claims create one assignee and leave subsequent writes usable', needs: ['resources'],
+    run: async ({ facade }) => {
+      const p = facade(organization())
+      const attempts = await Promise.allSettled(Array.from({ length: 4 }, () => human(p, 'claimed')))
+      same(attempts.filter(row => row.status === 'fulfilled').length, 1, 'one nickname winner')
+      same((await p.assignees.list({ nickname: 'CLAIMED' })).total, 1, 'one persisted identity')
+      await human(p, 'after-conflict')
+      same((await p.assignees.list()).total, 2, 'rejected writes do not poison durable operation journal')
+    },
+  },
+  {
+    name: 'comments retain trusted authors and derived mentions follow edits and removal', needs: ['resources'],
+    run: async ({ facade, service, store }) => {
+      const org = organization(), p = facade(org), actor = await human(p), mentioned = await human(p, 'mentioned')
+      const branch = await conformanceFixturesOf(p).createBranch(), card = await conformanceFixturesOf(p).createBook(branch.id!)
+      const authored = service.for({ ...p.scope, assigneeId: actor.id })
+      await rejects(p.comments.create({ card: card.id!, body: 'no author' }), PlanningForbidden, 'comment requires trusted author')
+      const comment = await authored.comments.create({ card: card.id!, body: `${mentionHelper.encode(mentioned.id!, mentioned.nickname)} ${mentionHelper.encode(mentioned.id!, mentioned.nickname)}` })
+      same([comment.author, comment.version], [actor.id, 1], 'trusted immutable author')
+      const mentions = await authored.mentions.list({ comment: comment.id })
+      same(mentions.items.map(row => [row.assignee, row.revision]), [[mentioned.id, 1]], 'stable-id mentions deduplicate')
+      // Remove the cache behind the facade; the next reader repairs it from the source revision.
+      await store.mentions!.drop(mentions.items[0].id!, org, mentions.items[0].version)
+      same((await authored.mentions.list({ comment: comment.id })).total, 1, 'cache self-heals after interrupted cache write')
+      const stranger = service.for({ ...p.scope, assigneeId: mentioned.id })
+      await rejects(stranger.comments.update(comment.id!, { body: 'taken' }, { version: 1 }), PlanningForbidden, 'another author cannot edit')
+      await authored.comments.update(comment.id!, { body: 'no mentions' }, { version: 1 })
+      same((await authored.mentions.list({ comment: comment.id })).total, 0, 'removed mention is removed from cache')
+      await rejects(authored.comments.update(comment.id!, { body: 'stale' }, { version: 1 }), WorkcardConflict, 'comment CAS')
+      await authored.comments.remove(comment.id!, { version: 2 })
+      same(await authored.comments.load(comment.id!), null, 'comment removed')
+      same((await store.mentions!.list({ entityId: org, comment: comment.id })).total, 0, 'no orphan cache records')
+      await rejects(authored.comments.create({ card: card.id!, body: '[@foreign](assignee:missing)' }), WorkcardNotFound, 'mention of unknown assignee is refused')
+    },
+  },
+  {
+    name: 'teams are reusable canonical relationships with deduplicated project assignees', needs: ['resources'],
+    run: async ({ facade, store }) => {
+      const org = organization(), p = facade(org), actor = await human(p), fixtures = conformanceFixturesOf(p)
+      const first = await fixtures.createBranch('First'), second = await fixtures.createBranch('Second')
+      const a = await p.teams.create({ name: 'Editors', externalId: 'permission-group:editors' }), b = await p.teams.create({ name: 'Reviewers' })
+      await p.teams.addMember(a.id!, actor.id!); await p.teams.addMember(a.id!, actor.id!); await p.teams.addMember(b.id!, actor.id!)
+      await p.teams.attach(a.id!, first.id!); await p.teams.attach(a.id!, second.id!); await p.teams.attach(b.id!, first.id!)
+      sameSet((await p.teams.members(a.id!)).map(row => row.id), [actor.id], 'membership is idempotent')
+      sameSet(await p.teams.projects(a.id!), [first.id, second.id], 'one reusable team on two projects')
+      same((await p.teams.assignees(first.id!)).map(row => row.id), [actor.id], 'union of team assignees')
+      check((await store.links!.list({ entityId: org, from: a.id, fromKind: PlanningResourceKind.Team })).total === 1, 'native relationship store owns membership')
+      await rejects(p.teams.remove(a.id!, { version: 1 }), WorkcardConflict, 'attached team cannot be removed')
+      await p.teams.detach(a.id!, first.id!); await p.teams.detach(a.id!, second.id!); await p.teams.remove(a.id!, { version: 1 })
+      same(await p.teams.load(a.id!), null, 'detached team removed')
+      same((await p.assignees.get(actor.id!)).id, actor.id, 'team deletion preserves identity')
+      same(await facade(organization()).teams.load(b.id!), null, 'team isolation')
+    },
+  },
+  {
+    name: 'card reporter, assignee and schema fields derive indexes and preserve retired references', needs: ['resources'],
+    run: async ({ facade, store }) => {
+      const org = organization(), p = facade(org), actor = await human(p), bot = await p.assignees.create({ nickname: 'bot', type: LIBRARY.bot, kind: AssigneeKind.NonHuman })
+      const branch = await conformanceFixturesOf(p).createBranch()
+      const card = await section(p, branch.id!, { reporter: actor.id, assignee: bot.id, fields: { requester: actor.id, reviewers: [actor.id, bot.id] } })
+      const edges = await store.links!.list({ entityId: org, from: card.id, toKind: PlanningResourceKind.Assignee }, { size: 0 })
+      sameSet(edges.items.map(row => [row.type, row.to]), [[PLANNING_REPORTER, actor.id], [PLANNING_ASSIGNEE, bot.id], ['requested-by', actor.id], ['reviewed-by', actor.id], ['reviewed-by', bot.id]], 'canonical indexes from top-level and typed fields')
+      same((await p.relationships.list({ from: actor.id, type: 'requests', fromKind: PlanningResourceKind.Assignee })).items.map(edge => edge.to), [card.id], 'inverse relationship is derived from canonical edge')
+      await rejects(section(p, branch.id!, { reporter: 'missing' }), RelationshipRefused, 'unknown assignee reference')
+      await rejects(section(p, branch.id!, { fields: { requester: bot.id } }), RelationshipRefused, 'assignee-type relationship restriction')
+      await rejects(p.execute({ card: card.id!, action: TransitionAction.Link, link: { type: 'requested-by', to: bot.id! } }), RelationshipRefused, 'field-derived link cannot be independently edited')
+      await rejects(p.assignees.update(actor.id!, { type: LIBRARY.guest }, { version: 1 }), FieldsInvalid, 'assignee type change cannot invalidate existing typed references')
+      same((await p.assignees.get(actor.id!)).version, 1, 'rejected type change leaves identity unchanged')
+      await p.assignees.retire(actor.id!, { version: 1 })
+      await p.execute({ card: card.id!, action: TransitionAction.Update, changes: { title: 'Kept after retirement' } }, { wait: true })
+      await rejects(section(p, branch.id!, { reporter: actor.id }), RelationshipRefused, 'new references to retired assignee refused')
+      await p.execute({ card: card.id!, action: TransitionAction.Update, unset: ['reporter', 'fields.requester', 'fields.reviewers'] }, { wait: true })
+      same((await store.links!.list({ entityId: org, from: card.id }, { size: 0 })).items.map(row => row.type), [PLANNING_ASSIGNEE], 'cleared fields remove their derived indexes')
+    },
+  },
+  {
+    name: 'purging a former project preserves reparented descendant documents, links and full history', needs: ['resources'],
+    run: async ({ facade, store }) => {
+      const org = organization(), p = facade(org), fixtures = conformanceFixturesOf(p)
+      const old = await fixtures.createBranch('Former'), next = await fixtures.createBranch('Destination')
+      const parent = await section(p, old.id!), leaf = await fixtures.createBook(parent.id!)
+      const document = (await (await p.model(leaf)).write('summary', '{"lines":["kept"]}', { wait: true })).card!
+      await p.execute({ card: leaf.id!, action: TransitionAction.Link, link: { type: 'shelved-near', to: parent.id! } }, { wait: true })
+      const history = (await store.transitions!.list({ entityId: org, card: leaf.id }, { size: 0 })).items.map(row => row.id)
+      await p.execute({ card: parent.id!, action: TransitionAction.Update, changes: { parent: next.id, parents: [next.id!] } }, { wait: true })
+      await p.execute({ card: old.id!, action: TransitionAction.Delete }, { wait: true })
+      same((await p.cards.get(leaf.id!)).id, leaf.id, 'reparented descendant survives')
+      same((await p.specifications.get(document.id!)).body, '{"lines":["kept"]}', 'descendant document survives stale project cache')
+      sameSet((await store.transitions!.list({ entityId: org, card: leaf.id }, { size: 0 })).items.map(row => row.id), history, 'complete history survives former project purge')
+      same((await p.relationships.list({ from: leaf.id })).items.length, 1, 'surviving edge kept')
+      await (await p.model(leaf.id!)).update({ title: 'Still writable' }, { wait: true })
+    },
+  },
+  {
+    name: 'nested hierarchies derive primary parent type, refuse cycles and permit safe reparenting',
+    run: async ({ facade }) => {
+      const p = facade(organization()), fixtures = conformanceFixturesOf(p)
+      const a = await fixtures.createBranch('A'), b = await fixtures.createBranch('B'), parent = await section(p, a.id!), child = await section(p, parent.id!), leaf = await fixtures.createBook(child.id!)
+      same([child.parent, child.parentType, child.parents, leaf.parentType], [parent.id, LIBRARY.section, [parent.id], LIBRARY.section], 'primary parent is direct and typed')
+      same((await p.model(leaf)).schema().type, LIBRARY.book, 'nested card resolves nearest project schemas')
+      await rejects(p.execute({ card: parent.id!, action: TransitionAction.Update, changes: { parent: child.id, parents: [child.id!] } }), PlanningError, 'cycle refused')
+      await rejects(p.execute({ card: parent.id!, action: TransitionAction.Delete }), PlanningError, 'live children refuse ordinary deletion')
+      await rejects(p.execute({ card: child.id!, action: TransitionAction.Update, changes: { parents: [] }, unset: ['parent'] }), ParentNotFound, 'required primary parent cannot orphan')
+      await p.execute({ card: parent.id!, action: TransitionAction.Update, changes: { parent: b.id, parents: [b.id!] } }, { wait: true })
+      same((await p.cards.get(parent.id!)).parent, b.id, 'required hierarchy permits safe reparent')
+    },
+  },
+  {
+    name: 'recursive project scopes filter nested cards, comments and relationships before pagination', needs: ['resources'],
+    run: async ({ facade, service }) => {
+      const org = organization(), p = facade(org), fixtures = conformanceFixturesOf(p), actor = await human(p)
+      const a = await fixtures.createBranch('Allowed'), b = await fixtures.createBranch('Other'), nest = await section(p, a.id!)
+      const visible = await fixtures.createBook(nest.id!), hidden = await fixtures.createBook(b.id!)
+      await p.execute({ card: visible.id!, action: TransitionAction.Link, link: { type: 'shelved-near', to: hidden.id! } }, { wait: true })
+      const author = service.for({ ...p.scope, assigneeId: actor.id })
+      await author.comments.create({ card: visible.id!, body: 'visible' }); await author.comments.create({ card: hidden.id!, body: 'hidden' })
+      const narrowed = service.for({ ...p.scope, projects: [a.id!] })
+      same((await narrowed.cards.get(visible.id!)).id, visible.id, 'recursive single read')
+      same(await narrowed.cards.load(hidden.id!), null, 'outside scope absent')
+      const list = await narrowed.cards.list({ size: 1, page: 1 })
+      same(list.total, 3, 'recursive total includes project and nested cards')
+      same((await narrowed.comments.list({ size: 1 })).total, 1, 'comment total excludes inaccessible cards')
+      same((await narrowed.relationships.list({ from: visible.id, size: 1 })).total, 0, 'cross-scope target edge concealed')
+    },
+  },
+  {
+    name: 'project modes are validated metadata and project purge removes recursive auxiliaries only', needs: ['resources'],
+    run: async ({ facade, service, store }) => {
+      const org = organization(), p = facade(org), fixtures = conformanceFixturesOf(p), actor = await human(p)
+      const project = await fixtures.createBranch(), nest = await section(p, project.id!), card = await fixtures.createBook(nest.id!)
+      same(project.mode, ProjectMode.Opened, 'default open mode')
+      await p.execute({ card: project.id!, action: TransitionAction.Update, changes: { mode: ProjectMode.Closed } }, { wait: true })
+      same((await p.cards.get(project.id!)).mode, ProjectMode.Closed, 'closed mode persists independently of flow status')
+      await rejects(p.execute({ card: card.id!, action: TransitionAction.Update, changes: { mode: ProjectMode.Closed } }), FieldsInvalid, 'mode belongs to projects')
+      const team = await p.teams.create({ name: 'Reusable' }); await p.teams.addMember(team.id!, actor.id!); await p.teams.attach(team.id!, project.id!)
+      const author = service.for({ ...p.scope, assigneeId: actor.id })
+      const comment = await author.comments.create({ card: card.id!, body: mentionHelper.encode(actor.id!, actor.nickname) })
+      await p.execute({ card: project.id!, action: TransitionAction.Delete }, { wait: true })
+      same(await p.cards.load(card.id!), null, 'recursive child purged')
+      same(await p.comments.load(comment.id!), null, 'comment purged')
+      same((await store.mentions!.list({ entityId: org, comment: comment.id })).total, 0, 'mention purged')
+      same((await p.teams.get(team.id!)).id, team.id, 'organization team survives project purge')
+      same((await p.assignees.get(actor.id!)).id, actor.id, 'organization assignee survives project purge')
+      same(await p.teams.projects(team.id!), [], 'project-team edge purged')
+    },
+  },
+  {
+    name: 'data-defined assignee schemas are organization-only, validated and revisioned', needs: ['schemas', 'resources'],
+    run: async ({ facade, service }) => {
+      const p = facade(organization()), defs = p.definitions!, type = `agent:${idHelper.uuid()}`
+      const schema = { type, version: 1, kind: AssigneeKind.NonHuman, fields: { type: 'object', properties: { model: { type: 'string' } }, required: ['model'], additionalProperties: false } }
+      await defs.putAssigneeType(schema)
+      await rejects(p.assignees.create({ nickname: 'agent', type, kind: AssigneeKind.NonHuman }), FieldsInvalid, 'data-defined fields enforced')
+      const actor = await p.assignees.create({ nickname: 'agent', type, kind: AssigneeKind.NonHuman, fields: { model: 'runner' } })
+      const bundle = await defs.bundle()
+      check(bundle.assigneeTypes?.some(row => row.type === type) === true, 'assignee definition roundtrips')
+      const root = await conformanceFixturesOf(p).createBranch('Schema root')
+      const nested = (await p.execute({ action: TransitionAction.Create, card: { kind: WorkcardKind.Project, type: LIBRARY.branch, title: 'Nested schema project', parent: root.id! } }, { wait: true })).card!
+      const nestedType = `${type}:nested-card`
+      await defs.putType({ type: nestedType, version: 1, kind: WorkcardKind.Card, fields: { type: 'object' }, flows: [LIBRARY.circulation], specifications: [] }, { project: nested.id })
+      const scoped = service.for({ ...p.scope, projects: [root.id!] })
+      check((await scoped.definitions!.records({ project: nested.id })).some(record => record.key === nestedType), 'ancestor project scope includes descendant schema records')
+      await rejects(defs.putAssigneeType({ ...schema, version: 2, fields: { type: 'invalid-json-schema' } }), SchemaInvalid, 'invalid assignee schema refused')
+      await defs.retire(PlanningSchemaKind.AssigneeType, type)
+      await rejects(p.assignees.create({ nickname: 'new-agent', type, kind: AssigneeKind.NonHuman, fields: actor.fields }), FieldsInvalid, 'retired type refuses new identities')
+      same((await p.assignees.get(actor.id!)).id, actor.id, 'retirement keeps identity readable')
+    },
+  },
+]

package/src/conformance/types.ts

@@ -0,0 +1,20 @@
+import type { PlanningFacade, PlanningService, PlanningStore } from '@owlmeans/planning'
+
+/** What a case runs against: a planning service over the store under test. */
+export interface ConformanceSubject {
+  /** A service with `planningConformancePlugin` registered and a strictly increasing clock. */
+  service: PlanningService
+  /** The store under test — the service's default store. */
+  store: PlanningStore
+  /** A facade of one organization, acting as a signed-in person. */
+  facade: (entityId: string) => PlanningFacade
+}
+
+/** A capability a store may implement; a case that needs one is skipped for a store without it. */
+export type ConformanceCapability = 'schemas' | 'resources'
+
+export interface ConformanceCase {
+  name: string
+  needs?: ConformanceCapability[]
+  run: (subject: ConformanceSubject) => Promise<void>
+}

package/src/consts.ts

@@ -20,3 +20,9 @@ export const DEFAULT_COMMIT_MEMORY = 1000
  * ladder is what answers when it folded somewhere the hub does not.
  */
 export const COMMIT_POLL_LADDER: readonly number[] = Object.freeze([250, 1000, 2000])
+
+/**
+ * How many resolved schema layers (organization, project) a service keeps. A layer is re-resolved
+ * whenever its organization's schema revision moves, so the cap bounds memory, never staleness.
+ */
+export const DEFAULT_SCHEMA_VIEWS = 500