@owlmeans/planning 0.1.18-rc.9 → 0.1.18

package/src/registry.ts

@@ -1,23 +1,47 @@
+import type { AssigneeTypeSchema } from './resources/types.js'
 import type { ValidateFunction } from 'ajv'
 import { PLANNING_SCHEMA_VERSION } from './consts.js'
 import { UnknownStatusFlow, UnknownWorkcardType } from './errors.js'
+import { appSchemaHelper } from './helpers/app.js'
 import { makeAjv } from './helpers/validate.js'
-import type { AnyTypeSchema, PlanningSchemaBundle, PlanningSchemaRegistry, StatusFlowSchema } from './types.js'
+import type { AnyTypeSchema, PlanningAppDeclarations, PlanningSchemaBundle, PlanningSchemaRegistry, StatusFlowSchema } from './types.js'
 
 /**
- * Types, flows and the compiled validator of each type's `fields`.
+ * Types, flows, the application's declarations and the compiled validator of each type's `fields`
+ * (its own schema, with the application's base card fields for a `card` type).
  *
  * It lives in the contract package so a client answers `can()` / `available()` from a loaded bundle
  * with no round trip. A later registration of the same type or flow id replaces the earlier one;
- * `load(bundle)` replaces everything.
+ * `registerApp` replaces the declarations; `load(bundle)` replaces everything.
  */
 export const makeSchemaRegistry = (bundle?: Partial<PlanningSchemaBundle>): PlanningSchemaRegistry => {
   const types = new Map<string, AnyTypeSchema>()
+  const assigneeTypes = new Map<string, AssigneeTypeSchema>()
+  const assigneeValidators = new Map<string, ValidateFunction>()
   const flows = new Map<string, StatusFlowSchema>()
   const validators = new Map<string, ValidateFunction>()
+  let app: PlanningAppDeclarations | undefined
   let ajv = makeAjv()
 
   const registry: PlanningSchemaRegistry = {
+    registerAssigneeType: schema => {
+      assigneeTypes.set(schema.type, schema)
+      assigneeValidators.delete(schema.type)
+    },
+    assigneeTypes: () => [...assigneeTypes.values()],
+    assigneeType: type => {
+      const schema = assigneeTypes.get(type)
+      if (schema == null) throw new UnknownWorkcardType(`assignee:${type}`)
+      return schema
+    },
+    assigneeValidator: type => {
+      let validator = assigneeValidators.get(type)
+      if (validator == null) {
+        validator = ajv.compile(registry.assigneeType(type).fields)
+        assigneeValidators.set(type, validator)
+      }
+      return validator
+    },
     registerType: schema => {
       types.set(schema.type, schema)
       validators.delete(schema.type)
@@ -27,6 +51,22 @@ export const makeSchemaRegistry = (bundle?: Partial<PlanningSchemaBundle>): Plan
       flows.set(flow.id, flow)
     },
 
+    registerApp: next => {
+      if (next != null) {
+        appSchemaHelper.assertDeclarations(next)
+      }
+      if (next == null && app == null) {
+        return
+      }
+      app = next == null ? undefined : structuredClone(next)
+      validators.clear()
+      assigneeValidators.clear()
+      // A fresh ajv: a replaced declaration must not collide with a schema `$id` the old one compiled.
+      ajv = makeAjv()
+    },
+
+    app: () => app,
+
     types: () => [...types.values()],
 
     type: type => {
@@ -57,10 +97,12 @@ export const makeSchemaRegistry = (bundle?: Partial<PlanningSchemaBundle>): Plan
       return registry.flow(primary)
     },
 
+    fieldsSchema: type => appSchemaHelper.fieldsSchemaOf(registry.type(type), app),
+
     validator: type => {
       let validate = validators.get(type)
       if (validate == null) {
-        validate = ajv.compile(registry.type(type).fields)
+        validate = ajv.compile(registry.fieldsSchema(type))
         validators.set(type, validate)
       }
       return validate
@@ -70,19 +112,28 @@ export const makeSchemaRegistry = (bundle?: Partial<PlanningSchemaBundle>): Plan
       version: PLANNING_SCHEMA_VERSION,
       types: [...types.values()],
       flows: [...flows.values()],
+      assigneeTypes: [...assigneeTypes.values()],
+      ...(app != null ? { app } : {}),
     }),
 
     load: next => {
+      assigneeTypes.clear()
+      assigneeValidators.clear()
       types.clear()
       flows.clear()
       validators.clear()
+      app = undefined
       // A fresh ajv: a replaced type must not collide with a schema `$id` the old one compiled.
       ajv = makeAjv()
+      registry.registerApp(next.app ?? undefined)
+      next.assigneeTypes?.forEach(registry.registerAssigneeType)
       next.flows.forEach(registry.registerFlow)
       next.types.forEach(registry.registerType)
     },
   }
 
