@voxgig/sdkgen 4.21.0 → 4.23.0

package/project/.sdk/src/cmp/lua/EntityTypes_lua.ts

@@ -1,20 +1,5 @@
 
 
-// Typed-model generator (Lua target).
-//
-// Lua is dynamically typed, so the "types" are LuaLS annotations
-// (---@class / ---@field) for editor/tooling DX only — no runtime effect.
-//
-// Reads main.<KIT>.entity.<e>.fields[] and per-op params
-// (op.<name>.points[].args.params[]) and emits one file, <sdk>_types.lua,
-// with a `---@class <Name>` per active entity plus a request/match ---@class
-// per active op. Field/param sentinels ($STRING, $INTEGER, ...) are turned
-// into LuaLS types by the shared sdkgen helper `canonToType` ('lua' column).
-//
-// Keeps the SAME type-name scheme as the TS reference (<Name>,
-// <Name>LoadMatch, <Name>ListMatch, <Name>CreateData, <Name>UpdateData,
-// <Name>RemoveMatch). The op fragments reference these class names via
-// ---@param / ---@return.
 
 import {
   cmp, each, names,
@@ -32,8 +17,6 @@ import {
 const LANG = 'lua'
 
 
-// A bare LuaLS field key, or a bracketed string literal for anything that is
-// not a plain Lua identifier.
 function propKey(name: string): string {
   return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ? name : '[' + JSON.stringify(name) + ']'
 }
@@ -43,10 +26,6 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
   const { target } = props
   const { model, log } = props.ctx$
 
-  // only_active:false — getModelPath DROPS active:false entries by default,
-  // but the consumer scaffold (create-sdkgen Root.ts) iterates the RAW entity
-  // collection, so inactive entities still get generated entity code that
-  // references these typed names. The typed model must cover them too.
   const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
   // Emit for EVERY entity that gets generated entity code: the consumer
   // scaffold (create-sdkgen Root.ts) iterates entities WITHOUT an active
@@ -58,17 +37,14 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
   // entity not yet named (e.g. a fieldless placeholder) would otherwise read
   // `Name = undefined` below. Parity with the go emitter's fix.
 
-  // Surface duplicate generated type names (two entities with the same
-  // PascalCase Name) — they would redeclare a type in statically-typed
-  // targets. Detection only; renaming is a model-level decision.
   warnEntityTypeCollisions(entity, log, LANG)
 
   File({ name: model.name + '_types.' + (target.ext || LANG) }, () => {
 
     Content(`-- Typed models for the ${model.const.Name} SDK (LuaLS annotations).
 --
--- GENERATED from the API model: main.${KIT}.entity.<e>.fields[] and per-op
--- params (op.<name>.points[].args.params[]). Field/param types come from the
+-- GENERATED from the API model: main.${KIT}.entity.<e>.fields{} and per-op
+-- params (op.<name>.points[].g.params[]). Field/param types come from the
 -- canonical type sentinels via @voxgig/sdkgen canonToType (source of truth:
 -- @voxgig/apidef VALID_CANON). Annotations only — no runtime effect. Do not
 -- edit by hand.
@@ -78,22 +54,18 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
     entityList.forEach((ent: any) => {
       const Name = ent.Name
       const fields = (ent.fields ? each(ent.fields) : [])
-        .filter((f: any) => f.active !== false)
+        .filter((f: any) => f.a !== false)
 
-      // Entity data model: one ---@field per field, `req:false` -> optional (?).
       Content(`---@class ${Name}
 `)
       fields.forEach((f: any) => {
-        const opt = false === f.req ? '?' : ''
-        Content(`---@field ${propKey(f.name)}${opt} ${canonToType(f.type, LANG)}
+        const opt = false === f.r ? '?' : ''
+        Content(`---@field ${propKey(f.n)}${opt} ${canonToType(f.t, LANG)}
 `)
       })
       Content(`
 `)
 
-      // Per active op: a request/match class. Members and their optionality
-      // come from the shared partiality policy (opRequestShape); this file only
-      // renders them as LuaLS ---@field lines.
       const ops = ent.op || {}
       ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
         if (null == ops[opname]) {
@@ -115,8 +87,6 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
       })
     })
 
