@voxgig/sdkgen 4.16.0 → 4.17.1

package/project/.sdk/tm/ts/test/live-entity.ts

@@ -0,0 +1,142 @@
+import assert from 'node:assert/strict'
+import { requestContract, synthesizeInput } from './live-contract'
+import { runLiveSteps, assertLiveReport, LiveBlocked } from './live-runner'
+import { isControlSkipped, liveDelayMs } from './utility'
+
+// The offline flow keeps its deterministic fixture assertions. Live flows
+// resolve real prerequisites per operation and collect failures until done.
+async function runLiveEntity(setup: any, entity: any, flow: any, accessor: string) {
+  const { client, transport } = setup
+  const steps: any[] = flow.step || []
+  const created = new Map<string, any>()
+  const listed: any[] = []
+  const marks = new Map<string, { name: string, value: any }>()
+  const idField = entity.id?.field || 'id'
+  const copy = (value: any) => JSON.parse(JSON.stringify(value ?? {}))
+  const hasCreate = steps.some(step => step.op === 'create')
+  const report = await runLiveSteps(steps.map((step, index) => {
+    const ref = step.input?.ref || entity.name + '_ref01'
+    const op = step.op
+    const excluded = isControlSkipped('entityOp', entity.name + '.' + op, 'live')
+    return {
+      id: entity.name + '.' + op + '.' + index,
+      cleanup: op === 'remove' || (step.valid || []).some((v: any) => v.apply === 'ItemNotExists'),
+      excluded: excluded.skip ? excluded.reason || 'Excluded by test control' : undefined,
+      run: async (context: any) => {
+        transport.enter(context)
+        const points = entity.op?.[op]?.points || []
+        if (!points.length) throw new LiveBlocked('No modelled operation point')
+        const record = created.get(ref)
+        // A failed create must not turn a later update/remove into a write
+        // against an arbitrary record found by a list operation.
+        if ((op === 'update' || op === 'remove') && hasCreate && !record) {
+          throw new LiveBlocked('Create did not provide a usable resource')
+        }
+        if (op === 'remove' && !record) throw new LiveBlocked('No resource created by this run')
+        if (op === 'remove' && !entity.id) throw new LiveBlocked('No modelled resource identity for cleanup')
+        if (record && ['update', 'remove'].includes(op) && entity.id &&
+            null == (record[idField] ?? record.id)) {
+          throw new LiveBlocked('Created resource has no usable identity')
+        }
+
+        let input: any = op === 'create'
+          ? copy(setup.data.new?.[entity.name]?.[ref]) : {}
+        for (const [name, binding] of Object.entries({ ...step.match, ...step.data })) {
+          const value = setup.idmap[binding as string] ?? setup.idmap[name]
+          if (undefined !== value) input[name] = value
+        }
+        const loaded = record || (op === 'load' ? listed[0] : undefined)
+        if (loaded && ['load', 'update', 'remove'].includes(op)) {
+          const id = loaded[idField] ?? loaded.id
+          if (undefined !== id) input.id = id
+        }
+        // A nested route needing a parent id must not hide an available
+        // parameter-free route for the same operation. Use the first viable
+        // candidate; the SDK still performs its normal route selection.
+        let resolved: any
+        let selected: any
+        const missing = new Set<string>()
+        for (const point of points) {
+          if (point.select?.$action !== input.$action) continue
+          const candidate = { ...input }
+          let viable = true
+          const params = point.args?.params || []
+          const query = (point.args?.query || []).filter((arg: any) => arg.reqd)
+          for (const arg of [...params, ...query]) {
+            if (undefined !== candidate[arg.name] && null !== candidate[arg.name]) continue
+            const key = arg.name === 'id' ? entity.name + '01' : arg.name.replace(/_id$/, '') + '01'
+            const value = setup.idmap[key] ?? setup.idmap[arg.name] ?? loaded?.[arg.name] ?? arg.example
+            if (undefined !== value && null !== value) candidate[arg.name] = value
+            else if (arg.reqd !== false) { viable = false; missing.add(arg.name) }
+          }
+          if (viable) { resolved = candidate; selected = point; break }
+        }
+        if (!resolved) throw new LiveBlocked('No usable route; missing arguments: ' + [...missing].join(', '))
+        input = resolved
+        if (op === 'create' && selected.contract) {
+          const facts = JSON.parse(selected.contract.json)
+          const request = requestContract(facts)
+          if (request.schema) input = { ...synthesizeInput(request.schema, facts.live?.input ?? request.example) }
+          else if (facts.protocol === 'http') input = {}
+          for (const arg of selected.args?.params || []) if (resolved[arg.name] !== undefined) input[arg.name] = resolved[arg.name]
+        }
+        let intendedMark: { name: string, value: any } | undefined
+        if (op === 'update') {
+          for (const spec of step.spec || []) {
+            if (spec.apply === 'TextFieldMark' && step.input?.textfield) {
+              const mark = { name: step.input.textfield, value: spec.def.mark + '_' + setup.now }
+              input[mark.name] = mark.value
+              intendedMark = mark
+            }
+          }
+        }
+
+        // A fresh entity prevents state left by a failed operation from
+        // changing the request for the next independent operation.
+        const result = await client[accessor]()[op](input)
+        if (intendedMark) marks.set(ref, intendedMark)
+        if (op === 'list') {
+          assert(Array.isArray(result), 'Expected a list of entity instances')
+          const data = result.map((item: any) => {
+            assert.equal(typeof item?.data, 'function')
+            return item.data()
+          })
+          listed.splice(0, listed.length, ...data)
+          context.publish(data)
+          for (const validation of step.valid || []) {
+            const previous = created.get(validation.def?.ref)
+            const id = previous?.[idField] ?? previous?.id
+            if (undefined === id) continue
+            const found = data.some((item: any) => (item?.[idField] ?? item?.id) === id)
+            if (validation.apply === 'ItemExists') assert(found, 'Created resource missing from list')
+            if (validation.apply === 'ItemNotExists') assert(!found, 'Removed resource still in list')
+          }
+        }
+        else {
+          assert.equal(typeof result?.data, 'function', 'Expected an entity instance')
+          const data = result.data()
+          assert(null != data, 'Expected operation data')
+          // Publish before assertion checks: cleanup still needs the id
+          // when the server created a resource with incorrect field values.
+          if (op === 'create') created.set(ref, data)
+          context.publish(data)
+          if (op === 'create' && entity.id) assert(null != (data[idField] ?? data.id), 'Missing created identity')
+          if (['load', 'update'].includes(op) && input.id != null && entity.id) {
+            assert.equal(data[idField] ?? data.id, input.id, 'Response identity mismatch')
+          }
+          const mark = marks.get(ref)
+          if (mark && ['update', 'load'].includes(op)) {
+            assert.equal(data[mark.name], mark.value, 'Updated field mismatch')
+          }
+        }
+      },
+    }
+  }), {
+    delayMs: liveDelayMs(),
+    report: result => console.log('LIVE STEP ' + JSON.stringify(result)),
+  })
+  console.log('LIVE SUMMARY ' + JSON.stringify({ entity: entity.name, ...report }))
+  assertLiveReport(report)
+}
+
+export { runLiveEntity }

