@voxgig/sdkgen 4.21.0 → 4.23.0

package/src/helpers/shipped.ts

@@ -1,16 +1,3 @@
-// WHERE THIS GENERATOR'S OWN FILES ARE, resolved from the compiled code.
-//
-// Every other path in `action/` is relative to the PROJECT being operated on
-// — `node_modules/@voxgig/sdkgen/project/.sdk` is how a consumer reaches the
-// bundled scaffold, and that is correct there. `package check` has no project:
-// it is run by an AUTHOR against a package that may sit anywhere, and it
-// still needs this generator's base schema (to unify against) and its feature
-// catalogue (to know which names denote features). Those come from the
-// installation doing the checking, which is this one.
-//
-// `__dirname` is `dist/helpers` in the shipped package, so the package root is
-// two levels up. The authoritative schema lives directly in its model/
-// directory, in both a checkout and an installed package.
 
 import Path from 'node:path'
 
@@ -20,7 +7,6 @@ function packageRoot(): string {
 }
 
 
-// The base model schema — `@voxgig/sdkgen/model/sdkgen.aon`.
 function schemaFile(): string {
   return Path.join(packageRoot(), 'model', 'sdkgen.aon')
 }

package/src/helpers/station.ts

@@ -1,26 +1,3 @@
-// The station SELF-REGISTRATION seam (station design station.md §9 /
-// station-declarative-config.md §6.2 path 1, §11 item 2): when the station
-// feature is installed and active, the generated MAIN module registers the
-// SDK's `{construct, config}` factory pair with the station library at
-// module init, so `station.sdk('<name>')` needs no imports in application
-// code. The registration key is the descriptor slug — `config.main.slug`,
-// the same field station's `normalizeDescriptor` reads — so the generated
-// code passes the embedded config's own value rather than re-deriving it.
-//
-// This helper answers the ONE question every Main_<lang> asks before
-// emitting that registration: is the station feature ACTIVE in this model,
-// and what is the station library package for this target? Both come from
-// the model — the active-filtered feature map (exactly the view the Main
-// components already emit from) and the station feature's own
-// `deps.<target>` block, which is the same entry `collectDeps` flows into
-// the generated manifest. ONE RULE, ONE PLACE: reading the package name
-// here, never hardcoding it per language, means the manifest dependency
-// and the emitted require can not disagree.
-//
-// Returns undefined when the station feature is absent, inactive, or
-// declares no active station library dep for this target (the vendored
-// targets carry the library inside their tm overlay instead of as a dep —
-// station.md §9.2): no dep, no package to require, no registration to emit.
 
 import { each } from 'jostraca'
 