+  registry.registerApp(bundle?.app ?? undefined)
+  bundle?.assigneeTypes?.forEach(registry.registerAssigneeType)
   bundle?.flows?.forEach(registry.registerFlow)
   bundle?.types?.forEach(registry.registerType)
 

package/src/resources/mentions.ts

@@ -0,0 +1,11 @@
+import type { MentionHelper } from './types.local.js'
+
+/** Stable-id Markdown mentions. Escaped display text cannot change the referenced identity. */
+export const mentionHelper: MentionHelper = {
+  encode: (id, nickname) => `[@${nickname.replace(/[\\\[\]]/g, '\\$&')}](assignee:${encodeURIComponent(id)})`,
+  parse: body => [...new Set([...body.matchAll(/\[@(?:\\.|[^\]\\])*\]\(assignee:([^\s)]+)\)/g)]
+    .flatMap(match => {
+      try { return [decodeURIComponent(match[1])] } catch { return [] }
+    }))],
+  nicknameKey: nickname => nickname.normalize('NFKC').trim().toLocaleLowerCase('en-US'),
+}

package/src/resources/protocol/types.ts

@@ -0,0 +1,21 @@
+import type { PlanningReply } from '../../helpers/reply/types.js'
+import type { EntrypointProtocol } from '@owlmeans/entrypoint'
+import type { ListResult } from '@owlmeans/resource'
+import type { AssigneeDraft, TeamDraft, CommentDraft, PlanningRecord } from '../types.js'
+
+export interface PlanningResourceQueryWire { query?: string }
+export interface PlanningResourceCommand {
+  action: 'create' | 'update' | 'retire' | 'remove' | 'members' | 'projects' | 'assignees' | 'addMember' | 'removeMember' | 'attach' | 'detach' | 'rebuild'
+  id?: string
+  draft?: Partial<AssigneeDraft & TeamDraft & CommentDraft>
+  version?: number
+  assignee?: string
+  project?: string
+}
+export type PlanningResourceReply = PlanningRecord | PlanningRecord[] | string[] | null
+
+export interface PlanningResourceProtocols<R extends PlanningRecord = PlanningRecord> {
+  get: EntrypointProtocol<{ params: { id: string } }, PlanningReply<R>>
+  list: EntrypointProtocol<{ query: PlanningResourceQueryWire }, PlanningReply<ListResult<R>>>
+  write: EntrypointProtocol<{ body: PlanningResourceCommand }, PlanningReply<PlanningResourceReply>>
+}

package/src/resources/protocol.ts