package/project/.sdk/tm/ts/test/live-runner.ts

@@ -0,0 +1,166 @@
+// Execute every independent live step before deciding the suite's result.
+// Values never appear in reports: they can contain credentials or API data.
+
+type LiveState = 'passed' | 'failed' | 'blocked' | 'excluded'
+
+type LiveResult = {
+  id: string
+  state: LiveState
+  attempted: boolean
+  role?: string
+  retention?: string
+  reason?: string
+  requests?: { method: string, path: string, status?: number }[]
+}
+
+type LiveContext = {
+  values: Map<string, any>
+  publish(value: any): void
+  attempted(): void
+  requests: { method: string, path: string, status?: number }[]
+}
+
+type LiveStep = {
+  id: string
+  needs?: string[]
+  cleanup?: boolean
+  role?: string
+  retention?: string
+  excluded?: string
+  run(ctx: LiveContext): Promise<void>
+}
+
+class LiveBlocked extends Error {}
+
+type LiveReport = {
+  planned: number
+  attempted: number
+  passed: number
+  failed: number
+  blocked: number
+  excluded: number
+  results: LiveResult[]
+}
+
+async function runLiveSteps(
+  steps: LiveStep[],
+  options: { delayMs?: number, report?: (result: LiveResult) => void } = {},
+): Promise<LiveReport> {
+  const values = new Map<string, any>()
+  const results: LiveResult[] = []
+  const ids = new Set<string>()
+  for (const step of steps) {
+    if (!step.id || ids.has(step.id)) throw new Error('Duplicate or empty live step id')
+    ids.add(step.id)
+  }
+
+  const record = (result: LiveResult) => {
+    const step = steps.find(step => step.id === result.id)
+    if (step?.role) result.role = step.role
+    if (step?.retention && result.attempted) result.retention = step.retention
+    results.push(result)
+    options.report?.(result)
+  }
+
+  // Cleanup runs after ordinary work, even if an assertion failed after a
+  // resource was created. A step publishes usable data before assertions.
+  for (const cleanup of [false, true]) {
+    const pending = steps.filter(step => !!step.cleanup === cleanup)
+    while (pending.length) {
+      let progressed = false
+      for (let i = 0; i < pending.length;) {
+        const step = pending[i]
+        const missing = (step.needs || []).filter(id => !values.has(id) ||
+          (!cleanup && results.some(result => result.id === id && result.state !== 'passed')))
+        if (!step.excluded && missing.some(id => pending.some(other => other.id === id))) {
+          i++
+          continue
+        }
+        pending.splice(i, 1)
+        progressed = true
+        if (step.excluded) {
+          record({ id: step.id, state: 'excluded', attempted: false, reason: step.excluded })
+          continue
+        }
+        if (missing.length) {
+          record({ id: step.id, state: 'blocked', attempted: false,
+            reason: 'Missing output: ' + missing.join(', ') })
+          continue
+        }
+        let attempted = false
+        const requests: LiveContext['requests'] = []
+        try {
+          await step.run({
+            values,
+            publish: value => { if (undefined !== value) values.set(step.id, value) },
+            attempted: () => { attempted = true },
+            requests,
+          })
+          if (!attempted) throw new LiveBlocked('No request attempted')
+          record({ id: step.id, state: 'passed', attempted, requests })
+        }
+        catch (error) {
+          // Ordinary SDK errors can contain request headers, bodies, or an
+          // issued token. Report the step's failure without serializing it.
+          record({ id: step.id, state: error instanceof LiveBlocked ? 'blocked' : 'failed',
+            attempted, requests,
+            reason: error instanceof LiveBlocked ? error.message : 'Request or assertion failed' })
+        }
+        if (attempted && (options.delayMs || 0) > 0) {
+          await new Promise(resolve => setTimeout(resolve, options.delayMs))
+        }
+      }
+      if (!progressed) {
+        for (const step of pending.splice(0)) {
+          record({ id: step.id, state: 'blocked', attempted: false,
+            reason: 'Cyclic or unavailable dependency' })
+        }
+      }
+    }
+  }
+
+  return {
+    planned: steps.length,
+    attempted: results.filter(result => result.attempted).length,
+    passed: results.filter(result => result.state === 'passed').length,
+    failed: results.filter(result => result.state === 'failed').length,
+    blocked: results.filter(result => result.state === 'blocked').length,
+    excluded: results.filter(result => result.state === 'excluded').length,
+    results,
+  }
+}
+
+function assertLiveReport(report: LiveReport): void {
+  if (report.failed || report.blocked || !report.attempted) {
+    throw new Error('Live coverage incomplete: ' + JSON.stringify(report))
+  }
+}
+
+function createLiveTransport(timeoutMs = 30000) {
+  let context: LiveContext | undefined
+  const requests: LiveContext['requests'] = []
+  const nativeFetch = globalThis.fetch
+  return {
+    requests,
+    enter(next: LiveContext) { context = next },
+    fetch: async (input: any, init?: any) => {
+      const url = new URL(String(input))
+      const request: LiveContext['requests'][number] = {
+        method: init?.method || 'GET', path: url.origin + url.pathname,
+      }
+      requests.push(request)
+      context?.requests.push(request)
+      context?.attempted()
+      if (!context) console.log('LIVE REQUEST ' + JSON.stringify(request))
+      const timeout = AbortSignal.timeout(timeoutMs)
+      const signal = init?.signal ? AbortSignal.any([init.signal, timeout]) : timeout
+      const response = await nativeFetch(input, { ...init, signal })
+      request.status = response.status
+      if (!context) console.log('LIVE RESPONSE ' + JSON.stringify(request))
+      return response
+    },
+  }
+}
+
+export { runLiveSteps, assertLiveReport, LiveBlocked, createLiveTransport }
+export type { LiveStep, LiveContext, LiveReport, LiveResult }