-    // Make the file a require-able (empty) module. The blank line above keeps
-    // LuaLS from binding the last ---@class to this local.
     Content(`local M = {}
 
 return M

package/project/.sdk/src/cmp/lua/Entity_lua.ts

@@ -35,7 +35,6 @@ const Entity = cmp(function Entity(props: any) {
 
   const ff = Path.normalize(__dirname + '/../../../src/cmp/lua/fragment/')
 
-  // Entity files go to entity/ folder
   Folder({ name: 'entity' }, () => {
 
     File({ name: entity.name + '_entity.' + target.ext }, () => {
@@ -58,14 +57,8 @@ const Entity = cmp(function Entity(props: any) {
           EntityName: entity.Name,
           entityname: entity.name,
 
-          // Class token decoupled from the EntityName data-type token in
-          // Entity.fragment.lua so the class can be renamed independently.
           EntyClass: cls,
 
-          // Feature-hook wiring: the built-in `#Name-Hook` tag replacement
-          // is hardwired to `//` line comments, so Lua's `-- #PrePoint-Hook`
-          // markers were never matched and no pipeline hooks fired in
-          // generated code. Match the Lua-comment hook tags explicitly.
           '/(?<indent>[ \\t]*)-- #(?<name>[A-Za-z0-9]+)-Hook[ \\t]*\\n?/':
             ({ name, indent }: any) =>
               `${indent}utility.feature_hook(ctx, "${name}")\n`,

package/project/.sdk/src/cmp/lua/Main_lua.ts

@@ -29,15 +29,6 @@ import { MainEntity } from './MainEntity_lua'
 import { EntityTypes } from './EntityTypes_lua'
 
 
-// Features whose source is a CONTAINER under the top-level feature/ dir,
-// beside the flat `<name>_feature.lua` every other lua feature is. Today
-// that is `secrets`: its folder holds a vendored @voxgig/sekreto port, the
-// voxgig/plugin runtime and the C transport helper - some forty files of
-// key-store, request-signing and child-process code that an SDK which never
-// asked for secrets must not ship. Anything named here is EXCLUDED from the
-// verbatim copy unless the model SELECTS the feature (see the Copy below);
-// its shipped test suite under test/feature/<name>/ goes with it. The
-// clojure target gates its container the same way (Main_clojure.ts).
 const CONTAINED = ['secrets']
 
 
@@ -56,12 +47,6 @@ const Main = cmp(async function Main(props: any) {
 
   Gitignore({})
 
-  // THE feature/<name>/ CONTAINER IS GATED HERE, at generate time - the
-  // top-level-container peer of the `srcFeatureExcludes` gate ts and js
-  // apply to src/feature/<name>/. `target add` keeps an unselected
-  // feature out of a project's tm/ in the first place; this covers a
-  // feature switched off after it was added, and the generator suite,
-  // which copies the whole scaffold tree.
   const containerExcludes = CONTAINED
     .filter((name: string) => null == feature[name])
     .flatMap((name: string) => [
@@ -70,13 +55,6 @@ const Main = cmp(async function Main(props: any) {
       new RegExp('(^|/)test/feature/' + name + '/'),
     ])
 
-  // Copy tm/lua files with replacements.
-  //
-  // pluginExcludes: the generate-time plugin trim (an ACTIVE feature's
-  // INACTIVE plugin group's declared files stay out of the tree). The
-  // model's lua `path` entries are target-root-relative, which is this
-  // Copy's root - helpers/featureSource documents that getting the root
-  // wrong makes the trim a silent no-op.
   Copy({
     from: 'tm/' + target.name,
     exclude: [/src\//, TEST_CONTROL_EXCLUDE,
@@ -86,29 +64,6 @@ const Main = cmp(async function Main(props: any) {
     }
   })
 
-  // THE NATIVE BUILD SEAM. sekreto's lua PLUGIN kinds (hashicorp, aws, ...)
-  // run a small compiled transport helper, because Lua 5.4 has no sockets
-  // and no TLS; the four built-in kinds never reach it. The helper's
-  // source is vendored with the feature (feature/secrets/native/
-  // sekretonet.c) and the template Makefile `-include`s this fragment, so
-  // it is compiled - and OpenSSL linked - ONLY when the model activates a
-  // plugin group that lua has definitions for. An SDK without secrets, or
-  // with the built-in chain alone, gets no fragment, no compiler run and
-  // no OpenSSL dependency.
-  //
-  // The vendored file opens with the vendoring tool's three-line `--`
-  // provenance header (every file under tm/lua is stamped in lua's comment
-  // syntax; the guard holds that), which the C compiler cannot read - so
-  // the rule feeds the compiler from line four. Line numbers in a compiler
-  // diagnostic are therefore three lower than in the file.
-  //
-  // TWO HELPERS, NOT ONE, AND THEY ARE BUILT DIFFERENTLY. The transport
-  // helper is a PROGRAM the plugins run; the mini vault's crypto is a
-  // LOADABLE MODULE the interpreter opens with package.loadlib, so it is
-  // compiled -shared -fPIC and keeps its `.so` name. Each is emitted only
-  // for the groups that actually use it: a chain of `[hashicorp]` builds
-  // no vault, and a chain of `[minivault]` opens no socket and links no
-  // TLS.
   const nativeGroups: string[] = []
   let wantsVault = false
   each(feature, (f: any) => {
@@ -178,7 +133,6 @@ feature/secrets/native/sekretovault.so: feature/secrets/native/sekretovault.c
     })
   }
 
-  // Generate main SDK file
   File({ name: model.name + '_sdk.' + target.ext }, () => {
 
     Fragment(
@@ -190,15 +144,12 @@ feature/secrets/native/sekretovault.so: feature/secrets/native/sekretovault.c
           // Load the LuaLS typed-model annotations module so it is part of
           // the loaded program (module body is empty — no runtime effect) and
           // does not depend on workspace-wide language-server scanning.
-          // NOTE: plain marker keys must EMBED the lua comment prefix
           // (`-- #X`) — jostraca's bare `#X` form only matches `//`-style
           // comment lines (cf. the `'-- #LoadOp'` keys in Entity_lua.ts).
           '-- #TypesRequire': ({ indent }: any) => Content({ indent },
             `-- Typed-model annotations (LuaLS ---@class); empty at runtime.\n` +
             `require("${model.name}_types")`),
 
-          // Same embedded `-- ` prefix requirement as above (the bare
-          // '#BuildFeatures' key never matched the lua comment line).
           '-- #BuildFeatures': ({ indent }: any) => {
             each(feature, (feat: any) => {
               const fname = feat.name.charAt(0).toUpperCase() + feat.name.slice(1)
@@ -214,7 +165,6 @@ self._utility.feature_hook(self._rootctx, "${name}")
         }
       },
 
-      // Entities - injected at SLOT
       () => {
         each(entity, (entity: ModelEntity) => {
           const entitySDK = getModelPath(model, `main.${KIT}.entity.${entity.name}`)
@@ -224,10 +174,8 @@ self._utility.feature_hook(self._rootctx, "${name}")
       })
   })
 
-  // Generate typed-model annotations (LuaLS ---@class / ---@field)
   EntityTypes({ target })
 
-  // Generate config module
   Folder({ name: '.' }, () => {
     Config({ target })
     Schema({ target })
@@ -235,15 +183,10 @@ self._utility.feature_hook(self._rootctx, "${name}")
 
   // GENERATED, NOT COPIED. Where the credential goes is a fact about the
   // API - header, query or cookie, under the name the spec gives - and tm/
-  // can only hold one answer. See PrepareAuth_lua.
-  //
   // Called at the TARGET ROOT, like Config above (that Folder({name:'.'})
   // is the root itself), because the lua tree has no src/ wrapper: the
-  // component opens the one `utility` folder that
-  // require("utility.prepare_auth") needs.
   PrepareAuth({ target })
 
-  // Generate feature factory module
   File({ name: 'features.' + target.ext }, () => {
     Content(`-- ${model.const.Name} SDK feature factory
 
@@ -285,7 +228,6 @@ return features
   })
 
   // Generate _make_feature function referenced by Main.fragment.lua
-  // This is part of the main SDK class, inserted via the slot
 
 })
 

package/project/.sdk/src/cmp/lua/Package_lua.ts

@@ -33,9 +33,6 @@ const SECRETS_CORE_MODULES = [
   'feature/secrets/sekreto/err',
   'feature/secrets/sekreto/name',
   'feature/secrets/sekreto/providers',
-  // The shared plugin helpers, in no group: httpjson (eight kinds), net
-  // (httpjson, boru, secretspec), json and support (every kind), crypto
-  // (aws AND gcpsecrets - two groups, so neither may own it).
   'feature/secrets/sekreto/plugins/crypto',
   'feature/secrets/sekreto/plugins/httpjson',
   'feature/secrets/sekreto/plugins/json',
@@ -110,23 +107,6 @@ dependencies = {
 `)
     }
 
-    // Feature modules must be listed too, or an install-from-rock ships a
-    // features.lua whose requires cannot resolve. Emitted from the model
-    // (each = sorted order, byte-stable), plus the base feature every
-    // factory falls back to. The station feature additionally carries the
-    // VENDORED voxgig_station library beside its adapter (no voxgig-station
-    // rock exists to depend on - station design 9.2's registry-less tier).
-    // Gated: a feature that does not apply to lua must not be listed
-    // as a rockspec module — the require would not resolve.
-    //
-    // The secrets feature carries the VENDORED sekreto core, the
-    // voxgig/plugin runtime and the shared plugin helpers (no sekreto or
-    // plugin rock exists to depend on); the plugin KINDS themselves are
-    // listed from the model's active `def.lua` entries, so a trimmed
-    // group's modules are not claimed. The compiled transport helper the
-    // plugin kinds run is NOT a rock module: `build.type = "builtin"`
-    // cannot produce an executable, so an install-from-rock carries the
-    // helper's source and `make build` compiles it where the SDK runs.
     const feature = targetFeatures(model, target)
     let featureModules = `    ["feature.base_feature"] = "feature/base_feature.lua",\n`
     each(feature, (f: any) => {

package/project/.sdk/src/cmp/lua/PrepareAuth_lua.ts

@@ -12,64 +12,18 @@ import {
 } from '@voxgig/sdkgen'
 
 
-// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
-// rather than templated. The lua peer of PrepareAuth_ts.
-//
-// This was a static file at tm/lua/utility/prepare_auth.lua that hardcoded
-// a lower-case "authorization" HEADER. apidef has always resolved the
-// scheme's "in" and "name" into main.kit.info.security - joplin's says
-// in: "query", name: "token" - and generation dropped both. The result was
-// an SDK that sent a header the API does not read and never sent the query
-// parameter it does, so it could not authenticate at all. Four repos in
-// the cedar fleet shipped that way: joplin (token), pipedrive (api_token),
-// trello (key), lm-umbrella (apiKey).
-//
-// A template cannot fix this, because the three placements need three
-// different bodies and a template has to pick one. A component emits the
-// branch this API actually uses and nothing else - no dead query code in a
-// bearer-token SDK, and no runtime branch on a value that is fixed at
-// generation time.
-//
-// The header placement renders BYTE-FOR-BYTE what the template rendered,
-// so every header-based lua SDK regenerates with a zero diff.
 const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   const { target } = props
   const { model } = props.ctx$
 
-  // `!isAuthSuppressed`, NOT `isAuthActive`. The latter is also false when
-  // the SPEC merely declares no security scheme (`main.kit.info.auth:
-  // false`), and those SDKs still carry a credential: optspec always
-  // declares `apikey` and makeOptions fills `options.auth` from its
-  // defaults, so the runtime guard never fired and they have always sent
-  // it. Only an explicit `main.kit.config.auth.active: false` means "no
-  // credential, ever", which is what isAuthSuppressed reads.
   const active = !isAuthSuppressed(model)
   const where = resolveAuthIn(model)
   const prefix = resolveAuthPrefix(model)
   const basic = isHttpBasicAuth(model)
 
-  // A HEADER NAME IS LOWER-CASED HERE; A QUERY OR COOKIE NAME IS NOT.
-  // Every header key the lua SDK writes is lower case (make_spec's
-  // "content-type", the secrets feature's "authorization", fetcher's
-  // lower-casing of the response headers), and HTTP header names are
-  // case-insensitive on the wire - so "Authorization" must arrive here as
-  // the "authorization" the rest of the SDK looks up. A query parameter
-  // and a cookie name are case-SENSITIVE: lm-umbrella's "apiKey" is not
-  // "apikey", and lower-casing it would break exactly the APIs this
-  // change exists to fix.
   const cred = resolveAuthName(model)
   const name = 'header' === where ? cred.toLowerCase() : cred
 
-  // FOLDER NESTING. Main_lua opens NO folder around this call: its
-  // Folder({name:'.'}) around Config is the target root itself, and the
-  // lua tree has no src/ wrapper (tm/lua/src holds only feature
-  // placeholders and Main's Copy excludes it). The template lived at
-  // tm/lua/utility/prepare_auth.lua, which the blanket Copy lands at
-  // <root>/utility/prepare_auth.lua - the one path
-  // require("utility.prepare_auth") in utility/register.lua resolves. So
-  // this component opens the single "utility" folder that path needs.
-  // Opening a second one would write <root>/utility/utility/, where
-  // nothing requires it.
   Folder({ name: 'utility' }, () => {
     File({ name: 'prepare_auth.' + target.ext }, () => {
       Content(render({
@@ -91,8 +45,6 @@ function render(spec: {
 }): string {
   const head = `-- ${spec.project} SDK utility: prepare_auth\n`
 
-  // NO AUTH AT ALL. A public API's SDK gets a prepare_auth that is honest
-  // about it rather than one that deletes a header nobody set.
   if (!spec.active) {
     return head + `
 -- This API declares no authentication, so there is no credential to place.
@@ -166,8 +118,6 @@ return prepare_auth_util
 }
 
 
-// The constant the credential name is bound to, named for where it goes -
-// a reader of the generated file should not have to ask.
 function credConst(where: string): string {
   return 'query' === where ? 'QUERY_AUTH' :
     'cookie' === where ? 'COOKIE_AUTH' : 'HEADER_AUTH'
@@ -200,9 +150,6 @@ function clear(where: string, indent: number): string {
 
 function place(where: string): string {
   if ('query' === where) {
-    // NO PREFIX IN A QUERY STRING. "?token=Bearer%20abc" is not a thing any
-    // API reads; the prefix is a header-value convention and is dropped
-    // here deliberately rather than silently concatenated.
     return `    -- NO PREFIX IN A QUERY STRING: "?token=Bearer%20abc" is not a thing
     -- any API reads, so the auth.prefix a header placement space-joins is
     -- dropped here deliberately rather than concatenated.
@@ -223,8 +170,6 @@ function place(where: string): string {
     cookie_set(headers, apikey_val)`
   }
 
-  // BYTE-FOR-BYTE the template's body, so a header-based SDK regenerates
-  // unchanged.
   return `    local auth_prefix = ""
     local ap = vs.getpath(options, "auth.prefix")
     if type(ap) == "string" then
@@ -243,8 +188,6 @@ function place(where: string): string {
 }
 
 
-// True HTTP Basic Auth: two credentials, base64-joined. Emitted only for a
-// header placement (see render).
 const BASIC = `
   -- True HTTP Basic Auth needs TWO credentials, base64-joined - a single
   -- token in the header (the branch below) can never authenticate against
@@ -322,10 +265,6 @@ end
 `
 
 
-// A cookie header is SHARED: any other cookie the caller set rides in the
-// same string, so the credential pair is rewritten in place and everything
-// else is kept. A plain assignment would throw the caller's cookies away.
-// A nil value removes just our pair.
 const COOKIE_SET = `
 local function cookie_set(headers, value)
   local kept = {}

package/project/.sdk/src/cmp/lua/ReadmeEntity_lua.ts

@@ -19,12 +19,8 @@ function luaLit(type: any, placeholder: string = 'example'): string {
   return `"${placeholder}"`
 }
 
-// Non-identifier table keys use bracket syntax.
 
 
-// Operation method spelling differs between Go and other languages — Go
-// uses PascalCase methods with explicit ctrl arg, others use lowercase
-// methods with optional ctrl. The op descriptions are language-agnostic.
 const OP_DESC: Record<string, { method: string, desc: string }> = {
   load:   { method: 'load(match)',   desc: 'Load a single entity by match criteria.' },
   list:   { method: 'list(match)',   desc: 'List entities matching the criteria.' },
@@ -55,8 +51,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
-    const fields = entity.fields || []
-    // Model-driven id key: null when this entity has no id-like field.
+    const fields = Object.values(entity.fields || {})
     const idF = entityIdField(entity)
     // Sanitise the local variable name — an entity whose lowercased name is a
     // Lua keyword (e.g. `end`) would otherwise emit uncompilable code.
@@ -103,8 +98,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
 
       each(fields, (field: any) => {
-        const desc = field.short || ''
-        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
+        const desc = field.sh || ''
+        Content(`| \`${field.n}\` | \`${canonToType(field.t, target.name)}\` | ${desc} |
 `)
       })
 
@@ -113,9 +108,6 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     }
 
     if (opnames.includes('load')) {
-      // The id key plus every REQUIRED match key (parent path params like
-      // page_id) — the same shape the runtime resolves path params from, so
-      // the example always works.
       const loadItems = opRequestShape(entity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>

package/project/.sdk/src/cmp/lua/ReadmeExamplesTest_lua.ts

@@ -6,30 +6,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// Emits lua/test/readme_examples_test.lua — a busted spec that is a
-// COMPLETENESS GATE over every ```lua block in ALL THREE docs that ship
-// lua examples:
-//   - the root README.md (top-level, multi-language quick start)
-//   - the per-language lua/README.md
-//   - the per-language lua/REFERENCE.md
-//
-// For every ```lua block, tagged by (source doc, index):
-//   1. Syntax: it must compile with Lua's load() — catches malformed
-//      example code (missing end, bad token, ...).
-//   2. Offline run: every RUNNABLE block (one that builds a client via
-//      sdk.new/sdk.test or references `client`) is EXECUTED with the mock
-//      transport (no network). Each client constructor is rewritten to the
-//      seeded test-mode form, and fragments that only use `client` get a
-//      seeded test client injected. A call to a method that does not exist
-//      — e.g. a lowercase entity accessor after the API capitalised it to
-//      client:Entity() — raises "call a nil value" and FAILS the test.
-//      Entity operations return a (value, err) tuple, so a seeded-fixture
-//      miss surfaces as a tolerated (nil, err) not-found domain error.
-//   3. Completeness: every block is partitioned into {executed, illustration}
-//      and total == executed + illustration is asserted per doc. A block that
-//      is neither runnable nor a NARROW explicit illustration (a comment-only
-//      / --[[ ]] placeholder) is a silently-untested example and FAILS the
-//      gate — "illustration" is never a catch-all.
 const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
   const { ctx$: { model } } = props
 

package/project/.sdk/src/cmp/lua/ReadmeModel_lua.ts

@@ -13,10 +13,6 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const entityList = each(entity).filter((e: any) => e.active !== false)
 
-  // Model-driven op rows for the shared entity interface: emit a
-  // load/list/create/update/remove row only for operations at least one active
-  // entity actually exposes (a read-only entity has just list+load) — never
-  // document an operation no entity has.
   const opUnion = new Set<string>()
   entityList.forEach((e: any) => Object.keys(e.op || {})
     .forEach((o: string) => { if (e.op[o] && e.op[o].active !== false) opUnion.add(o) }))
@@ -30,9 +26,6 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const opRows = ['load', 'list', 'create', 'update', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
 
-  // Model-driven Result-shape rows: only describe the operations that
-  // actually exist. Record-returning ops (load/create/update/remove) share
-  // one row; list has its own — never name a missing op.
   const recordOps = ['load', 'create', 'update', 'remove'].filter((o) => opUnion.has(o))
     .map((o) => '`' + o + '`')
   const resultRows: string[] = []
@@ -50,8 +43,6 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const eName = exEnt.Name || 'Entity'
   const eLower = String(exEnt.name || 'entity').toLowerCase()
   const hasLoad = null != (exEnt.op || {}).load
-  // Model-driven id key: null when the example entity has no id-like field, so
-  // the Result-shape load illustration takes no match argument.
   const idF = entityIdField(exEnt)
 
   const apikeyOptionRow = isAuthActive(model)
@@ -136,18 +127,17 @@ Only \`direct()\` returns a response envelope — a \`table\` with \`ok\`,
 
 `)
 
-  // Entities summary
   Content(`### Entities
 
 `)
   each(entityList, (ent: any) => {
-    const fields = ent.fields || []
+    const fields = Object.values(ent.fields || {})
     const opnames = Object.keys(ent.op || {})
     const ops = ent.op || {}
     const points = each(ops).map((op: any) =>
       op.points ? each(op.points) : []
     ).flat()
-    const path = points.length > 0 ? (points[0] as any).orig || '' : ''
+    const path = points.length > 0 ? (points[0] as any).o || '' : ''
 
     Content(`#### ${ent.Name}
 
@@ -155,7 +145,7 @@ Only \`direct()\` returns a response envelope — a \`table\` with \`ok\`,
 | --- | --- |
 `)
     each(fields, (field: any) => {
-      Content(`| \`${field.name}\` | ${field.short || ''} |
+      Content(`| \`${field.n}\` | ${field.sh || ''} |
 `)
     })
 

package/project/.sdk/src/cmp/lua/ReadmeQuick_lua.ts

@@ -15,9 +15,6 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  // Find a nested entity if available: one with a parent chain
-  // (relations.ancestors), an active load op, and a required non-id load
-  // param to demonstrate (the parent key, e.g. page_id).
   const nestedEntity = Object.values(entity).find((e: any) =>
     e.active !== false &&
     e.relations && e.relations.ancestors && 0 < e.relations.ancestors.length &&
@@ -73,12 +70,12 @@ local client = ${ctor}
     // `id`, matching the load example and the seeded test fixture.
     const idNames = new Set<string>(['id',
       (exampleEntity.id && exampleEntity.id.field) || 'id'])
-    const fields: any[] = Array.isArray(exampleEntity.fields) ? exampleEntity.fields : []
+    const fields: any[] = Object.values(exampleEntity.fields || {})
     const isStringField = (f: any) =>
-      f && typeof f.type === 'string' && /STRING/i.test(f.type)
+      f && typeof f.t === 'string' && /STRING/i.test(f.t)
     const displayFieldObj =
-      fields.find((f: any) => f && !idNames.has(f.name) && isStringField(f)) ||
-      fields.find((f: any) => f && !idNames.has(f.name))
+      fields.find((f: any) => f && !idNames.has(f.n) && isStringField(f)) ||
+      fields.find((f: any) => f && !idNames.has(f.n))
     const displayField = displayFieldObj ? displayFieldObj.name : null
     const idCol = dataIdF ? `item["${dataIdF}"]` : null
     const dispCol = displayField ? `item["${displayField}"]` : null
@@ -108,9 +105,6 @@ end
       const neArticle = /^[aeiou]/i.test(neName) ? "an" : "a"
       const neVar = exampleVarName(neName.toLowerCase(), 'lua')
 
-      // Model-driven match: every REQUIRED load-match key — the same shape
-      // the runtime resolves path params from, so the example always works.
-      // Parent keys (e.g. page_id) first, the entity's own id last.
       const neIdF = entityIdField(nestedEntity)
       const neRequired = opRequestShape(nestedEntity, 'load').items
         .filter((it: any) => !it.optional)
@@ -136,9 +130,6 @@ print(${neVar})
 `)
     }
     else if (opnames.includes('load')) {
-      // Every REQUIRED load-match key (id first, then parent path params like
-      // page_id) — the same shape the runtime resolves path params from, so
-      // the example always works.
       const loadRequired = opRequestShape(exampleEntity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>
@@ -160,20 +151,12 @@ print(${eVar})
 `)
     }
 
-    // Model-driven example fields: derive the create/update body from the op
-    // shape (opRequestShape) so the docs reference REAL writable fields, not a
-    // hardcoded "name" the entity may not have. Literals are Lua-typed by the
-    // field's canonical type; non-identifier keys use bracket syntax. ids are
-    // rendered separately as the match key for update/remove; a REQUIRED
-    // create id stays (the call is invalid without it).
     const examplePairs = (opname: string): string[] => {
       const items = opRequestShape(exampleEntity, opname).items
         .filter((it: any) => !idNames.has(it.name) ||
           ('create' === opname && !it.optional))
       const required = items.filter((it: any) => !it.optional)
       const optional = items.filter((it: any) => it.optional)
-      // create needs ALL required fields; update is a patch, so the required
-      // members plus a sample optional field or two suffice.
       const chosen = 'create' === opname
         ? (required.length ? required : items.slice(0, 2))
         : required.concat(optional).slice(0, Math.max(2, required.length))
@@ -181,8 +164,6 @@ print(${eVar})
         `${luaKey(it.name)} = ${luaLit(it.type, 'example_' + it.name)}`)
     }
 
-    // The id VALUE for an update/remove match: off the returned `created` record
-    // only when its data type carries the id AND a create ran, else a literal.
     const idParamType = (opname: string): any => {
       const it = opRequestShape(exampleEntity, opname).items.find((x: any) => x.name === idF)
       return it && it.type
@@ -211,8 +192,6 @@ client:${eName}():update({ ${updatePairs.join(', ')} })
 `)
       }
       if (opnames.includes('remove')) {
-        // Every REQUIRED remove-match key: the id (off the created record
-        // when possible) plus parent keys like page_id.
         const removePairs = opRequestShape(exampleEntity, 'remove').items
           .filter((it: any) => !it.optional || it.name === idF)
           .sort((a: any, b: any) =>