@@ -0,0 +1,36 @@
+import type { PlanningReply } from '../helpers/reply/types.js'
+import { planningAliasHelper } from '../aliases.js'
+import { contract, protocol, typed } from '@owlmeans/entrypoint'
+import type { EntrypointProtocol } from '@owlmeans/entrypoint'
+import { backend, route, RouteMethod } from '@owlmeans/route'
+import { AssigneeKind } from '../consts.js'
+import { WorkcardParamsSchema } from '../schemas.js'
+import type { ListResult } from '@owlmeans/resource'
+import type { PlanningRecord } from './types.js'
+import type { PlanningResourceCommand, PlanningResourceProtocols, PlanningResourceQueryWire, PlanningResourceReply } from './protocol/types.js'
+
+/** Opt-in auxiliary branches share the planning base's authentication guards. */
+export const makePlanningResourceProtocols = <R extends PlanningRecord>(base: EntrypointProtocol<any, any>, alias: string, name: 'assignees' | 'teams' | 'comments' | 'mentions'): PlanningResourceProtocols<R> => {
+  const aliases = planningAliasHelper.planningResourceAliases(alias)[name]
+  const commandSchema = {
+    type: 'object', properties: {
+      action: { type: 'string', enum: ['create', 'update', 'retire', 'remove', 'members', 'projects', 'assignees', 'addMember', 'removeMember', 'attach', 'detach', 'rebuild'] },
+      id: { type: 'string', minLength: 1, maxLength: 128, nullable: true },
+      version: { type: 'number', minimum: 1, nullable: true },
+      assignee: { type: 'string', minLength: 1, maxLength: 128, nullable: true },
+      project: { type: 'string', minLength: 1, maxLength: 128, nullable: true },
+      draft: { type: 'object', properties: {
+        nickname: { type: 'string', nullable: true }, kind: { type: 'string', enum: [...Object.values(AssigneeKind), null], nullable: true },
+        type: { type: 'string', nullable: true }, name: { type: 'string', nullable: true }, externalId: { type: 'string', nullable: true },
+        card: { type: 'string', nullable: true }, body: { type: 'string', nullable: true },
+        fields: { type: 'object', additionalProperties: true, required: [], nullable: true },
+        authentication: { type: 'object', properties: { provider: { type: 'string' }, externalId: { type: 'string' } }, required: ['provider', 'externalId'], additionalProperties: false, nullable: true },
+      }, required: [], additionalProperties: false, nullable: true },
+    }, required: ['action'], additionalProperties: false,
+  }
+  return Object.freeze({
+    get: protocol(route(aliases.get, `/${name}/:id`, backend({ parent: base }, RouteMethod.GET)), contract.request({ params: typed<{ id: string }>(WorkcardParamsSchema) }, typed<PlanningReply<R>>())),
+    list: protocol(route(aliases.list, `/${name}`, backend({ parent: base }, RouteMethod.GET)), contract.request({ query: typed<PlanningResourceQueryWire>({ type: 'object', properties: { query: { type: 'string', maxLength: 16384, nullable: true } }, required: [], additionalProperties: false }) }, typed<PlanningReply<ListResult<R>>>())),
+    write: protocol(route(aliases.write, `/${name}`, backend({ parent: base }, RouteMethod.POST)), contract.request({ body: typed<PlanningResourceCommand>(commandSchema as any) }, typed<PlanningReply<PlanningResourceReply>>())),
+  })
+}

package/src/resources/types.local.ts

@@ -0,0 +1,5 @@
+export interface MentionHelper {
+  encode: (id: string, nickname: string) => string
+  parse: (body: string) => string[]
+  nicknameKey: (nickname: string) => string
+}

package/src/resources/types.ts