package/project/.sdk/tm/ts/test/live-scenarios.ts

@@ -0,0 +1,112 @@
+import assert from 'node:assert/strict'
+import { LiveBlocked, runLiveSteps, assertLiveReport, createLiveTransport } from './live-runner'
+import { requestContract, synthesizeInput, validateContract } from './live-contract'
+import { liveClientOptions, liveDelayMs, isControlSkipped } from './utility'
+
+const at = (value: any, path?: string): any => (path || '').split('.').filter(Boolean).reduce((v, k) => v?.[k], value)
+export function resolveRecipe(recipe: any, values: Map<string, any>): any {
+  if (Array.isArray(recipe)) return recipe.map(v => resolveRecipe(v, values))
+  if (recipe && typeof recipe === 'object') {
+    if (recipe.from) {
+      if (!values.has(recipe.from)) throw new LiveBlocked('Missing recipe output: ' + recipe.from)
+      let value = values.get(recipe.from)
+      if (recipe.where) {
+        if (!Array.isArray(value)) throw new LiveBlocked('Discovery output is not a list')
+        value = value.find((item: any) => Object.entries(recipe.where).every(([k, v]) => at(item, k) === v) &&
+          (!recipe.related || (values.get(recipe.related.from) || []).some((other: any) =>
+            at(item, recipe.related.local) === at(other, recipe.related.foreign) &&
+            Object.entries(recipe.related.where || {}).every(([k, v]) => at(other, k) === v))))
+      }
+      value = at(value, recipe.path)
+      if (value === undefined || value === null) throw new LiveBlocked('Discovery found no compatible value')
+      return value
+    }
+    return Object.fromEntries(Object.entries(recipe).map(([k, v]) => [k, resolveRecipe(v, values)]))
+  }
+  return recipe
+}
+
+export function recipeNeeds(value: any): string[] {
+  if (!value || typeof value !== 'object') return []
+  return [...new Set([...(typeof value.from === 'string' ? [value.from] : []), ...Object.values(value).flatMap(recipeNeeds)])]
+}
+
+export async function runLiveScenarios(SDK: any, plan: any[], envPrefix: string, liveDefaults: any = {}) {
+  const transport = createLiveTransport()
+  const steps = plan.map(point => {
+    const hint = point.facts.live || {}
+    const control = isControlSkipped('entityOp', point.entity + '.' + point.op, 'live')
+    return { role: hint.auth || (point.facts.security?.length === 0 || point.facts.securitySource === 'unspecified' ? 'public' : 'account'), retention: hint.retention, id: hint.id || point.id, needs: [...new Set([...(hint.needs || []), ...recipeNeeds(hint.input), ...recipeNeeds(hint.credential), ...recipeNeeds(hint.assert)])] as string[],
+      cleanup: !!hint.cleanup,
+      excluded: control.skip ? control.reason || 'Excluded by test control' : hint.excluded,
+      run: async (ctx: any) => {
+        transport.enter(ctx)
+        if (point.contractVersion && point.contractVersion !== 1) throw new LiveBlocked('Unsupported operation contract version')
+        if (point.op === 'remove' || hint.cleanup) {
+          const owned = recipeNeeds(hint.input).some(id => plan.some(source =>
+            (source.facts.live?.id || source.id) === id && source.entity === point.entity && source.op === 'create'))
+          if (!owned) throw new LiveBlocked('Cleanup input is not bound to a resource created by this run')
+        }
+        if (!point.reachable) throw new LiveBlocked('Point selector is indistinguishable; add a guide action')
+        const request = requestContract(point.facts)
+        const explicit = hint.input === undefined ? request.example : resolveRecipe(hint.input, ctx.values)
+        let input = request.schema ? synthesizeInput(request.schema, explicit) : explicit ?? {}
+        for (const kind of ['params', 'query', 'header', 'cookie']) for (const arg of point.args?.[kind] || []) {
+          if (arg.reqd && input[arg.name] === undefined) {
+            if (arg.example === undefined) throw new LiveBlocked('Missing required argument: ' + arg.name)
+            input[arg.name] = arg.example
+          }
+        }
+        const role = hint.auth || (point.facts.security?.length === 0 || point.facts.securitySource === 'unspecified' ? 'public' : 'account')
+        let apikey = role === 'public' ? null : role === 'issued' ? resolveRecipe(hint.credential, ctx.values) : process.env[envPrefix + '_APIKEY']
+        if (role === 'issued' && (typeof apikey !== 'string' || !apikey)) throw new LiveBlocked('Issued credential unavailable')
+        let wire: any
+        let wireSchema: any
+        const options = liveClientOptions()
+        const client = new SDK({ ...options, ...liveDefaults, apikey,
+          feature: { ...options.feature, test: { active: false }, retry: { active: false },
+            secrets: { ...options.feature?.secrets, active: role === 'account' && (!apikey || options.feature?.secrets?.active === true) } },
+          system: { ...options.system, fetch: async (url: any, init: any) => {
+            const headers = new Headers(init?.headers)
+            if (role === 'public') assert(!headers.has('authorization'), 'Public request carries authentication')
+            else if (!headers.get('authorization')) throw new LiveBlocked('Credential unavailable for ' + role + ' request')
+            const response = await transport.fetch(url, { ...init, redirect: 'error' })
+            const expectedPath = point.path.replace(/\{([^}]+)\}/g, (_: string, name: string) => encodeURIComponent(input[point.rename?.param?.[name] || name] ?? input[name]))
+            if (point.kind === 'graphql') {
+              const payload = JSON.parse(init.body)
+              assert.equal(payload.query, point.graphql.doc, 'Entity selected wrong GraphQL operation')
+            } else assert.equal(new URL(String(url)).pathname, expectedPath, 'Entity selected wrong route')
+            assert.equal(init?.method || 'GET', point.method)
+            assert(response.status >= 200 && response.status < 300, 'Unsuccessful HTTP response')
+            if (point.kind === 'graphql') wire = await response.clone().json()
+            const def = point.facts.responses?.[response.status] || point.facts.responses?.[String(response.status)[0] + 'XX'] || point.facts.responses?.default
+            if (point.facts.responses && !def) throw new Error('Undeclared response status')
+            if (def) {
+              const schema = def.content?.['application/json']?.schema ?? def.schema
+              if (schema && response.status !== 204) { wireSchema = schema; wire = await response.clone().json() }
+            }
+            return response
+          } } })
+        if (point.action) input = { ...input, $action: point.action }
+        assert(JSON.stringify(input).length <= 1024 * 1024, 'Request exceeds test payload limit')
+        const result = await client[point.accessor]()[point.op](input)
+        const data = Array.isArray(result) ? result.map(item => { assert.equal(typeof item?.data, 'function'); return item.data() }) : (assert.equal(typeof result?.data, 'function'), result.data())
+        ctx.publish(data)
+        if (wireSchema) validateContract(wireSchema, wire, 'response')
+        if (Array.isArray(wire?.errors) && wire.errors.length) throw new Error('GraphQL operation reported errors')
+        if (wire?.success === false) throw new Error('API reported unsuccessful operation')
+        const checks = resolveRecipe(hint.assert || {}, ctx.values)
+        for (const [path, expected] of Object.entries(checks.equal || {})) assert.deepEqual(at(data, path), expected)
+        for (const path of checks.nonempty || []) assert(at(data, path)?.length > 0, 'Empty required output')
+        if (checks.vectors) {
+          const vectors = at(data, checks.vectors.path)
+          assert(Array.isArray(vectors) && vectors.length === checks.vectors.count)
+          for (const vector of vectors) assert(Array.isArray(vector) && vector.length === checks.vectors.dimension && vector.every((n: any) => typeof n === 'number' && Number.isFinite(n)), 'Invalid vector shape')
+        }
+      } }
+  })
+  const report = await runLiveSteps(steps, { delayMs: liveDelayMs(), report: result => console.log('LIVE STEP ' + JSON.stringify(result)) })
+  console.log('LIVE SUMMARY ' + JSON.stringify(report))
+  assertLiveReport(report)
+  return report
+}

