@owlmeans/planning 0.1.18-rc.9 → 0.1.18

package/src/helpers/query.ts

@@ -1,345 +1,175 @@
 import type { Criteria, ListOptions, ResourceRecord, Sort } from '@owlmeans/resource'
 import { IntrinsicStatus, WorkcardKind } from '../consts.js'
-import { PlanningError } from '../errors.js'
-import type {
-  IntrinsicCounts, ListWire, PlanningScope, RelationshipQuery, RelationshipQueryWire, RelationshipWhere,
-  Specification, SpecificationQuery, SpecificationQueryWire, SummaryQuery, SummaryQueryWire, SummaryView,
-  TransitionQuery, TransitionQueryWire, TransitionWhere, Workcard, WorkcardQuery, WorkcardQueryWire,
-} from '../types.js'
-
-type Scope = Pick<PlanningScope, 'entityId'>
+import type { IntrinsicCounts, RelationshipQuery, RelationshipQueryWire, RelationshipWhere, Specification, SpecificationQuery, SpecificationQueryWire, SummaryQuery, SummaryQueryWire, SummaryView, TransitionQuery, TransitionQueryWire, TransitionWhere, Workcard, WorkcardQuery, WorkcardQueryWire } from '../types.js'
+import type { QueryHelper } from './query/types.js'
+import type { Scope } from './types.local.js'
+import { wireHelper } from './wire.js'
 
 const clean = <T extends object>(record: T): T =>
   Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined)) as T
 