@@ -0,0 +1,148 @@
+import type { AnySchema, ValidateFunction } from 'ajv'
+import type { ListOptions, ListResult, ResourceRecord, Criteria } from '@owlmeans/resource'
+import type { AssigneeKind } from '../consts.js'
+
+/** Identity in an external authentication domain; neither email nor nickname is its key. */
+export interface AssigneeAuthentication {
+  provider: string
+  externalId: string
+}
+
+export interface AssigneeTypeSchema {
+  type: string
+  version: number
+  kind: AssigneeKind
+  fields: AnySchema
+  authentication?: 'required' | 'optional'
+  label?: string
+  overridable?: boolean
+}
+
+export interface PlanningRecord extends ResourceRecord {
+  id?: string
+  entityId: string
+  version: number
+  createdAt: string
+  updatedAt?: string
+}
+
+export interface Assignee extends PlanningRecord {
+  nickname: string
+  /** Organization-scoped, Unicode-normalized, case-insensitive identity key. */
+  nicknameKey: string
+  kind: AssigneeKind
+  type: string
+  fields: Record<string, unknown>
+  authentication?: AssigneeAuthentication
+  retired?: boolean
+}
+
+export interface Team extends PlanningRecord {
+  name: string
+  externalId?: string
+  fields: Record<string, unknown>
+}
+
+export interface Comment extends PlanningRecord {
+  card: string
+  /** Immutable author, resolved by the host from a trusted planning scope. */
+  author: string
+  body: string
+}
+
+/** A derived mention of a stable assignee id; revision is the source comment's version. */
+export interface CommentMention extends PlanningRecord {
+  comment: string
+  card: string
+  assignee: string
+  revision: number
+}
+
+export interface AssigneeDraft {
+  nickname: string
+  kind: AssigneeKind
+  type: string
+  fields?: Record<string, unknown>
+  authentication?: AssigneeAuthentication
+}
+
+export interface TeamDraft {
+  name: string
+  externalId?: string
+  fields?: Record<string, unknown>
+}
+
+export interface CommentDraft {
+  card: string
+  body: string
+}
+
+/** Compare-and-set version is mandatory for updates/removal, optional for retiring an assignee. */
+export interface PlanningWriteOptions { version: number }
+
+export interface AssigneeQuery extends ListOptions<Assignee> {
+  ids?: string[]
+  nickname?: string
+  kind?: AssigneeKind
+  type?: string
+  authentication?: AssigneeAuthentication
+  retired?: boolean
+}
+export interface TeamQuery extends ListOptions<Team> { ids?: string[], externalId?: string }
+export interface CommentQuery extends ListOptions<Comment> { card?: string, author?: string }
+export interface MentionQuery extends ListOptions<CommentMention> { comment?: string, card?: string, assignee?: string }
+
+/** Durable versioned resource port. put expects stored version + 1, with 1 for creation. */
+export interface PlanningRecordStore<R extends PlanningRecord> {
+  get: (id: string, entityId: string) => Promise<R | null>
+  list: (where: Criteria<R>, opts?: ListOptions<R>) => Promise<ListResult<R>>
+  put: (record: R) => Promise<R>
+  drop: (id: string, entityId: string, version: number) => Promise<void>
+}
+
+export interface PlanningResourceFacade {
+  assignees: {
+    get: (id: string) => Promise<Assignee>
+    load: (id: string) => Promise<Assignee | null>
+    list: (query?: AssigneeQuery) => Promise<ListResult<Assignee>>
+    create: (draft: AssigneeDraft) => Promise<Assignee>
+    update: (id: string, changes: Partial<AssigneeDraft>, opts: PlanningWriteOptions) => Promise<Assignee>
+    retire: (id: string, opts: PlanningWriteOptions) => Promise<Assignee>
+  }
+  teams: {
+    get: (id: string) => Promise<Team>
+    load: (id: string) => Promise<Team | null>
+    list: (query?: TeamQuery) => Promise<ListResult<Team>>
+    create: (draft: TeamDraft) => Promise<Team>
+    update: (id: string, changes: Partial<TeamDraft>, opts: PlanningWriteOptions) => Promise<Team>
+    remove: (id: string, opts: PlanningWriteOptions) => Promise<void>
+    members: (team: string) => Promise<Assignee[]>
+    addMember: (team: string, assignee: string) => Promise<void>
+    removeMember: (team: string, assignee: string) => Promise<void>
+    projects: (team: string) => Promise<string[]>
+    attach: (team: string, project: string) => Promise<void>
+    detach: (team: string, project: string) => Promise<void>
+    assignees: (project: string) => Promise<Assignee[]>
+  }
+  comments: {
+    get: (id: string) => Promise<Comment>
+    load: (id: string) => Promise<Comment | null>
+    list: (query?: CommentQuery) => Promise<ListResult<Comment>>
+    create: (draft: CommentDraft) => Promise<Comment>
+    update: (id: string, changes: Pick<CommentDraft, 'body'>, opts: PlanningWriteOptions) => Promise<Comment>
+    remove: (id: string, opts: PlanningWriteOptions) => Promise<void>
+  }
+  mentions: {
+    get: (id: string) => Promise<CommentMention>
+    load: (id: string) => Promise<CommentMention | null>
+    list: (query?: MentionQuery) => Promise<ListResult<CommentMention>>
+    rebuild: (comment: string) => Promise<CommentMention[]>
+  }
+}
+
+export interface AssigneeSchemaRegistry {
+  registerAssigneeType: (schema: AssigneeTypeSchema) => void
+  assigneeType: (type: string) => AssigneeTypeSchema
+  assigneeTypes: () => AssigneeTypeSchema[]
+  assigneeValidator: (type: string) => ValidateFunction
+}

package/src/schemas.ts

@@ -1,3 +1,5 @@
+import type { AssigneeTypeSchema, Assignee, Team, Comment, CommentMention } from './resources/types.js'
+import { AssigneeKind, PlanningResourceKind, ProjectMode } from './consts.js'
 import type { JSONSchemaType } from 'ajv'
 import { IdValueSchema } from '@owlmeans/auth'
 import { createListSchema } from '@owlmeans/resource'