package/project/.sdk/tm/ts/test/utility.ts

@@ -161,8 +161,7 @@ function skipIfMissingIds(t: any, setup: any, requiredKeys: string[]): boolean {
   if (!setup.live) return false
   const missing = requiredKeys.filter(k => null == setup.idmap?.[k])
   if (missing.length > 0) {
-    t.skip(`live test needs ${missing.join(', ')} via *_ENTID env var (synthetic IDs only)`)
-    return true
+    throw new Error(`Live test blocked: needs ${missing.join(', ')} via *_ENTID env var`)
   }
   return false
 }

package/project/sdkgen-package.json

@@ -3,7 +3,7 @@
     "package": 1
   },
   "name": "@voxgig/sdkgen",
-  "version": "4.16.0",
+  "version": "4.17.1",
   "provides": {
     "target": [
       "c",

package/src/action/action.ts

@@ -102,7 +102,7 @@ function parseAddNames(args: any[]): string[] {
 // `seed` IS THE UPGRADE PATH. A project scaffolded before a kind existed has
 // no `model/<kind>/<kind>-index.aon` — every project alive today is in
 // exactly that position for `docs` — and reading it unguarded made the FIRST
-// `docs add` in any existing project fail on ENOENT before it wrote anything.
+// `edition add` in any existing project fail on ENOENT before it wrote anything.
 //
 // Seeded per call rather than defaulted for every kind: a missing
 // `target-index.aon` in a scaffolded project is a broken project, and
@@ -136,7 +136,7 @@ function loadContent(
 // indexes of the kinds that existed then. So a project scaffolded before a
 // kind existed — which is every project alive today, for `docs` — never
 // includes its index, and the item's model file is an orphan: it is on disk,
-// `<kind>-index.aon` includes it, and NOTHING includes that. `main.kit.docs`
+// `<kind>-index.aon` includes it, and NOTHING includes that. `main.kit.doc.edition`
 // is then absent from the compiled model, so `package list`, `package update`
 // and `doctor` cannot see the item at all.
 //

package/src/action/check.ts

@@ -1,3 +1,4 @@
+import { kindCollection } from '../helpers/kindCollection'
 // `package check` — the AUTHOR-side battery. Design §14.
 //
 // WHAT IT IS FOR
@@ -308,11 +309,11 @@ function checkDefinition(
   //    `main: kit: target: go:` installs an item the consumer's model never
   //    sees — the exact mistake a package author makes copying a bundled
   //    target as a starting point.
-  const declared = strict.model?.main?.[KIT]?.[kind]?.[name]
+  const declared = kindCollection(strict.model, kind)?.[name]
 
   if (null == declared || 'object' !== typeof declared) {
     found.push(at('error', 'model-key-missing',
-      'declares no `main: kit: ' + kind + ': ' + name + ':` block — the file ' +
+      'declares no `main: kit: ' + (kind === 'edition' ? 'doc: edition' : kind) + ': ' + name + ':` block — the file ' +
       'is installed and included under its own name, so nothing it declares ' +
       'under another name is reachable'))
   }

package/src/action/dispatch.ts

@@ -1,7 +1,7 @@
 // WHAT `voxgig-sdkgen <action> …` CAN BE.
 //
 // Built FROM THE KIND REGISTRY rather than hand-listed, so registering a kind
-// is the only edit a new kind needs — `docs add …` costs no dispatch code
+// is the only edit a new kind needs — `edition add …` costs no dispatch code
 // (docs/design/sdkgen-packages.md §9). The `package` and `doctor` verbs are
 // not kinds and are added beside it.
 //
@@ -25,7 +25,7 @@ import { KINDS } from './kind'
 
 import { action_target, target_add } from './target'
 import { action_feature, feature_add } from './feature'
-import { action_docs, docs_add } from './docs'
+import { action_edition, edition_add } from './edition'
 import { action_doctor } from './doctor'
 import { action_package, registerAdder } from './package'
 
@@ -41,7 +41,7 @@ const KIND_ACTIONS: Record<string, ActionFunc> = Object.assign(
   Object.create(null), {
   target: action_target,
   feature: action_feature,
-  docs: action_docs,
+  edition: action_edition,
 })
 
 
@@ -49,7 +49,7 @@ const KIND_ACTIONS: Record<string, ActionFunc> = Object.assign(
 // over. Registered rather than imported by `package.ts`, for the cycle above.
 registerAdder('target', target_add)
 registerAdder('feature', feature_add)
-registerAdder('docs', docs_add)
+registerAdder('edition', edition_add)
 
 
 function actionMap(): Record<string, ActionFunc> {

package/src/action/doctor.ts

@@ -1,3 +1,4 @@
+import { kindCollection } from '../helpers/kindCollection'
 // `voxgig-sdkgen doctor` — does this project's `.sdk/` still match the
 // scaffold?
 //
@@ -276,7 +277,7 @@ async function doctor(
 
   const counts: Record<string, number> = {}
   for (const kind of kinds) {
-    counts[kind] = Object.keys((model as any)?.main?.[KIT]?.[kind] ?? {}).length
+    counts[kind] = Object.keys(kindCollection(model, kind) ?? {}).length
   }
 
   log.info({ point: 'doctor-start', targets: counts.target ?? 0, ...counts })
@@ -303,7 +304,7 @@ async function doctor(
   }
 
   for (const kind of kinds) {
-    const items = Object.keys((model as any)?.main?.[KIT]?.[kind] ?? {}).sort()
+    const items = Object.keys(kindCollection(model, kind) ?? {}).sort()
 
     for (const name of items) {
       if (null != scope && !scope(kind, name)) {
@@ -321,8 +322,8 @@ async function doctor(
         checkTarget(actx, source, report)
       }
 
-      if ('docs' === kind) {
-        checkDocs(actx, source, report)
+      if ('edition' === kind) {
+        checkEdition(actx, source, report)
       }
 
       // Only an ACTIVE feature has source copied out; what an inactive one
@@ -433,7 +434,7 @@ function checkWiring(actx: ActionContext, report: DoctorReport) {
 function resolveDeclared(
   kind: string, name: string, actx: ActionContext,
 ): Source | undefined {
-  const declared: any = (actx.model as any)?.main?.[KIT]?.[kind]?.[name]
+  const declared: any = kindCollection(actx.model, kind)?.[name]
   const ref = recordedRef(declared, name) || name
 
   try {
@@ -659,8 +660,8 @@ function compareTrees(
 // rather than being spelled a second time.
 //
 // The optional template tree is skipped when the SOURCE does not ship one:
-// `docs add` did not copy it, so the project is right not to have it.
-function checkDocs(
+// `edition add` did not copy it, so the project is right not to have it.
+function checkEdition(
   actx: ActionContext, resolved: Source, report: DoctorReport,
 ) {
   const fs = actx.fs()
@@ -669,8 +670,8 @@ function checkDocs(
   const origname = resolved.origname
   const aliased = name !== origname
 
-  const dest = kindTrees('docs', name)
-  const from = kindTrees('docs', origname)
+  const dest = kindTrees('edition', name)
+  const from = kindTrees('edition', origname)
 
   const trees: TreeCompare[] = dest.flatMap((tree: TreeDef, i: number) => {
     const scaffold = Path.join(resolved.folder, ...from[i].path.split('/'))