-/** `%`, `_` and `\` are wildcards/escapes to `$ilike`; a search text means them literally. */
-const escapeLike = (text: string): string => text.replace(/[\\%_]/g, char => `\\${char}`)
-
-/**
- * `WorkcardQuery` → `Criteria<Workcard>` — the ONE translation every store answers, so a query
- * means the same thing in memory, in Mongo and in a client mirror.
- *
- * `entityId` always comes from the scope (a query that forgot it would be a cross-tenant read);
- * `undefined` values are omitted. Paging and sorting are {@link listOptionsOf}'s.
- */
-export const criteriaOf = (query?: WorkcardQuery | null, scope?: Scope): Criteria<Workcard> => {
-  const where: Record<string, unknown> = {
-    entityId: scope?.entityId,
-    kind: query?.kind,
-    type: query?.type,
-    status: query?.status,
-    intrinsic: query?.intrinsic,
-    code: query?.code,
-    parent: query?.parent,
-    parents: query?.within != null ? { $contains: query.within } : undefined,
-    labels: query?.labels != null ? { $overlaps: query.labels } : undefined,
-    id: query?.ids != null ? { $in: query.ids } : undefined,
-    category: query?.category,
-    updatedAt: query?.updatedSince != null ? { $gte: query.updatedSince } : undefined,
-  }
-  if (query?.flow != null) {
-    where[`flows.${query.flow.id}`] = query.flow.status
-  }
-  for (const [key, value] of Object.entries(query?.fields ?? {})) {
-    if (value !== undefined) {
-      where[`fields.${key}`] = value
+export const createQueryHelper = (): QueryHelper => {
+  /** `%`, `_` and `\` are wildcards/escapes to `$ilike`; a search text means them literally. */
+  const escapeLike = (text: string): string => text.replace(/[\\%_]/g, char => `\\${char}`)
+
+  const criteriaOf = (query?: WorkcardQuery | null, scope?: Scope): Criteria<Workcard> => {
+    const where: Record<string, unknown> = {
+      entityId: scope?.entityId,
+      kind: query?.kind,
+      type: query?.type,
+      status: query?.status,
+      intrinsic: query?.intrinsic,
+      code: query?.code,
+      parent: query?.parent,
+      parents: query?.within != null ? { $contains: query.within } : undefined,
+      labels: query?.labels != null ? { $overlaps: query.labels } : undefined,
+      id: query?.ids != null ? { $in: query.ids } : undefined,
+      category: query?.category,
+      updatedAt: query?.updatedSince != null ? { $gte: query.updatedSince } : undefined,
     }
-  }
-  if (query?.q != null && query.q !== '') {
-    const like = `%${escapeLike(query.q)}%`
-    where.$or = [
-      { title: { $ilike: like } },
-      { description: { $ilike: like } },
-      { code: { $startsWith: query.q } },
-    ]
+    if (query?.flow != null) {
+      where[`flows.${query.flow.id}`] = query.flow.status
+    }
+    for (const [key, value] of Object.entries(query?.fields ?? {})) {
+      if (value !== undefined) {
+        where[`fields.${key}`] = value
+      }
+    }
+    if (query?.q != null && query.q !== '') {
+      const like = `%${escapeLike(query.q)}%`
+      where.$or = [
+        { title: { $ilike: like } },
+        { description: { $ilike: like } },
+        { code: { $startsWith: query.q } },
+      ]
+    }
+
+    return clean(where) as Criteria<Workcard>
   }
 
-  return clean(where) as Criteria<Workcard>
-}
+  const listOptionsOf = <T extends ResourceRecord>(query?: ListOptions<T> | null): ListOptions<T> => clean({
+    page: query?.page,
+    size: query?.size,
+    sort: query?.sort,
+  })
 
-/** Paging and sorting out of a query. `size: 0` (no limit) survives. */
-export const listOptionsOf = <T extends ResourceRecord>(query?: ListOptions<T> | null): ListOptions<T> => clean({
-  page: query?.page,
-  size: query?.size,
-  sort: query?.sort,
-})
+  const specCriteriaOf = (
+    parent: string, query?: SpecificationQuery | null, scope?: Scope
+  ): Criteria<Specification> => clean({
+    entityId: scope?.entityId,
+    kind: WorkcardKind.Specification,
+    parent,
+    category: query?.category,
+  }) as Criteria<Specification>
 
-/** The criteria over a parent's specifications. */
-export const specCriteriaOf = (
-  parent: string, query?: SpecificationQuery | null, scope?: Scope
-): Criteria<Specification> => clean({
-  entityId: scope?.entityId,
-  kind: WorkcardKind.Specification,
-  parent,
-  category: query?.category,
-}) as Criteria<Specification>
-
-export const linkWhereOf = (query: RelationshipQuery | null | undefined, scope: Scope): RelationshipWhere => clean({
-  entityId: scope.entityId,
-  from: query?.from,
-  to: query?.to,
-  type: query?.type,
-})
-
-export const transitionWhereOf = (query: TransitionQuery | null | undefined, scope: Scope): TransitionWhere => clean({
-  entityId: scope.entityId,
-  card: query?.card,
-  project: query?.project,
-  sinceSeq: query?.sinceSeq,
-  action: query?.action,
-  state: query?.state,
-})
-
-const emptyCounts = (): IntrinsicCounts => ({
-  total: 0, [IntrinsicStatus.Planned]: 0, [IntrinsicStatus.InProgress]: 0, [IntrinsicStatus.Closed]: 0,
-})
-
-/** Counts of DIRECT children (`card.parent`) per parent, by intrinsic state. No key for a parent with none. */
-export const summaryOf = (cards: Workcard[], parents: string[]): SummaryView => cards.reduce<SummaryView>(
-  (view, card) => {
-    if (card.parent == null || !parents.includes(card.parent)) {
-      return view
-    }
-    const counts = view[card.parent] ?? emptyCounts()
-    counts.total += 1
-    counts[card.intrinsic] = (counts[card.intrinsic] ?? 0) + 1
-    view[card.parent] = counts
-    return view
-  }, {}
-)
-
-// ─── Wire encoding ───────────────────────────────────────────────────────────────────────────────
-
-/** A list as one query value: comma-joined, or JSON when an element itself holds a comma. */
-export const encodeList = (value?: string | readonly string[] | null): string | undefined => {
-  if (value == null) {
-    return undefined
-  }
-  if (typeof value === 'string') {
-    return encodeList([value])
-  }
-  if (value.length === 0) {
-    return undefined
-  }
+  const linkWhereOf = (query: RelationshipQuery | null | undefined, scope: Scope): RelationshipWhere => clean({
+    entityId: scope.entityId,
+    from: query?.from,
+    to: query?.to,
+    type: query?.type, fromKind: query?.fromKind, toKind: query?.toKind,
+  })
 
-  return value.some(entry => entry.includes(',') || entry.startsWith('['))
-    ? JSON.stringify(value)
-    : value.join(',')
-}
+  const transitionWhereOf = (query: TransitionQuery | null | undefined, scope: Scope): TransitionWhere => clean({
+    entityId: scope.entityId,
+    card: query?.card,
+    project: query?.project,
+    sinceSeq: query?.sinceSeq,
+    action: query?.action,
+    state: query?.state,
+  })
 
-/** Every entry of a list query value, whatever shape the transport left it in. */
-export const decodeList = (value: unknown, key: string = 'list'): string[] | undefined => {
-  if (value == null || value === '') {
-    return undefined
-  }
-  if (Array.isArray(value)) {
-    const entries = value.filter(entry => entry != null && entry !== '').map(entry => `${entry}`)
-    return entries.length > 0 ? entries : undefined
-  }
-  if (typeof value !== 'string') {
-    return [`${value}`]
-  }
-  if (value.startsWith('[')) {
-    const parsed: unknown = (() => {
-      try {
-        return JSON.parse(value)
-      } catch {
-        throw new PlanningError(`malformed:query:${key}`)
+  const emptyCounts = (): IntrinsicCounts => ({
+    total: 0, [IntrinsicStatus.Planned]: 0, [IntrinsicStatus.InProgress]: 0, [IntrinsicStatus.Closed]: 0,
+  })
+
+  const summaryOf = (cards: Workcard[], parents: string[]): SummaryView => cards.reduce<SummaryView>(
+    (view, card) => {
+      if (card.parent == null || !parents.includes(card.parent)) {
+        return view
       }
-    })()
-    return Array.isArray(parsed) ? parsed.map(entry => `${entry}`) : undefined
-  }
-  const entries = value.split(',').map(entry => entry.trim()).filter(entry => entry !== '')
+      const counts = view[card.parent] ?? emptyCounts()
+      counts.total += 1
+      counts[card.intrinsic] = (counts[card.intrinsic] ?? 0) + 1
+      view[card.parent] = counts
+      return view
+    }, {}
+  )
 
-  return entries.length > 0 ? entries : undefined
+  return { criteriaOf, listOptionsOf, specCriteriaOf, linkWhereOf, transitionWhereOf, summaryOf }
 }
 
-/** A list decoded to a bare value when it holds one — the same criteria either way. */
-const decodeOneOrMany = <T extends string>(value: unknown, key: string): T | T[] | undefined => {
-  const entries = decodeList(value, key) as T[] | undefined
-  return entries == null ? undefined : entries.length === 1 ? entries[0] : entries
-}
+export const queryHelper = createQueryHelper()
 
-const encodeJson = (value: unknown): string | undefined => value == null ? undefined : JSON.stringify(value)
+/** @deprecated compat:factory-refactor — use `queryHelper.criteriaOf(…)` */
+export const criteriaOf = (query?: WorkcardQuery | null, scope?: Scope): Criteria<Workcard> =>
+  queryHelper.criteriaOf(query, scope)
 
-const decodeJson = <T>(value: unknown, key: string): T | undefined => {
-  if (value == null || value === '') {
-    return undefined
-  }
-  if (typeof value !== 'string') {
-    return value as T
-  }
-  try {
-    return JSON.parse(value) as T
-  } catch {
-    throw new PlanningError(`malformed:query:${key}`)
-  }
-}
+/** @deprecated compat:factory-refactor — use `queryHelper.listOptionsOf(…)` */
+export const listOptionsOf = <T extends ResourceRecord>(query?: ListOptions<T> | null): ListOptions<T> =>
+  queryHelper.listOptionsOf<T>(query)
 
-const decodeNumber = (value: unknown, key: string): number | undefined => {
-  if (value == null || value === '') {
-    return undefined
-  }
-  const number = typeof value === 'number' ? value : Number(value)
-  if (Number.isNaN(number)) {
-    throw new PlanningError(`malformed:query:${key}`)
-  }
+/** @deprecated compat:factory-refactor — use `queryHelper.specCriteriaOf(…)` */
+export const specCriteriaOf = (
+  parent: string, query?: SpecificationQuery | null, scope?: Scope
+): Criteria<Specification> => queryHelper.specCriteriaOf(parent, query, scope)
 
-  return number
-}
+/** @deprecated compat:factory-refactor — use `queryHelper.linkWhereOf(…)` */
+export const linkWhereOf = (query: RelationshipQuery | null | undefined, scope: Scope): RelationshipWhere =>
+  queryHelper.linkWhereOf(query, scope)
 
-const decodeBoolean = (value: unknown): boolean | undefined =>
-  value == null || value === '' ? undefined : value === true || value === 'true' || value === '1'
+/** @deprecated compat:factory-refactor — use `queryHelper.transitionWhereOf(…)` */
+export const transitionWhereOf = (query: TransitionQuery | null | undefined, scope: Scope): TransitionWhere =>
+  queryHelper.transitionWhereOf(query, scope)
 
-const decodeText = (value: unknown): string | undefined =>
-  value == null || value === '' ? undefined : `${Array.isArray(value) ? value[0] : value}`
+/** @deprecated compat:factory-refactor — use `queryHelper.summaryOf(…)` */
+export const summaryOf = (cards: Workcard[], parents: string[]): SummaryView => queryHelper.summaryOf(cards, parents)
 
-/** `[{ field: 'order' }, { field: 'updatedAt', order: 'desc' }]` ⇄ `order,-updatedAt`. */
-export const encodeSort = <T>(sort?: Sort<T>[] | null): string | undefined =>
-  sort == null || sort.length === 0 ? undefined : sort.map(entry => typeof entry === 'string'
-    ? entry
-    : `${entry.order === 'desc' ? '-' : ''}${entry.field}`).join(',')
+/** @deprecated compat:factory-refactor — use `wireHelper.encodeList(…)` */
+export const encodeList = (value?: string | readonly string[] | null): string | undefined => wireHelper.encodeList(value)
 
-export const decodeSort = <T>(value: unknown): Sort<T>[] | undefined => {
-  if (value == null || value === '') {
-    return undefined
-  }
-  const entries: unknown[] = Array.isArray(value) ? value : typeof value === 'string' ? value.split(',') : [value]
-  const sort = entries.flatMap((entry): Sort<T>[] => {
-    if (typeof entry !== 'string') {
-      return entry != null && typeof entry === 'object' && 'field' in entry ? [entry as Sort<T>] : []
-    }
-    const field = entry.trim()
-    if (field === '' || field === '-') {
-      return []
-    }
-    return field.startsWith('-')
-      ? [{ field: field.slice(1) as Sort<T> & string, order: 'desc' } as Sort<T>]
-      : [field as Sort<T>]
-  })
+/** @deprecated compat:factory-refactor — use `wireHelper.decodeList(…)` */
+export const decodeList = (value: unknown, key: string = 'list'): string[] | undefined => wireHelper.decodeList(value, key)
 
-  return sort.length > 0 ? sort : undefined
-}
+/** @deprecated compat:factory-refactor — use `wireHelper.encodeSort(…)` */
+export const encodeSort = <T>(sort?: Sort<T>[] | null): string | undefined => wireHelper.encodeSort<T>(sort)
 
-const encodeListOptions = (query?: ListOptions<any> | null): ListWire => clean({
-  page: query?.page,
-  size: query?.size,
-  sort: encodeSort(query?.sort),
-})
-
-const decodeListOptions = <T>(wire: Record<string, unknown>): ListOptions<T> => clean({
-  page: decodeNumber(wire.page, 'page'),
-  size: decodeNumber(wire.size, 'size'),
-  sort: decodeSort<T>(wire.sort),
-})
-
-const asRecord = (wire: unknown): Record<string, unknown> =>
-  wire != null && typeof wire === 'object' ? wire as Record<string, unknown> : {}
-
-export const encodeWorkcardQuery = (query?: WorkcardQuery | null): WorkcardQueryWire => clean({
-  ...encodeListOptions(query),
-  kind: encodeList(query?.kind),
-  type: encodeList(query?.type),
-  parent: query?.parent,
-  within: query?.within,
-  status: encodeList(query?.status),
-  intrinsic: encodeList(query?.intrinsic),
-  flow: encodeJson(query?.flow),
-  labels: encodeList(query?.labels),
-  code: encodeList(query?.code),
-  ids: encodeList(query?.ids),
-  fields: query?.fields != null && Object.keys(query.fields).length > 0 ? encodeJson(query.fields) : undefined,
-  q: query?.q,
-  category: encodeList(query?.category),
-  updatedSince: query?.updatedSince,
-})
-
-/** @throws {PlanningError} `malformed:query:<key>` for a value that does not decode */
-export const decodeWorkcardQuery = (wire?: WorkcardQueryWire | WorkcardQuery | null): WorkcardQuery => {
-  const value = asRecord(wire)
-  return clean({
-    ...decodeListOptions<Workcard>(value),
-    kind: decodeOneOrMany<WorkcardKind>(value.kind, 'kind'),
-    type: decodeOneOrMany(value.type, 'type'),
-    parent: decodeText(value.parent),
-    within: decodeText(value.within),
-    status: decodeOneOrMany(value.status, 'status'),
-    intrinsic: decodeOneOrMany<IntrinsicStatus>(value.intrinsic, 'intrinsic'),
-    flow: decodeJson<WorkcardQuery['flow']>(value.flow, 'flow'),
-    labels: decodeList(value.labels, 'labels'),
-    code: decodeOneOrMany(value.code, 'code'),
-    ids: decodeList(value.ids, 'ids'),
-    fields: decodeJson<Record<string, unknown>>(value.fields, 'fields'),
-    q: decodeText(value.q),
-    category: decodeOneOrMany(value.category, 'category'),
-    updatedSince: decodeText(value.updatedSince),
-  })
-}
+/** @deprecated compat:factory-refactor — use `wireHelper.decodeSort(…)` */
+export const decodeSort = <T>(value: unknown): Sort<T>[] | undefined => wireHelper.decodeSort<T>(value)
 
-export const encodeSummaryQuery = (query: SummaryQuery): SummaryQueryWire => clean({
-  parents: encodeList(query.parents) ?? '',
-  kind: query.kind,
-  type: encodeList(query.type),
-})
-
-export const decodeSummaryQuery = (wire?: SummaryQueryWire | SummaryQuery | null): SummaryQuery => {
-  const value = asRecord(wire)
-  return clean({
-    parents: decodeList(value.parents, 'parents') ?? [],
-    kind: decodeText(value.kind) as WorkcardKind | undefined,
-    type: decodeOneOrMany(value.type, 'type'),
-  })
-}
+/** @deprecated compat:factory-refactor — use `wireHelper.encodeWorkcardQuery(…)` */
+export const encodeWorkcardQuery = (query?: WorkcardQuery | null): WorkcardQueryWire => wireHelper.encodeWorkcardQuery(query)
 
-export const encodeTransitionQuery = (query?: TransitionQuery | null): TransitionQueryWire => clean({
-  ...encodeListOptions(query),
-  card: query?.card,
-  project: query?.project,
-  sinceSeq: query?.sinceSeq,
-  action: encodeList(query?.action),
-  state: query?.state,
-})
-
-export const decodeTransitionQuery = (wire?: TransitionQueryWire | TransitionQuery | null): TransitionQuery => {
-  const value = asRecord(wire)
-  return clean({
-    ...decodeListOptions(value),
-    card: decodeText(value.card),
-    project: decodeText(value.project),
-    sinceSeq: decodeNumber(value.sinceSeq, 'sinceSeq'),
-    action: decodeOneOrMany(value.action, 'action'),
-    state: decodeText(value.state),
-  }) as TransitionQuery
-}
+/** @deprecated compat:factory-refactor — use `wireHelper.decodeWorkcardQuery(…)` */
+export const decodeWorkcardQuery = (wire?: WorkcardQueryWire | WorkcardQuery | null): WorkcardQuery =>
+  wireHelper.decodeWorkcardQuery(wire)
 
-export const encodeSpecificationQuery = (query?: SpecificationQuery | null): SpecificationQueryWire => clean({
-  ...encodeListOptions(query),
-  category: encodeList(query?.category),
-  all: query?.all,
-})
-
-export const decodeSpecificationQuery = (wire?: SpecificationQueryWire | SpecificationQuery | null): SpecificationQuery => {
-  const value = asRecord(wire)
-  return clean({
-    ...decodeListOptions<Specification>(value),
-    category: decodeOneOrMany(value.category, 'category'),
-    all: decodeBoolean(value.all),
-  })
-}
+/** @deprecated compat:factory-refactor — use `wireHelper.encodeSummaryQuery(…)` */
+export const encodeSummaryQuery = (query: SummaryQuery): SummaryQueryWire => wireHelper.encodeSummaryQuery(query)
 
-export const encodeRelationshipQuery = (query?: RelationshipQuery | null): RelationshipQueryWire => clean({
-  ...encodeListOptions(query),
-  from: encodeList(query?.from),
-  to: encodeList(query?.to),
-  type: encodeList(query?.type),
-})
-
-export const decodeRelationshipQuery = (wire?: RelationshipQueryWire | RelationshipQuery | null): RelationshipQuery => {
-  const value = asRecord(wire)
-  return clean({
-    ...decodeListOptions(value),
-    from: decodeOneOrMany(value.from, 'from'),
-    to: decodeOneOrMany(value.to, 'to'),
-    type: decodeOneOrMany(value.type, 'type'),
-  }) as RelationshipQuery
-}
+/** @deprecated compat:factory-refactor — use `wireHelper.decodeSummaryQuery(…)` */
+export const decodeSummaryQuery = (wire?: SummaryQueryWire | SummaryQuery | null): SummaryQuery =>
+  wireHelper.decodeSummaryQuery(wire)
+
+/** @deprecated compat:factory-refactor — use `wireHelper.encodeTransitionQuery(…)` */
+export const encodeTransitionQuery = (query?: TransitionQuery | null): TransitionQueryWire =>
+  wireHelper.encodeTransitionQuery(query)
+
+/** @deprecated compat:factory-refactor — use `wireHelper.decodeTransitionQuery(…)` */
+export const decodeTransitionQuery = (wire?: TransitionQueryWire | TransitionQuery | null): TransitionQuery =>
+  wireHelper.decodeTransitionQuery(wire)
+
+/** @deprecated compat:factory-refactor — use `wireHelper.encodeSpecificationQuery(…)` */
+export const encodeSpecificationQuery = (query?: SpecificationQuery | null): SpecificationQueryWire =>
+  wireHelper.encodeSpecificationQuery(query)
+
+/** @deprecated compat:factory-refactor — use `wireHelper.decodeSpecificationQuery(…)` */
+export const decodeSpecificationQuery = (wire?: SpecificationQueryWire | SpecificationQuery | null): SpecificationQuery =>
+  wireHelper.decodeSpecificationQuery(wire)
+
+/** @deprecated compat:factory-refactor — use `wireHelper.encodeRelationshipQuery(…)` */
+export const encodeRelationshipQuery = (query?: RelationshipQuery | null): RelationshipQueryWire =>
+  wireHelper.encodeRelationshipQuery(query)
+
+/** @deprecated compat:factory-refactor — use `wireHelper.decodeRelationshipQuery(…)` */
+export const decodeRelationshipQuery = (wire?: RelationshipQueryWire | RelationshipQuery | null): RelationshipQuery =>
+  wireHelper.decodeRelationshipQuery(wire)

package/src/helpers/reply/consts.ts

@@ -0,0 +1 @@
+export const REPLY_CONTAINERS = new Set(['items', 'records', 'card', 'record', 'transition', 'bundle', 'scope'])

package/src/helpers/reply/types.ts

@@ -0,0 +1,13 @@
+/** Storage organization metadata is absent from planning HTTP and socket replies. */
+export type PlanningReply<T> = T extends readonly (infer R)[] ? PlanningReply<R>[]
+  : T extends object ? {
+    [K in keyof T as K extends 'entityId' ? never : K]: K extends
+      'items' | 'records' | 'card' | 'record' | 'transition' | 'bundle' | 'scope'
+      ? PlanningReply<T[K]> : T[K]
+  } : T
+
+export interface PlanningReplyHelper {
+  project: <T>(value: T) => PlanningReply<T>
+  /** Restore the shared facade shape with empty, non-authoritative organization metadata. */
+  hydrate: <T>(value: PlanningReply<T>) => T
+}

package/src/helpers/reply.ts

@@ -0,0 +1,27 @@
+import { REPLY_CONTAINERS } from './reply/consts.js'
+import type { PlanningReply, PlanningReplyHelper } from './reply/types.js'
+
+/** Project known planning envelopes; custom fields, changes and schema definitions remain opaque. */
+export const createPlanningReplyHelper = (): PlanningReplyHelper => {
+  const visit = (value: unknown, hydrate: boolean, scope = false): unknown => {
+    if (Array.isArray(value)) return value.map(item => visit(item, hydrate))
+    if (value == null || typeof value !== 'object') return value
+    const source = value as Record<string, unknown>
+    const result: Record<string, unknown> = {}
+    for (const [key, item] of Object.entries(source)) {
+      if (key === 'entityId') continue
+      result[key] = REPLY_CONTAINERS.has(key) ? visit(item, hydrate, key === 'scope') : item
+    }
+    const record = typeof source.createdAt === 'string'
+      || (typeof source.card === 'string' && typeof source.seq === 'number'
+        && (source.commit != null || typeof source.state === 'string'))
+    if (hydrate && (scope || record)) result.entityId = ''
+    return result
+  }
+  return {
+    project: <T>(value: T): PlanningReply<T> => visit(value, false) as PlanningReply<T>,
+    hydrate: <T>(value: PlanningReply<T>): T => visit(value, true) as T,
+  }
+}
+
+export const planningReplyHelper = createPlanningReplyHelper()

package/src/helpers/scoped/types.ts

@@ -0,0 +1,78 @@
+import type { AssigneeTypeSchema } from '../../resources/types.js'
+import type { PlanningSchemaKind } from '../../consts.js'
+import type {
+  PlanningAppDeclarations, PlanningSchemaBundle, PlanningSchemaRegistry, SchemaScope, ScopedSchemaBundle, ScopedSchemaRecord,
+  ScopedSchemaRegistry, StatusFlowSchema, WorkcardTypeSchema,
+} from '../../types.js'
+
+/** Data-defined (scoped) types and flows: their keys, the checks a write passes, and the layer they resolve to. */
+export interface ScopedSchemaHelper {
+  /** One layer's identity of a record: organization, project (or none), kind, key. */
+  schemaRecordKey: (record: Pick<ScopedSchemaRecord, 'entityId' | 'project' | 'kind' | 'key'>) => string
+  /** The key a declaration is addressed by: a type's `type`, a flow's `id`. */
+  schemaKeyOf: (kind: PlanningSchemaKind, definition: WorkcardTypeSchema | StatusFlowSchema | AssigneeTypeSchema) => string
+  /**
+   * Refuse a data-defined declaration of a key the code registry seals: a code type or flow that does
+   * not say `overridable: true`, and any project or specification type.
+   *
+   * @throws {SchemaSealed}
+   */
+  assertOverridable: (
+    code: Pick<PlanningSchemaRegistry, 'has' | 'type' | 'flows' | 'assigneeTypes'>, kind: PlanningSchemaKind, key: string
+  ) => void
+  /**
+   * The closed-form checks of a data-defined assignee type: the declaration's own schema and a
+   * `fields` schema that compiles.
+   *
+   * @throws {SchemaInvalid}
+   */
+  assertAssigneeTypeSchema: (schema: AssigneeTypeSchema) => void
+  /**
+   * The closed-form checks of a data-defined flow: the declaration's own schema, at least one status,
+   * unique status keys, every rule's `to` declared, a `from` that is `'*'` or a list of declared
+   * statuses, and its `app` bag against the application's `flow` declaration
+   * (`appSchemaHelper.assertBag` — refused when `app` declares none).
+   *
+   * @throws {SchemaInvalid}
+   */
+  assertFlowSchema: (flow: StatusFlowSchema, app?: PlanningAppDeclarations) => void
+  /**
+   * The closed-form checks of a data-defined type: the declaration's own schema, the `card` kind,
+   * its `app` bag against the application's `type` declaration (refused when `app` declares none),
+   * a `fields` schema that compiles together with the application's base card fields, and unique
+   * flow ids every one of which resolves.
+   *
+   * @throws {SchemaInvalid}
+   */
+  assertTypeSchema: (type: WorkcardTypeSchema, flows: Pick<PlanningSchemaRegistry, 'flow'>, app?: PlanningAppDeclarations) => void
+  /**
+   * One layer resolved: the code bundle, overlaid by the organization-wide records, then by the
+   * project's (when `scope.project` names one). Pure — every store and both sides of the wire resolve
+   * the same records to the same bundle.
+   *
+   * - A code key is sealed unless it says `overridable: true`; project and specification types are
+   *   always sealed, so only card types and flows are data-defined. A record under a sealed key is
+   *   ignored here (the write path refuses it with `SchemaSealed`).
+   * - A project record overrides an organization-wide one of the same key.
+   * - A retired record gives way to the nearest live declaration below it; a key retired in every
+   *   layer resolves retired — present in `types`/`flows`, listed in `retired`.
+   * - A data-defined declaration carries its record's `version`.
+   * - The code bundle's `app` declarations pass through as they are; a record's `app` bag is not
+   *   re-checked here (the write path checks it), so a record written under earlier declarations
+   *   still resolves.
+   */
+  resolveScopedBundle: (
+    code: PlanningSchemaBundle, records: readonly ScopedSchemaRecord[], scope: SchemaScope & { revision?: number }
+  ) => ScopedSchemaBundle
+  /**
+   * A read-only registry over a resolved layer. It answers exactly what `makeSchemaRegistry` answers
+   * for the same types and flows, plus where each key came from and whether it is retired; its
+   * `registerType`, `registerFlow` and `load` refuse with `PlanningUnsupported`.
+   */
+  scopedRegistryOf: (bundle: ScopedSchemaBundle) => ScopedSchemaRegistry
+  /**
+   * The live type that keeps a flow from being retired in a resolved layer: the flow resolves retired
+   * (no live declaration below the retired record) while a type that is not retired still runs it.
+   */
+  flowInUse: (bundle: ScopedSchemaBundle, flow: string) => string | undefined
+}