@@ -5,12 +7,14 @@ import type { ListResult } from '@owlmeans/resource'
 import {
   BODY_MAX, CAUSE_MAX, CODE_MAX, CodeScope, CodeStyle, CommitState, DESCRIPTION_MAX, IntrinsicPolicy,
   IntrinsicStatus, KEY_MAX, LABEL_MAX, MAX_COMMIT_POLL, MAX_LABELS, MAX_PARENTS, MAX_QUERY_LIST,
-  QUERY_TEXT_MAX, REF_MAX, SpecificationFormat, TITLE_MAX, TransitionAction, TYPE_MAX, WorkcardKind,
+  PlanningSchemaKind, QUERY_TEXT_MAX, REF_MAX, SchemaOrigin, SchemaWriteMode, SpecificationFormat,
+  TITLE_MAX, TransitionAction, TYPE_MAX, WorkcardKind,
 } from './consts.js'
 import type {
   AnyTypeSchema, CodePolicy, CommitEvent, CommitFeedQuery, CommitQuery, CommitStatus, ExecuteRequest,
-  PlanningSchemaBundle, ProjectTypeSchema, Relationship, RelationshipDraft, RelationshipQueryWire,
-  RelationshipType, RevisionsQuery, Specification, SpecificationQueryWire, SpecificationRevision,
+  PlanningAppDeclarations, PlanningSchemaBundle, ProjectTypeSchema, Relationship, RelationshipDraft, RelationshipQueryWire,
+  RelationshipType, RevisionsQuery, SchemaDefineRequest, SchemaKey, SchemaListQuery, ScopedSchemaBundle,
+  ScopedSchemaRecord, Specification, SpecificationQueryWire, SpecificationRevision,
   SpecificationRevisionList, SpecificationSlot, StatusDefinition, StatusFlowSchema,
   StatusTransitionRule, SummaryQueryWire, SummaryView, Transition, TransitionActor, TransitionCommit,
   TransitionExecution, TransitionParams, TransitionQueryWire, TransitionReceiptView, Workcard,
@@ -66,6 +70,10 @@ const workcardProperties = {
   title: { type: 'string', minLength: 1, maxLength: TITLE_MAX },
   description: { type: 'string', maxLength: DESCRIPTION_MAX, nullable: true },
   parent: OptionalId,
+  parentType: { ...TypeKey, nullable: true },
+  reporter: OptionalId,
+  assignee: OptionalId,
+  mode: { type: 'string', enum: [...Object.values(ProjectMode), null], nullable: true },
   parents: { type: 'array', maxItems: MAX_PARENTS, items: Id },
   status: Label,
   intrinsic: IntrinsicStatusSchema,
@@ -99,7 +107,7 @@ const specificationProperties = {
 /** The optional form of a schema: `nullable`, and `null` admitted by an enum too. */
 const nullable = (schema: object): object => {
   const enumerated = (schema as { enum?: unknown[] }).enum
-  return { ...schema, nullable: true, ...(enumerated != null ? { enum: [...enumerated, null] } : {}) }
+  return { ...schema, nullable: true, ...(enumerated != null ? { enum: [...new Set([...enumerated, null])] } : {}) }
 }
 
 const nullableOf = (properties: Record<string, object>): Record<string, object> =>
@@ -133,6 +141,8 @@ export const RelationshipDraftSchema = cast<RelationshipDraft>({
     type: Label,
     from: OptionalId,
     to: Id,
+    fromKind: { type: 'string', enum: [...Object.values(PlanningResourceKind), null], nullable: true },
+    toKind: { type: 'string', enum: [...Object.values(PlanningResourceKind), null], nullable: true },
     fields: OptionalOpenObject,
   },
   required: ['type', 'to'],
@@ -147,6 +157,8 @@ export const RelationshipSchema = cast<Relationship>({
     type: Label,
     from: Id,
     to: Id,
+    fromKind: { type: 'string', enum: [...Object.values(PlanningResourceKind), null], nullable: true },
+    toKind: { type: 'string', enum: [...Object.values(PlanningResourceKind), null], nullable: true },
     project: OptionalId,
     fields: OptionalOpenObject,
     createdAt: IsoDate,
@@ -164,6 +176,10 @@ export const WorkcardChangesSchema = cast<WorkcardChanges>({
     title: workcardProperties.title,
     description: workcardProperties.description,
     parent: workcardProperties.parent,
+    parentType: workcardProperties.parentType,
+    reporter: workcardProperties.reporter,
+    assignee: workcardProperties.assignee,
+    mode: workcardProperties.mode,
     parents: workcardProperties.parents,
     status: workcardProperties.status,
     intrinsic: workcardProperties.intrinsic,
@@ -260,6 +276,11 @@ export const StatusFlowSchemaSchema = cast<StatusFlowSchema>({
     statuses: { type: 'array', minItems: 1, items: StatusDefinitionSchema },
     transitions: { type: 'array', items: StatusTransitionRuleSchema },
     label: { type: 'string', maxLength: TITLE_MAX, nullable: true },
+    tone: { type: 'string', maxLength: LABEL_MAX, nullable: true },
+    icon: { type: 'string', maxLength: LABEL_MAX, nullable: true },
+    overridable: { type: 'boolean', nullable: true },
+    /** The application's own properties — their own schema is applied by `assertFlowSchema`. */
+    app: OptionalOpenObject,
   },
   required: ['id', 'version', 'statuses', 'transitions'],
   additionalProperties: false,
@@ -303,6 +324,10 @@ export const RelationshipTypeSchema = cast<RelationshipType>({
     name: Label,
     from: { type: 'array', items: TypeKey, nullable: true },
     to: { type: 'array', items: TypeKey, nullable: true },
+    fromKind: { type: 'string', enum: [...Object.values(PlanningResourceKind), null], nullable: true },
+    toKind: { type: 'string', enum: [...Object.values(PlanningResourceKind), null], nullable: true },
+    field: { ...TypeKey, nullable: true },
+    multiple: { type: 'boolean', nullable: true },
     inverse: { ...Label, nullable: true },
     single: { type: 'boolean', nullable: true },
     label: { type: 'string', maxLength: TITLE_MAX, nullable: true },
@@ -318,10 +343,17 @@ const typeProperties = {
   flows: { type: 'array', minItems: 1, items: TypeKey },
   intrinsic: nullable(IntrinsicPolicySchema),
   specifications: { type: 'array', items: SpecificationSlotSchema },
+  parents: { type: 'object', properties: { types: { type: 'array', items: TypeKey, nullable: true }, required: { type: 'boolean', nullable: true } }, required: [], additionalProperties: false, nullable: true },
+  children: { type: 'object', properties: { types: { type: 'array', items: TypeKey } }, required: ['types'], additionalProperties: false, nullable: true },
   relationships: { type: 'array', items: RelationshipTypeSchema, nullable: true },
   labels: { type: 'array', items: Label, nullable: true },
   code: { ...CodePolicySchema, nullable: true },
   label: { type: 'string', maxLength: TITLE_MAX, nullable: true },
+  tone: { type: 'string', maxLength: LABEL_MAX, nullable: true },
+  icon: { type: 'string', maxLength: LABEL_MAX, nullable: true },
+  overridable: { type: 'boolean', nullable: true },
+  /** The application's own properties — their own schema is applied by `assertTypeSchema`. */
+  app: OptionalOpenObject,
 }
 
 const typeRequired = ['type', 'kind', 'version', 'fields', 'flows', 'specifications']
@@ -343,6 +375,7 @@ export const ProjectTypeSchemaSchema = cast<ProjectTypeSchema>({
     kind: { type: 'string', enum: [WorkcardKind.Project] },
     cardTypes: { type: 'array', items: TypeKey },
     projectTypes: { type: 'array', items: TypeKey, nullable: true },
+    scopedCardTypes: { type: 'boolean', nullable: true },
   },
   required: [...typeRequired, 'cardTypes'],
   additionalProperties: false,
@@ -356,22 +389,159 @@ export const AnyTypeSchemaSchema = cast<AnyTypeSchema>({
     kind: WorkcardKindSchema,
     cardTypes: { type: 'array', items: TypeKey, nullable: true },
     projectTypes: { type: 'array', items: TypeKey, nullable: true },
+    scopedCardTypes: { type: 'boolean', nullable: true },
   },
   required: typeRequired,
   additionalProperties: false,
 })
 
+export const AssigneeTypeSchemaSchema = cast<AssigneeTypeSchema>({
+  type: 'object', properties: {
+    type: TypeKey, version: { type: 'number', minimum: 1 }, kind: { type: 'string', enum: Object.values(AssigneeKind) },
+    fields: OpenObject, authentication: { type: 'string', enum: ['required', 'optional', null], nullable: true },
+    label: { type: 'string', maxLength: TITLE_MAX, nullable: true }, overridable: { type: 'boolean', nullable: true },
+  }, required: ['type', 'version', 'kind', 'fields'], additionalProperties: false,
+})
+const planningRecordProperties = { id: OptionalId, entityId: Id, version: { type: 'number', minimum: 1 }, createdAt: IsoDate, updatedAt: OptionalIsoDate }
+const planningRecordRequired = ['entityId', 'version', 'createdAt']
+export const AssigneeSchema = cast<Assignee>({
+  type: 'object', properties: { ...planningRecordProperties,
+    nickname: { type: 'string', minLength: 1, maxLength: TYPE_MAX }, nicknameKey: TypeKey,
+    kind: { type: 'string', enum: Object.values(AssigneeKind) }, type: TypeKey, fields: OpenObject,
+    authentication: { type: 'object', properties: { provider: TypeKey, externalId: { type: 'string', minLength: 1, maxLength: REF_MAX } }, required: ['provider', 'externalId'], additionalProperties: false, nullable: true },
+    retired: { type: 'boolean', nullable: true },
+  }, required: [...planningRecordRequired, 'nickname', 'nicknameKey', 'kind', 'type', 'fields'], additionalProperties: false,
+})
+export const TeamSchema = cast<Team>({
+  type: 'object', properties: { ...planningRecordProperties, name: { type: 'string', minLength: 1, maxLength: TITLE_MAX }, externalId: { type: 'string', minLength: 1, maxLength: REF_MAX, nullable: true }, fields: OpenObject },
+  required: [...planningRecordRequired, 'name', 'fields'], additionalProperties: false,
+})
+export const CommentSchema = cast<Comment>({
+  type: 'object', properties: { ...planningRecordProperties, card: Id, author: Id, body: { type: 'string', minLength: 1, maxLength: BODY_MAX } },
+  required: [...planningRecordRequired, 'card', 'author', 'body'], additionalProperties: false,
+})
+export const CommentMentionSchema = cast<CommentMention>({
+  type: 'object', properties: { ...planningRecordProperties, comment: Id, card: Id, assignee: Id, revision: { type: 'number', minimum: 1 } },
+  required: [...planningRecordRequired, 'comment', 'card', 'assignee', 'revision'], additionalProperties: false,
+})
+
+/**
+ * The application's declarations as a bundle carries them. Each kind is an object schema whose
+ * closed form (`type`, `properties`, `required` only) `appSchemaHelper.assertDeclarations` checks.
+ */
+export const PlanningAppDeclarationsSchema = cast<PlanningAppDeclarations>({
+  type: 'object',
+  properties: { type: OptionalOpenObject, flow: OptionalOpenObject, card: OptionalOpenObject },
+  required: [],
+  additionalProperties: false,
+})
+
 export const PlanningSchemaBundleSchema = cast<PlanningSchemaBundle>({
   type: 'object',
   properties: {
     version: { type: 'number', minimum: 1 },
     types: { type: 'array', items: AnyTypeSchemaSchema },
     flows: { type: 'array', items: StatusFlowSchemaSchema },
+    assigneeTypes: { type: 'array', items: AssigneeTypeSchemaSchema, nullable: true },
+    app: { ...PlanningAppDeclarationsSchema, nullable: true },
+  },
+  required: ['version', 'types', 'flows'],
+  additionalProperties: false,
+})
+
+// ─── Data-defined (scoped) schemas ───────────────────────────────────────────────────────────────
+
+export const PlanningSchemaKindSchema = cast<PlanningSchemaKind>({ type: 'string', enum: Object.values(PlanningSchemaKind) })
+export const SchemaOriginSchema = cast<SchemaOrigin>({ type: 'string', enum: Object.values(SchemaOrigin) })
+export const SchemaWriteModeSchema = cast<SchemaWriteMode>({ type: 'string', enum: Object.values(SchemaWriteMode) })
+
+export const ScopedSchemaRecordSchema = cast<ScopedSchemaRecord>({
+  type: 'object',
+  properties: {
+    id: OptionalId,
+    entityId: Id,
+    project: OptionalId,
+    kind: PlanningSchemaKindSchema,
+    key: TypeKey,
+    version: { type: 'number', minimum: 1 },
+    /** A card type or a flow — its own schema is applied by `assertTypeSchema` / `assertFlowSchema`. */
+    definition: OpenObject,
+    retired: { type: 'boolean', nullable: true },
+    rev: { type: 'number', minimum: 0, nullable: true },
+    createdAt: IsoDate,
+    updatedAt: OptionalIsoDate,
+    by: { ...TransitionActorSchema, nullable: true },
+  },
+  required: ['entityId', 'kind', 'key', 'version', 'definition', 'createdAt'],
+  additionalProperties: false,
+})
+
+export const SchemaKeySchema = cast<SchemaKey>({
+  type: 'object',
+  properties: { kind: PlanningSchemaKindSchema, key: TypeKey },
+  required: ['kind', 'key'],
+  additionalProperties: false,
+})
+
+const originMap = () => ({ type: 'object', additionalProperties: { type: 'string', enum: Object.values(SchemaOrigin) }, required: [] })
+const keyList = () => ({ type: 'array', items: TypeKey })
+
+export const ScopedSchemaBundleSchema = cast<ScopedSchemaBundle>({
+  type: 'object',
+  properties: {
+    version: { type: 'number', minimum: 1 },
+    types: { type: 'array', items: AnyTypeSchemaSchema },
+    flows: { type: 'array', items: StatusFlowSchemaSchema },
+    assigneeTypes: { type: 'array', items: AssigneeTypeSchemaSchema, nullable: true },
+    app: { ...PlanningAppDeclarationsSchema, nullable: true },
+    scope: {
+      type: 'object',
+      properties: { entityId: Id, project: OptionalId },
+      required: ['entityId'],
+      additionalProperties: false,
+      nullable: true,
+    },
+    revision: { type: 'number', minimum: 0, nullable: true },
+    origins: {
+      type: 'object',
+      properties: { types: originMap(), flows: originMap(), assigneeTypes: { ...originMap(), nullable: true } },
+      required: ['types', 'flows'],
+      additionalProperties: false,
+      nullable: true,
+    },
+    retired: {
+      type: 'object',
+      properties: { types: keyList(), flows: keyList(), assigneeTypes: { ...keyList(), nullable: true } },
+      required: ['types', 'flows'],
+      additionalProperties: false,
+      nullable: true,
+    },
   },
   required: ['version', 'types', 'flows'],
   additionalProperties: false,
 })
 
+export const SchemaListQuerySchema = cast<SchemaListQuery>({
+  type: 'object',
+  properties: { project: OptionalId },
+  required: [],
+  additionalProperties: false,
+})
+
+export const SchemaDefineRequestSchema = cast<SchemaDefineRequest>({
+  type: 'object',
+  properties: {
+    project: OptionalId,
+    mode: nullable(SchemaWriteModeSchema),
+    types: { type: 'array', maxItems: MAX_QUERY_LIST, items: WorkcardTypeSchemaSchema, nullable: true },
+    flows: { type: 'array', maxItems: MAX_QUERY_LIST, items: StatusFlowSchemaSchema, nullable: true },
+    assigneeTypes: { type: 'array', maxItems: MAX_QUERY_LIST, items: AssigneeTypeSchemaSchema, nullable: true },
+    retire: { type: 'array', maxItems: MAX_QUERY_LIST, items: SchemaKeySchema, nullable: true },
+  },
+  required: [],
+  additionalProperties: false,
+})
+
 // ─── Execution ───────────────────────────────────────────────────────────────────────────────────
 
 export const WorkcardDraftSchema = cast<WorkcardDraft>({
@@ -380,6 +550,9 @@ export const WorkcardDraftSchema = cast<WorkcardDraft>({
     kind: WorkcardKindSchema,
     type: TypeKey,
     parent: OptionalId,
+    reporter: OptionalId,
+    assignee: OptionalId,
+    mode: workcardProperties.mode,
     parents: { ...workcardProperties.parents, nullable: true },
     title: workcardProperties.title,
     description: workcardProperties.description,
@@ -577,6 +750,8 @@ export const SpecificationQuerySchema = cast<SpecificationQueryWire>({
 export const RelationshipQuerySchema = cast<RelationshipQueryWire>({
   type: 'object',
   properties: {
+    fromKind: { type: 'string', enum: [...Object.values(PlanningResourceKind), null], nullable: true },
+    toKind: { type: 'string', enum: [...Object.values(PlanningResourceKind), null], nullable: true },
     ...listWireProperties(),
     from: listValue(),
     to: listValue(),