@@ -35,9 +12,6 @@ import type { SdkModel, ModelFeature } from '../types'
 
 
 function stationLibrary(model: SdkModel, targetName: string): string | undefined {
-  // Active-filtered on purpose: an inactive feature ships no source, no
-  // embedded config entry and no manifest dep, so it must emit no
-  // registration either.
   const feature = getModelPath(model, `main.${KIT}.feature`,
     { required: false }) || {}
 
@@ -56,12 +30,6 @@ function stationLibrary(model: SdkModel, targetName: string): string | undefined
 
   if (0 === names.length) { return undefined }
 
-  // EXACTLY ONE, or say so. Picking the first of several — each() sorts,
-  // so it would be the alphabetically first — means the generated main
-  // can `require` an unrelated helper package, find no `provide`, and
-  // leave the factory table silently empty. The station feature model
-  // declares one library per target; a second active dep is a model
-  // question only its author can answer.
   if (1 < names.length) {
     throw new SdkGenError(
       'station: feature `station` declares ' + names.length + ' active ' +

package/src/helpers/stdrep.ts

@@ -1,24 +1,7 @@
-// Replacement keys the GENERATOR owns, merged into the project's `ctx$.stdrep`.
-//
-// `stdrep` itself is built by the consumer's `Root.ts`
-// (`names(ctx$.stdrep, model.Name, 'ProjectName')`), which lives outside this
-// package and is frozen at project-init time — so a new placeholder cannot be
-// added there without every existing project resyncing its root wiring. These
-// are added here instead, immediately before the templates that use them are
-// copied, so an old project gets them without touching its scaffold.
 
 import { envName, packageVersion } from './packageMeta'
 
 
-// PROJECTENV — the env-var base for this SDK's `<BASE>_TEST_LIVE`,
-// `<BASE>_APIKEY` and friends.
-//
-// NOT `PROJECTNAME`. That one is the camel-cased class name uppercased, which
-// SWALLOWS a hyphen: `voxgig-solardemo` becomes `VOXGIGSOLARDEMO`, while every
-// component-generated env var reads `VOXGIG_SOLARDEMO`. Both spellings used to
-// reach the same generated SDK — `test/utility.ts` (a template) read one and
-// `PlanetEntity.test.ts` (a component) the other — so setting either variable
-// sent half the suite live and left the rest mocked, green either way.
 function ensureStdrep(ctx$: any): any {
   const stdrep = ctx$.stdrep = (ctx$.stdrep || {})
 
@@ -30,14 +13,6 @@ function ensureStdrep(ctx$: any): any {
 }
 
 
-// The substitutions `target add` applies when it copies a target's TEMPLATE
-// tree (tm/<t>).
-//
-// ONE definition, because two consumers must agree exactly: `target add`
-// writes the files, and `doctor` re-applies these to the scaffold before
-// comparing, to tell a substitution artefact from a real hand-edit. When
-// PROJECTVERSION was added to the writer alone, every project's VERSION file
-// immediately read as an edited master.
 function templateReplacements(model: any, tname: string): Record<string, string> {
   return {
     ProjectName: model?.const?.Name,
@@ -50,42 +25,15 @@ function templateReplacements(model: any, tname: string): Record<string, string>
 }
 
 
-// PROVENANCE — where a copied target or feature came from.
-//
-// Every shipped model file carries a `base: 'BASE'` line as an ANCHOR, and
-// the add actions rewrite that one line into the block the copy keeps:
-//
-//   base: 'BASE'   ->   base: 'node_modules/@acme/sdkgen-iot/.sdk'
-//                       origname: 'iot-go'
-//
-// The anchor is why every shipped model needs the line even though most
-// installs are unaliased from the bundled scaffold: a `replace` map can only
-// rewrite text that is already there, and there is nowhere else to hang the
-// keys that do not appear in the source.
-//
-// ONE definition, for the same reason templateReplacements is one: `target
-// add` and `feature add` WRITE with this map and `doctor` re-applies it to
-// the scaffold before comparing. A writer and a reader that disagree by a
-// single character make every project read as forked.
-//
-// `origname` and `package` are emitted only when they apply, so an ordinary
-// install still records exactly one line and its model file is unchanged
-// from what earlier versions wrote — apart from the base value itself.
 type Provenance = {
-  // The `.sdk` folder the copy came from, project-relative and
-  // '/'-normalised (see resolveTarget).
   base: string
 
-  // The name in the SOURCE and the name it was INSTALLED as. Equal for an
-  // ordinary add; different for `target add go~go2`.
   origname?: string
   name?: string
 
-  // The sdkgen package that provided it, when the source declared one.
   package?: string
 }
 
-// Two spaces, matching every shipped model file's indentation for these keys.
 const PROVENANCE_INDENT = '  '
 
 

package/src/helpers/testPolicy.ts

@@ -1,9 +1,5 @@
 import { KIT } from '../types'
 
-// Live requests assert success by default. This never enables fail-fast:
-// independent tests continue and their framework aggregates the failures.
-// An explicit false preserves the legacy exploratory policy for callers
-// migrating a fleet; it must not be confused with full live verification.
 function liveStrict(model: any, target?: string): boolean {
   const perTarget = null == target ? undefined :
     model?.main?.[KIT]?.target?.[target]?.test?.live?.strict

package/src/sdkgen.ts

@@ -25,7 +25,7 @@ import { Main } from './cmp/Main'
 import { featureApplies, targetFeatures, featureTags, unknownTags, TAGS } from './helpers/applicability'
 import { ExternalTarget } from './cmp/ExternalTarget'
 
-import { KIT } from '@voxgig/apidef'
+import { KIT, resolvedSpec } from '@voxgig/apidef'
 import { Deploy } from './cmp/Deploy'
 import { Entity } from './cmp/Entity'
 import { Feature } from './cmp/Feature'
@@ -53,9 +53,11 @@ import { ReadmeRef } from './cmp/ReadmeRef'
 import { ReadmeRefFeatures } from './cmp/ReadmeRefFeatures'
 import { FeatureHook } from './cmp/FeatureHook'
 import { registerComponent } from './cmp/Registered'
+
+import { resolvedFor, liveHint, pointFacts, hasLiveScenarios } from './helpers/resolved'
 import type { RegisterOptions } from './cmp/Registered'
 
-import { buildIdNames } from './helpers/buildIdNames'
+import { buildIdNames, entityRelationName, flowSteps } from './helpers/buildIdNames'
 import { getMatchEntries } from './helpers/getMatchEntries'
 import { collectDeps } from './helpers/collectDeps'
 import { guardModelNames } from './helpers/modelNames'
@@ -157,7 +159,6 @@ import { ACTION_MAP, actionNames, needsModel } from './action/dispatch'
 
 
 
-// TODO: use shape
 type SdkGenOptions = {
   folder: string
   fs: any
@@ -174,7 +175,6 @@ type SdkGenOptions = {
   pino?: any, // ReturnType<typeof Pino>
   now?: () => number
 
-  // TODO: match Jostraca
   existing?: {
     txt?: any
     bin?: any
@@ -182,27 +182,10 @@ type SdkGenOptions = {
 
   dryrun?: boolean
 
-  // WHERE AN OUT-OF-TREE ITEM GOES, DECIDED AT GENERATE TIME RATHER THAN IN
-  // THE MODEL. Keyed by item name:
-  //
-  //   external: { 'seneca-provider': { path: '../..', sdkrel: '.sdksrc/acme-sdk', enclosing: true } }
-  //
-  // `output: path` in the model is a fact about ONE developer's checkout
-  // layout, and it is committed. The same model generated from a different
-  // layout is the same model — a different INVOCATION of it, not a second
-  // truth to encode — so the second layout belongs here and not in a second
-  // committed value that the two layouts then fight over.
-  //
-  // The case that forced it: a provider repo that carries a tagged checkout
-  // of its SDK in a subfolder and regenerates itself from it. The SDK's own
-  // committed model cannot describe that, because the SDK does not know it
-  // has been cloned into someone else's repo.
   external?: Record<string, ExternalOverride>
 }
 
 
-// See SdkGenOptions.external. `enclosing` is separate from `path` on
-// purpose — see checkExternalFolders.
 type ExternalOverride = {
   path?: string
   sdkrel?: string
@@ -213,20 +196,6 @@ type ExternalOverride = {
 const { Jostraca } = JostracaModule
 
 
-// A BROKEN PROJECT MODEL IS THE USER'S FILE, NOT A CRASH.
-//
-// One constructor for both routes out of `resolveModel` — the throw aontu
-// actually takes, and the `errs` array it documents but never fills — because
-// two spellings of the same error is how this repo keeps reintroducing the
-// same defect.
-//
-// aontu's own diagnostic is the valuable part and is passed through
-// UNTOUCHED: it carries the source excerpt, a caret under the offending
-// token, and an explanation. What it lacks is any statement of WHOSE file
-// this is, so the path leads. Wrapping it in an SdkGenError is what makes the
-// CLI print it as a message instead of dumping the error object and a stack
-// trace through sdkgen's internals — `handleError` reserves clean output for
-// that name.
 function modelError(path: string, cause: any, rooterrs: any[]): any {
   const detail = String(cause?.msg ?? cause?.message ?? cause ?? '').trim()
 
@@ -252,8 +221,6 @@ function SdkGen(opts: SdkGenOptions) {
   const folder = opts.folder || '../'
   const now = opts.now || (() => Date.now())
 
-  // Per-instance cache of the Aontu model loader. Previously a module-level
-  // global, which leaked the (relative) preload across SdkGen instances.
   let aontu: any = null
 
   const jopts = {
@@ -261,16 +228,6 @@ function SdkGen(opts: SdkGenOptions) {
     control: {
       dryrun: opts.dryrun
     },
-    // Generated SDK output is fully model-derived and never hand-edited, so
-    // OVERWRITE existing files on regenerate (jostraca's default). Do NOT enable
-    // the 3-way `merge` here: it merges against a `.jostraca` base that drifts
-    // from the toolchain, which (a) silently KEEPS a stale generated file when a
-    // template adds a field a newer component references (-> `undefined: X`
-    // compile errors, e.g. Control.Actor / Result.Stream), and (b) injects
-    // `<<<<<<<` conflict markers when a generated/index file is touched, which
-    // then break downstream parsers (aontu) and compilers. Overwrite makes
-    // generation deterministic: same model -> byte-stable output.
-    // See docs/explanation/regeneration-overwrite.md.
     existing: {
       txt: {
         write: true,
@@ -294,6 +251,7 @@ function SdkGen(opts: SdkGenOptions) {
     const start = Date.now()
     const { model, config } = spec
 
+
     log.info({ point: 'generate-start', start, note: opts.dryrun ? '** DRY RUN **' : '' })
     log.debug({ point: 'generate-spec', spec })
 
@@ -316,12 +274,11 @@ function SdkGen(opts: SdkGenOptions) {
       fs: () => fs,
       folder,
       log: log.child({ cmp: 'jostraca' }),
-      meta: { spec },
+      // apidef publishes the resolved definition on the model build's
+      // context; jostraca merges `meta` into every component's ctx$, and
+      // docgen is handed these same options.
+      meta: { spec, apidef: resolvedSpec(spec.buildctx) },
       debug: opts.debug,
-      // Respect the caller's `existing` policy (the .sdk/build/sdkgen.js action
-      // config). SDK output should be OVERWRITE, not 3-way merge — that is set
-      // at the scaffold source (create-sdkgen build/sdkgen.js: existing.txt =
-      // { write:true, merge:false }); see docs/explanation/regeneration-overwrite.md.
       existing: opts.existing,
       // Per-call, for the same reason the actions pass it: jostraca applies
       // OptionsShape to `generate`'s own options first, so its
@@ -334,14 +291,6 @@ function SdkGen(opts: SdkGenOptions) {
       cmp: copyOpts(),
     }
 
-    // Targets that write OUTSIDE the SDK repo (`output: path`) are generated
-    // by their own pass, rooted at that path — see cmp/ExternalTarget for why
-    // a folder name cannot do this. The in-tree pass must not see them, or
-    // the consumer Root would also emit them into `<sdk-repo>/<target>/`.
-    //
-    // `folder` may be relative (a consumer's build passes '..' from `.sdk`),
-    // so resolve it ONCE: every destination is compared against it, and a
-    // comparison between a relative and an absolute path is meaningless.
     const root = Path.resolve(folder)
 
     const externalOverride = resolveExternalOverride(opts, log)
@@ -353,9 +302,6 @@ function SdkGen(opts: SdkGenOptions) {
       externalItems(model, root, ['target'], externalOverride)
         .map((ext) => ({ ...ext, skip: externalSkipReason(ext, fs) }))
 
-    // Before ANY file is written, in-tree included: a destination that turns
-    // out to be wrong must abort the whole generation, not leave half of it
-    // done. See checkExternalFolders.
     checkExternalFolders(external, root, fs)
 
     const jres = await jostraca.generate(
@@ -373,16 +319,6 @@ function SdkGen(opts: SdkGenOptions) {
     }
 
     for (const ext of external) {
-      // A skipped external target is still removed from the in-tree model
-      // above: neither `active: false` nor a missing `output.create: false`
-      // destination may relocate it into `<sdk-repo>/<target>/`.
-      // The snapshot is deliberately not re-taken to ADMIT an item: a
-      // destination that appeared since would be written without ever having
-      // been ownership-validated. Re-taking it to SKIP one is the opposite
-      // direction and cannot open that hole. Without this, an optional
-      // destination deleted or moved between the snapshot and this pass is
-      // recreated by jostraca's ensureDir — exactly what `output.create:
-      // false` promises not to do.
       const gone = false === ext.target.output?.create && !fs.existsSync(ext.folder)
 
       if (null != ext.skip || gone) {
@@ -422,23 +358,6 @@ function SdkGen(opts: SdkGenOptions) {
   }
 
 
-  // Action arguments are PATHS AND NAMES, and they reach the actions as the
-  // raw strings the shell gave us.
-  //
-  // They used to be mapped through `Jsonic(arg)` first, which parses each one
-  // as relaxed JSON — so a Windows absolute ref arrived as an OBJECT:
-  // `Jsonic('C:\\pkg\\go')` is `{ C: '\\pkg\\go' }`, and every downstream path
-  // join then missed. (`ts,py` also became `['ts','py']`, which is why
-  // parseAddNames still carries a non-string branch; it splits on commas
-  // itself, so nothing is lost by handing it strings.)
-  //
-  // Nothing here wants structured arguments: every action takes names and
-  // refs. Parsing them was pure loss.
-  //
-  // `flags` is the second parameter because `--only` and `--alias` are
-  // arguments to ONE command, not generator configuration: passing them
-  // through `SdkGen({…})` like `debug`/`dryrun` would make a later
-  // `action()` call on the same instance silently inherit them.
   async function action(
     args: string[], flags?: Record<string, any>,
   ): Promise<any> {
@@ -461,7 +380,6 @@ function SdkGen(opts: SdkGenOptions) {
     flags?: Record<string, any>, wantmodel?: boolean,
   ): ActionContext {
 
-    // TODO: use AsyncLocalStorage to avoid reloading model
     const { model, url } = resolveModel(false !== wantmodel)
 
     const ctx: ActionContext = {
@@ -498,21 +416,6 @@ function SdkGen(opts: SdkGenOptions) {
     const aopts = { path, errs }
     const src = fs.readFileSync(path, 'utf8')
 
-    // AONTU THROWS; IT DOES NOT FILL `errs`.
-    //
-    // The `errs` array is handed to `generate` and stays empty on every
-    // failure — syntax, unresolved path and unify conflict alike all raise an
-    // AontuError instead (verified against 0.52 by running each). So the
-    // `0 < errs.length` branch this used to have could never fire, and every
-    // broken project model reached the CLI as a bare AontuError: `handleError`
-    // prints the raw object for anything that is not an SdkGenError, so the
-    // user got aontu's diagnostic followed by a stack trace into sdkgen's
-    // `dist/` and a dump of the error's own fields. It read as an sdkgen
-    // crash rather than a problem in their own file.
-    //
-    // The array is still passed, and still checked below, because that is
-    // aontu's documented option and a later version may start using it. Both
-    // routes build the error the same way, so they cannot drift.
     let model: any
 
     try {
@@ -628,7 +531,6 @@ function SdkGen(opts: SdkGenOptions) {
 
 SdkGen.makeBuild = async function(opts: SdkGenOptions) {
   let sdkgen: any = undefined
-  // let apidef: any = undefined
 
   const config = {
     root: opts.root,
@@ -647,8 +549,7 @@ SdkGen.makeBuild = async function(opts: SdkGenOptions) {
       })
     }
 
-    // await apidef.generate({ model, build, config })
-    return await sdkgen.generate({ model, build, config })
+    return await sdkgen.generate({ model, build, config, buildctx: ctx })
   }
 }
 
@@ -677,35 +578,6 @@ type ExternalPlan = ExternalSpec & {
 }
 
 
-// Targets declaring `output: path` — generated into their own repo rather
-// than into `<sdk-repo>/<target>/`.
-//
-// A relative path resolves against the SDK repo root, so a sibling checkout
-// is '../<repo>'. That is deliberately the SAME base the generator writes
-// everything else against: a path in the model should not depend on the
-// directory the command happened to be run from.
-//
-// An INACTIVE target is still listed: it must be taken out of the in-tree
-// model (see withoutExternal) so that switching it off does not silently
-// relocate it into `<sdk-repo>/<target>/`. The generate loop skips it.
-// The generate-time override of where out-of-tree items are written.
-//
-// Two ways in, merged, the environment winning:
-//
-//   opts.external     the caller holds the config — a build script it owns.
-//   SDKGEN_EXTERNAL   JSON, for driving a checkout the caller does NOT own.
-//
-// The environment matters more than it looks. The case this exists for is a
-// repository that carries a tagged checkout of its SDK and regenerates
-// itself from it: the script doing that owns neither the SDK's model nor its
-// `.sdk/build/sdkgen.js`, so any route that requires editing a file inside
-// the checkout means patching someone else's repo on every clone — and the
-// point of the exercise was that the clone is disposable.
-//
-// ONE JSON VARIABLE, not one variable per item per field. Item names carry
-// hyphens (`seneca-provider`), so a
-// `SDKGEN_EXTERNAL_SENECA_PROVIDER_PATH` scheme needs a name mangling with
-// no inverse: `a-b` and `a_b` collide, and nothing can tell which was meant.
 function resolveExternalOverride(
   opts: SdkGenOptions, log: any,
 ): Record<string, ExternalOverride> {
@@ -805,18 +677,6 @@ function externalItems(
 }
 
 
-// Why this external item should not get a generation pass RIGHT NOW.
-//
-// `active: false` disables the target itself. `output.create: false` does
-// something deliberately narrower: the target stays active in the model but
-// an absent destination is treated as an optional checkout rather than a
-// folder sdkgen should fabricate. If that repo is checked out later, the same
-// unchanged model generates it normally.
-//
-// Snapshotted into ExternalPlan because both the pre-write destination guard
-// and the actual pass must make the identical decision. If the guard skipped
-// an item that the pass did not, generation could write outside the project
-// without any of the ownership checks below.
 function externalSkipReason(ext: ExternalSpec, fs: any): string | null {
   if (!ext.active) {
     return ext.name + ' inactive, not generated'
@@ -838,53 +698,12 @@ function externalSkipReason(ext: ExternalSpec, fs: any): string | null {
 // has been generated into already, whoever set it up.
 const EXTERNAL_MARKER = '.jostraca'
 
-// Entries that do not count as content when deciding whether a destination
-// is empty. A `git init` (or a clone of an empty repo) leaves only `.git`, and
-// that is exactly the destination a FIRST generation is aimed at — as is one
-// the maintainer opened in the Finder on the way to declaring it.
-//
-// `isNoise`, not `isJunk`: a destination holding build output is not empty,
-// whether or not sdkgen would ever copy such a thing. See helpers/junk.
-
-
-// Refuse a destination the project cannot have meant.
-//
-// The external pass is the one code path that writes outside the repo it was
-// pointed at, at a filesystem path taken verbatim from the model — and
-// generation is overwrite, not merge, while jostraca's ensureDir creates
-// missing parents. So a mistyped `output: path` does not fail: it fabricates
-// a package tree at an arbitrary location, or overwrites an unrelated repo's
-// package.json, README.md, LICENSE and CI workflow in place. The only trace
-// was one INFO line naming the resolved folder.
-//
-// A destination must therefore be:
-//   - outside the SDK project, in BOTH directions — inside it is what a
-//     typo like '.' or 'ts' produces (and the external pass runs SECOND, so
-//     it wins over what the in-tree pass just wrote), while a destination
-//     that CONTAINS the project is what '..' produces;
-//   - claimed by no other target;
-//   - and either absent, empty, or carrying the marker a previous
-//     generation left there.
-//
-// Anything else is refused with both paths named. NOT skipped: a project
-// generating somewhere other than it believes must be told. A destination
-// that legitimately holds other content first (a repo seeded with a README
-// and LICENCE) says so once in the model, with `output: adopt: true`.
+
+
 function checkExternalFolders(external: ExternalPlan[], root: string, fs: any) {
   const claimed: Record<string, string> = {}
 
   for (const ext of external) {
-    // An INACTIVE item writes nothing and claims nothing: it is out of the
-    // model for this run.
-    //
-    // An item skipped only because its optional destination is absent is a
-    // different case. Path containment and the duplicate claim are model
-    // invariants — they do not depend on folder contents — so skipping them
-    // here let two items claim one absent path: the ordinary one generated
-    // there, and the NEXT identical run then saw the folder, detected the
-    // duplicate, and refused everything. The failure appeared one run after
-    // the mistake. Validate the path; the `existsSync` guard below still
-    // skips every check that reads the folder.
     if (!ext.active) continue
 
     const label = ext.kind.charAt(0).toUpperCase() + ext.kind.slice(1)
@@ -901,22 +720,6 @@ function checkExternalFolders(external: ExternalPlan[], root: string, fs: any) {
         ext.name + '/.')
     }
 
-    // A DESTINATION THAT CONTAINS THE PROJECT is what `..` produces, and it
-    // is refused — UNLESS the caller said at generate time that it meant it.
-    //
-    // The legitimate case is a repository that carries a tagged checkout of
-    // its SDK in a subfolder and regenerates itself from it: the SDK then
-    // sits INSIDE its own output folder, and `output: path` resolves to an
-    // ancestor. Generation writes the files its components declare and
-    // prunes nothing, so the checkout survives its own run.
-    //
-    // `enclosing` is a separate flag from `path` on purpose, and only the
-    // override can set it — never the model. Overriding a path is one
-    // decision; writing over the directory holding the project is a second,
-    // much worse thing to get wrong, and it fails silently: a typo'd `..`
-    // fabricates a package tree over an unrelated repo, overwriting its
-    // package.json, README, LICENSE and CI in place. Saying it twice is the
-    // cost of keeping the typo caught for everyone who did not ask.
     if (folderContains(ext.folder, root) && !ext.enclosing) {
       throw new SdkGenError(
         'External output path contains the SDK project.\n  ' + where +
@@ -949,18 +752,6 @@ function checkExternalFolders(external: ExternalPlan[], root: string, fs: any) {
 
     if (true === ext.target.output.adopt) continue
 
-    // AN ENCLOSING DESTINATION ALWAYS HOLDS CONTENT: the SDK project itself
-    // is inside it, along with whatever else the repository carries. The
-    // emptiness check can therefore only ever say "yes, it has content", so
-    // it carries no information here — and requiring `output: adopt` on top
-    // of the opt-in would put the layout back in the SDK's COMMITTED model,
-    // which is the coupling the generate-time override exists to break. An
-    // SDK cloned into a repository it regenerates cannot have anticipated
-    // being cloned there.
-    //
-    // The containment check above is what guards this case, and it is
-    // stricter: it refuses unless the caller named this item and said
-    // `enclosing` for it.
     if (ext.enclosing) continue
 
     const entries: string[] = fs.readdirSync(ext.folder)
@@ -994,24 +785,6 @@ function folderContains(folder: string, path: string): boolean {
 }
 
 
-// The path from the destination back to the SDK project, which the target's
-// own docs, scripts and live tests name (the companion test server lives in
-// the SDK repo and is not published).
-//
-// It is DERIVED from the two resolved folders by default, which is only
-// honest while the walk back crosses nothing the model does not name. It
-// does not for `output: path: '../<repo>'`; it does for anything ascending
-// further. voxgig-solardemo-sdk declares '../../seneca/solardemo-provider'
-// and the derived inverse came out as '../../voxgig-sdk/voxgig-solardemo-sdk'
-// — where `voxgig-sdk` is the name of the WORKSPACE DIRECTORY holding the SDK
-// checkout on one machine, no part of the model. That string is committed
-// into the destination's README.md and three test files, so a second
-// developer with the same two repos under a differently named parent
-// regenerates a spurious diff in tracked files and an instruction path that
-// is wrong on the first machine.
-//
-// So a project that ascends further declares the walk back explicitly, as
-// `output: sdkrel`, and is warned until it does.
 function externalSdkRel(ext: ExternalSpec, root: string, log: any): string {
   const declared = String(ext.target.output?.sdkrel || '')
   if ('' !== declared) return declared
@@ -1023,13 +796,6 @@ function externalSdkRel(ext: ExternalSpec, root: string, log: any): string {
   // earlier one is a directory ABOVE it, which nothing in the model declares.
   const named = derived.split('/').filter((seg) => '..' !== seg)
 
-  // NOT WHEN THE OUTPUT ENCLOSES THE PROJECT. There the walk back descends
-  // rather than ascends — `.sdksrc/acme-sdk` names the subfolder holding the
-  // checkout and then the checkout, both INSIDE the output folder and both
-  // chosen by whoever asked for this layout. Nothing is above anything, so
-  // the warning's complaint (directories the model does not declare) is
-  // false, and its advice (declare `output: sdkrel`) would put one layout's
-  // path into the other's committed model.
   if (ext.enclosing) {
     return derived
   }
@@ -1049,15 +815,6 @@ function externalSdkRel(ext: ExternalSpec, root: string, log: any): string {
 }
 
 
-// The model the IN-TREE pass sees: the same model with the out-of-tree
-// targets taken out.
-//
-// A shallow clone down to `target` only — the model is large, entities and
-// features are shared with the external pass, and a deep copy would both
-// cost and quietly break identity comparisons.
-// The model the IN-TREE pass sees: every out-of-tree item removed, whatever
-// its kind. Rendering one in both passes would ALSO write it into
-// `<sdk-repo>/<name>/`, which is the folder the item asked not to use.
 function withoutExternal(
   model: any, external: { kind: string, name: string }[],
 ): any {
@@ -1147,13 +904,6 @@ export type {
 type Component = (props: any, children?: any) => void
 
 
-// Prevents TS2742
-// `typeof` rather than a hand-written signature: jostraca 0.38 made cmp
-// generic, `<P, Arg, Child>(component: (props: CmpProps<P>, ...) => any) =>
-// Component<P, Arg, Child>`, and the old annotation `(component: Function) =>
-// Component` no longer matched it. Deferring to the module's own type keeps
-// this correct across jostraca versions AND still names the type, which is
-// what prevented TS2742 in the first place.
 export const cmp: typeof JostracaModule.cmp = JostracaModule.cmp
 export const names: (base: any, name: string, prop?: string) => any = JostracaModule.names
 export const each: (subject?: any, apply?: any) => any = JostracaModule.each
@@ -1213,6 +963,10 @@ export {
   ReadmeRefFeatures,
   FeatureHook,
   registerComponent,
+  resolvedFor,
+  liveHint,
+  pointFacts,
+  hasLiveScenarios,
 
   Jostraca,
   SdkGen,
@@ -1238,11 +992,11 @@ export {
   SdkGenError,
 
   buildIdNames,
+  entityRelationName,
+  flowSteps,
   getMatchEntries,
   collectDeps,
 
-  // apidef ADR-003: the model carries typed path segments, not braced
-  // strings. Scaffold components read the path through these.
   pointSegments,
   pointParts,
   pointTerminalParam,