@voxgig/sdkgen 4.11.0 → 4.13.0

package/project/.sdk/tm/zig/feature/secrets/plugins/boru.zig

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (zig/plugins/boru.zig)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 //! A boru vault (https://github.com/boru-lang/boru) - a sekreto plugin.
 //!

package/project/.sdk/tm/zig/feature/secrets/plugins/doppler.zig

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (zig/plugins/doppler.zig)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 //! Doppler - a sekreto plugin. Needs HTTPS.
 

package/project/.sdk/tm/zig/feature/secrets/plugins/gcpsecrets.zig

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (zig/plugins/gcpsecrets.zig)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 //! GCP Secret Manager - a sekreto plugin. Needs HTTPS.
 

package/project/.sdk/tm/zig/feature/secrets/plugins/hashicorp.zig

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (zig/plugins/hashicorp.zig)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 //! HashiCorp Vault - a sekreto plugin.
 //!

package/project/.sdk/tm/zig/feature/secrets/plugins/httpjson.zig

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (zig/plugins/httpjson.zig)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 //! One JSON round-trip, for the plugins that talk to a vault over HTTP -
 //! and the small helpers every plugin shares: address trimming, the

package/project/.sdk/tm/zig/feature/secrets/plugins/infisical.zig

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (zig/plugins/infisical.zig)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 //! Infisical - a sekreto plugin. Needs HTTPS.
 

package/project/.sdk/tm/zig/feature/secrets/plugins/onepassword.zig

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (zig/plugins/onepassword.zig)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 //! 1Password, through a Connect server - a sekreto plugin. Needs HTTPS.
 

package/project/.sdk/tm/zig/feature/secrets/plugins/secretspec.zig

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (zig/plugins/secretspec.zig)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 //! SecretSpec (https://secretspec.dev) - a sekreto plugin.
 //!

package/project/.sdk/tm/zig/feature/secrets/plugins/sigv4.zig

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (zig/plugins/sigv4.zig)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 //! AWS Signature Version 4, hand-rolled.
 //!

package/project/.sdk/tm/zig/feature/secrets/sekreto/addr.zig

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (zig/src/addr.zig)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 //! The address check every network provider makes before it sends a
 //! credential anywhere.

package/project/.sdk/tm/zig/feature/secrets/sekreto/builtins.zig

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (zig/src/builtins.zig)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 //! THE BUILT-IN PROVIDER KINDS - the same four in every port.
 //!

package/project/.sdk/tm/zig/feature/secrets/sekreto/provider.zig

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (zig/src/provider.zig)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 //! What a provider is, what its declarative form looks like, and how a
 //! provider kind becomes a voxgig/plugin definition.

package/project/.sdk/tm/zig/feature/secrets/sekreto/sekreto.zig

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (zig/src/sekreto.zig)
-// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260911-2013-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 //! sekreto: one interface for secrets, wherever they live.
 //!

package/project/.sdk/tm/zig/test/vendor/omni/omni.zig

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/omni sdk-20260908-1556-0 (zig/src/omni.zig)
-// Source: https://github.com/voxgig/omni @ 274708cc2d12b21707d975543953f845f8444be0  [tag: sdk-20260908-1556-0]
+// Source: https://github.com/voxgig/omni @ 274708cc2d12b21707d975543953f845f8444be0  [tag: sdk-20260911-2013-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 //! Omni: the shared multi-language test runner (Zig port).
 //!

package/project/.sdk/tm/zig/test/vendor/omni/regex.zig

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/omni sdk-20260908-1556-0 (zig/src/regex.zig)
-// Source: https://github.com/voxgig/omni @ 274708cc2d12b21707d975543953f845f8444be0  [tag: sdk-20260908-1556-0]
+// Source: https://github.com/voxgig/omni @ 274708cc2d12b21707d975543953f845f8444be0  [tag: sdk-20260911-2013-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 //! A small backtracking regex engine.
 //!

package/project/.sdk/tm/zig/utility/voxgigstruct/regex.zig

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/struct sdk-20260908-1556-0 (zig/src/regex.zig)
-// Source: https://github.com/voxgig/struct @ adda9521c828147573df5a8878408a3f2193ddf4  [tag: sdk-20260908-1556-0]
+// Source: https://github.com/voxgig/struct @ abd93227e3295151f8dcd18597c3f3f2577af8b7  [tag: sdk-20260911-2013-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 // Copyright (c) 2025-2026 Voxgig Ltd. MIT LICENSE.
 //

package/project/.sdk/tm/zig/utility/voxgigstruct/struct.zig

@@ -1,5 +1,5 @@
 // VENDORED: @voxgig/struct sdk-20260908-1556-0 (zig/src/struct.zig)
-// Source: https://github.com/voxgig/struct @ adda9521c828147573df5a8878408a3f2193ddf4  [tag: sdk-20260908-1556-0]
+// Source: https://github.com/voxgig/struct @ abd93227e3295151f8dcd18597c3f3f2577af8b7  [tag: sdk-20260911-2013-0]
 // License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
 // Copyright (c) 2025-2026 Voxgig Ltd. MIT LICENSE.
 

package/project/sdkgen-package.json

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

package/src/action/resolve.ts

@@ -335,7 +335,91 @@ function nameConflict(
 
   const sameBase = normaliseBase(declared.base) === normaliseBase(source.base)
 
-  return (samePackage || sameBase) ? undefined : declared
+  if (samePackage || sameBase) {
+    return undefined
+  }
+
+  // The record names a DIFFERENT source. That is a collision only if that
+  // source still provides this name — otherwise the record is STALE and
+  // adopting the new one is a migration, not a silent clobber.
+  //
+  // A package can stop providing something it used to: `seneca-provider` left
+  // @voxgig/sdkgen for @voxgig/sdkgen-infrapack, `dart`/`haskell`/`lean` left
+  // for @voxgig/sdkgen-langpack. Every project carrying the pre-split copy
+  // still records the old package, so a check that reads only the record
+  // refuses the very add that repairs it, and names as the incumbent a
+  // package that no longer ships the thing at all. The only way through was
+  // `<kind> add <package>/<name>`, which nobody guesses from the message.
+  return providesStill(kind, declared, source, ctx$) ? declared : undefined
+}
+
+
+// Does the RECORDED source still provide this name?
+//
+// Answered from what is on disk now, not from the record. Conservative in
+// both directions: an unreadable or absent source cannot be shown to provide
+// it, so the add proceeds; anything still providing it is a real collision
+// and still refuses.
+function providesStill(
+  kind: string, declared: any, source: Source, ctx$: any,
+): boolean {
+  let fs: any
+  try {
+    fs = ctx$.fs()
+  }
+  catch (err: any) {
+    // No filesystem to check with — keep the pre-existing behaviour.
+    return true
+  }
+
+  const base = String(declared.base)
+  const folder = Path.isAbsolute(base) ?
+    Path.normalize(base) :
+    Path.normalize(Path.join(ctx$.folder, base))
+
+  if (!fs.existsSync(folder)) {
+    // Uninstalled, moved, or never fetched. Nothing there to collide with.
+    return false
+  }
+
+  // The name to look for is the one the SOURCE knows it by, which differs
+  // from the installed name only for an alias.
+  //
+  // `||`, NOT `??`. `origname` is `*'' | string` in the schema, and the model
+  // records the empty string for every unaliased item -- the convention is a
+  // falsy default, not an absent key. Nullish coalescing does not fall back
+  // for '', so a reloaded project would have every ordinary item looked up as
+  // '', found in no manifest, and declared stale: the guard would then wave
+  // through exactly the silent overwrite it exists to stop. The in-process
+  // tests could not see it, because `registerInstalled` leaves `origname`
+  // non-empty in the same context that wrote it.
+  const seek = declared.origname || source.name
+
+  // A WELL-FORMED manifest is authoritative about what its package provides:
+  // a definition file can linger in a stale node_modules tree after the
+  // package dropped it, and `provides` is the claim `package add` is itself
+  // checked against.
+  //
+  // A manifest that would fail validation is not authoritative about
+  // anything. `resolveSource` deliberately tolerates a malformed manifest on
+  // the direct-add path -- the definition, components and templates are all
+  // present, so it installs them and records `base` -- which is precisely how
+  // an installed item comes to have one. Reading `provides` out of it anyway
+  // would let a shape error (`provides: { target: 'iotgo' }`, a string where
+  // a list belongs) read as "provides nothing" and clear the way to overwrite
+  // a live target. Fall through to the definition file instead, which is what
+  // a source with no manifest at all is judged on.
+  const read = readManifest(fs, folder)
+  const manifest = read.manifest
+  if (null != manifest && 0 === checkShape(manifest, read.file).length) {
+    const names = manifest.provides?.[kind]
+    return Array.isArray(names) && names.includes(seek)
+  }
+
+  // No manifest, or one too malformed to be believed: a bare `.sdk`-shaped
+  // folder is a legal source, and its definition file is the only claim it
+  // makes.
+  return fs.existsSync(definitionPath(folder, kind, seek))
 }
 
 

package/src/cmp/PublishWorkflow.ts

@@ -0,0 +1,324 @@
+/* Copyright (c) 2024-2026 Voxgig Ltd, MIT License */
+
+import { cmp, each, Content, File, Folder } from 'jostraca'
+
+import {
+  KIT,
+  getModelPath
+} from '../types'
+
+import { packageName, packageVersion, repoInfo } from '../helpers/packageMeta'
+
+
+// PUBLISHING AN npm TARGET FROM GITHUB ACTIONS, WITH NO TOKEN.
+//
+// A generated SDK is published from CI, and the credential is the whole
+// problem: an NPM_TOKEN in repository secrets is long-lived, copyable, and
+// readable by every workflow in the repo. GitHub OIDC Trusted Publishing
+// replaces it — npm exchanges a short-lived OIDC token minted for one job in
+// one repository for a publish credential, and attaches SLSA provenance on
+// the way through.
+//
+// DISPATCH, NOT A TAG PUSH. The deploy Makefile in this same repo publishes
+// with a vault-injected token, and a tag-triggered workflow racing it would
+// publish the same version twice from two mechanisms. A dispatch is a
+// deliberate act by someone who can see the result, which is what a release
+// should be.
+//
+// THE WORKFLOW FILE NAME IS PART OF THE TRUST CONFIGURATION. npm binds a
+// trusted publisher to the repository AND the workflow filename, so renaming
+// this file silently breaks publishing until the npm side is updated to
+// match. That is also why one file per target: `publish-ts.yml` can be
+// trusted for the ts package without granting anything to another target's.
+//
+// SET-UP IS A MAINTAINER TASK, so what a human must do once is written to
+// `.sdk/PUBLISHING.md` — beside the generator, not into the target's own
+// docs, which describe the SDK to the people who INSTALL it and have no
+// business being told how this repo releases.
+const PublishWorkflow = cmp(function PublishWorkflow(props: any) {
+  const { ctx$ } = props
+  const { model } = ctx$
+
+  const targetMap = getModelPath(model, `main.${KIT}.target`) || {}
+
+  // npm ONLY. The mechanics here are npm's — `npm publish`, `npm trust`,
+  // npm's OIDC exchange — and a PyPI or RubyGems target needs a different
+  // workflow rather than this one with a word changed. Emitting nothing for
+  // them is the honest answer until those exist.
+  const npmTargets: any[] = []
+  each(targetMap, (t: any) => {
+    if (false === t.active) {
+      return
+    }
+    if ('npm' === (t.publish?.registry?.name || '')) {
+      npmTargets.push(t)
+    }
+  })
+
+  if (0 === npmTargets.length) {
+    return
+  }
+
+  const { repoUrl } = repoInfo(model)
+
+  Folder({ name: '.github' }, () => {
+    Folder({ name: 'workflows' }, () => {
+      for (const target of npmTargets) {
+        File({ name: `publish-${target.name}.yml` }, () => {
+          Content(publishWorkflow(model, target))
+        })
+      }
+    })
+  })
+
+  Folder({ name: '.sdk' }, () => {
+    File({ name: 'PUBLISHING.md' }, () => {
+      Content(publishingDoc(model, npmTargets, repoUrl))
+    })
+  })
+
+  ctx$.log.info({
+    point: 'generate-publish-workflow',
+    note: 'npm targets: ' + npmTargets.map((t: any) => t.name).join(','),
+  })
+})
+
+
+function publishWorkflow(model: any, target: any): string {
+  const name = target.name
+  const pkg = packageName(model, 'npm')
+
+  return `# Generated by @voxgig/sdkgen. Do not edit.
+#
+# Publishes ${pkg} (the \`${name}/\` target) to npm, via GitHub OIDC Trusted
+# Publishing — no NPM_TOKEN. npm exchanges a short-lived OIDC token minted
+# for THIS job in THIS repository for a publish credential, and attaches SLSA
+# provenance automatically.
+#
+# SET UP ONCE, by a maintainer with publish rights — see .sdk/PUBLISHING.md:
+#
+#   npm trust github ${pkg} \\
+#     --repository <owner>/<repo> \\
+#     --file publish-${name}.yml \\
+#     --allow-publish
+#
+# THE FILENAME IS PART OF THAT CONFIGURATION. Renaming this file breaks
+# publishing until the npm side is updated to match.
+#
+# BY DISPATCH, deliberately. The deploy Makefile publishes with a
+# vault-injected token; a tag-triggered workflow racing it would publish one
+# version by two mechanisms. Releasing is an act someone performs and
+# watches.
+#
+# TWO JOBS, BECAUSE THEY NEED DIFFERENT PRIVILEGES. A dependency lifecycle
+# script can ask the runner for any OIDC token its job is permitted to mint,
+# so a job that both installs dependencies and holds \`id-token: write\` can be
+# made to publish before its own gates finish.
+#
+#   verify   contents: read, nothing else. Installs, builds and tests.
+#   publish  id-token: write. Installs no dependencies and runs no project
+#            code; it packs what is already in the tree.
+
+name: publish-${name}
+
+on:
+  workflow_dispatch:
+    inputs:
+      expect_sha:
+        description: 'Optional: refuse unless main is still at this commit'
+        type: string
+        default: ''
+
+jobs:
+  verify:
+    name: verify
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    # Deliberately the default-minimum. This job runs third-party code.
+    permissions:
+      contents: read
+
+    outputs:
+      version: \${{ steps.version.outputs.version }}
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: 24.x
+
+      # RELEASES COME FROM main, INCLUDING FROM THE BUTTON. workflow_dispatch
+      # accepts any ref, so without this the Actions UI can release a branch.
+      - name: This ref is main, and is where the caller thinks it is
+        env:
+          EXPECT: \${{ inputs.expect_sha }}
+        run: |
+          set -euo pipefail
+          if [ "\${GITHUB_REF_NAME}" != "main" ]; then
+            echo "::error::releases come from main, not \${GITHUB_REF_NAME}"
+            exit 1
+          fi
+          if [ -n "\$EXPECT" ] && [ "\$EXPECT" != "\$GITHUB_SHA" ]; then
+            echo "::error::main is at \$GITHUB_SHA, not \$EXPECT"
+            exit 1
+          fi
+
+      - name: Resolve the version
+        id: version
+        working-directory: ${name}
+        run: |
+          set -euo pipefail
+          VERSION="\$(node -p "require('./package.json').version")"
+          test -n "\$VERSION" || { echo "::error::no version in ${name}/package.json"; exit 1; }
+          echo "version=\$VERSION" >> "\$GITHUB_OUTPUT"
+          echo "${pkg} \$VERSION"
+
+      - run: npm install
+        working-directory: ${name}
+
+      - run: npm run build
+        working-directory: ${name}
+
+      - run: npm test
+        working-directory: ${name}
+
+  publish:
+    name: npm publish
+    needs: verify
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    # The ONLY job holding the publish credential — and it installs no
+    # dependencies and runs no project code. See the header.
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: 24.x
+          registry-url: 'https://registry.npmjs.org'
+
+      # Trusted publishing requires npm >= 11.5.1. This is npm itself, not a
+      # project dependency: no package.json here is consulted.
+      - name: Use a trusted-publishing capable npm
+        run: npm install -g npm@latest
+
+      # THE REGISTRY IS THE SOURCE OF TRUTH FOR "IS THIS RELEASED", not the
+      # dispatch. A re-run would otherwise fail on a version conflict and
+      # report a red release that in fact succeeded.
+      - name: Is this version already on npm?
+        id: registry
+        env:
+          VERSION: \${{ needs.verify.outputs.version }}
+        run: |
+          set -euo pipefail
+          if npm view "${pkg}@\$VERSION" version >/dev/null 2>&1; then
+            echo "published=true" >> "\$GITHUB_OUTPUT"
+            echo "\$VERSION is already on npm — skipping publish"
+          else
+            echo "published=false" >> "\$GITHUB_OUTPUT"
+          fi
+
+      - name: Publish to npm
+        if: steps.registry.outputs.published == 'false'
+        working-directory: ${name}
+        run: npm publish --access public
+`
+}
+
+
+function publishingDoc(model: any, targets: any[], repoUrl: string): string {
+  const pkg = packageName(model, 'npm')
+  const repo = String(repoUrl || '')
+    .replace(/^git\+/, '')
+    .replace(/^(https?:\/\/)?(www\.)?github\.com[/:]/, '')
+    .replace(/\.git$/, '')
+    .replace(/\/+$/, '')
+  const owner = '' === repo ? '<owner>/<repo>' : repo
+
+  const rows = targets.map((t: any) =>
+    `| \`${t.name}/\` | ${packageName(model, 'npm')} | ` +
+    `\`.github/workflows/publish-${t.name}.yml\` |`).join('\n')
+
+  return `# Publishing
+
+GENERATED by @voxgig/sdkgen — regenerated on every \`npm run generate\`.
+
+This file is for MAINTAINERS of this repository. It is in \`.sdk/\` on
+purpose: the target directories document the SDK to the people who install
+it, and how this repo releases is none of their business.
+
+| target | package | workflow |
+|---|---|---|
+${rows}
+
+## How a release happens
+
+Publishing runs from GitHub Actions with **no NPM_TOKEN**. npm exchanges a
+short-lived OIDC token — minted for one job in this repository — for a
+publish credential, and attaches SLSA provenance as it goes.
+
+1. Bump the version in the model, then regenerate:
+
+       main: kit: target: ts: publish: version: '<x.y.z>'
+
+2. Commit and push to \`main\`, and let CI go green.
+3. Run the workflow from the Actions tab, or:
+
+       gh workflow run publish-ts.yml --ref main -f expect_sha=$(git rev-parse HEAD)
+
+\`expect_sha\` is optional and worth using: it refuses if \`main\` moved between
+the commit you checked and the run resolving.
+
+It is a DISPATCH rather than a tag push because the root \`Makefile\` also
+publishes, with a vault-injected token. A tag-triggered workflow racing it
+would publish one version by two mechanisms.
+
+## One-time set-up
+
+npm has to be told which repository and which workflow file may publish this
+package. From a machine logged in to npm with publish rights (2FA is
+required):
+
+    npm trust github ${pkg} \\
+      --repository ${owner} \\
+      --file publish-ts.yml \\
+      --allow-publish
+
+Then \`npm trust list ${pkg}\` shows it, and
+\`npm trust revoke ${pkg} --id=<id>\` removes it.
+
+**The workflow filename is part of the configuration.** Renaming
+\`publish-ts.yml\` breaks publishing until the npm side is updated to match.
+
+**A brand-new package cannot be set up this way.** npm only offers the
+trusted-publisher settings once a version exists, so the FIRST release of a
+package goes out by hand from an authenticated machine:
+
+    cd ts && npm publish --access public
+
+After that, register the publisher and every later release is a dispatch.
+
+## Why the workflow has two jobs
+
+A dependency lifecycle script can ask the runner for any OIDC token the job
+it runs in is permitted to mint. A job that both installs dependencies and
+holds \`id-token: write\` can therefore be made to publish as this package
+before its own gates finish.
+
+So \`verify\` installs, builds and tests under \`contents: read\` and holds no
+credential, and \`publish\` holds \`id-token: write\` while installing nothing
+and running no project code.
+`
+}
+
+
+export {
+  PublishWorkflow
+}

package/src/sdkgen.ts

@@ -38,6 +38,7 @@ import { AgentGuide } from './cmp/AgentGuide'
 import { AgentGuideFeature } from './cmp/AgentGuideFeature'
 import { License } from './cmp/License'
 import { Security } from './cmp/Security'
+import { PublishWorkflow } from './cmp/PublishWorkflow'
 import { Changelog } from './cmp/Changelog'
 import { Test } from './cmp/Test'
 import { TestControl, TEST_CONTROL_EXCLUDE } from './cmp/TestControl'
@@ -1083,6 +1084,7 @@ export {
   Deploy,
   License,
   Security,
+  PublishWorkflow,
   Changelog,
   Entity,
   Feature,

package/src/utility.ts

@@ -416,6 +416,23 @@ function configDefinition(model: any, targetname?: string): { def: any, json: st
   each(entity, (e: any) => {
     entityDefs[e.name] = clean({
       fields: e.fields,
+      // THE ID DESCRIPTOR REACHES THE RUNTIME, not just the generators.
+      //
+      // `id.parts` / `id.sep` / `id.from` say how the API addresses one
+      // record: which path parameters name it, what joins them into the one
+      // id an SDK entity carries, and — the part only a response can
+      // answer — WHERE each parameter's value lives in a returned record.
+      // github's repo is `{owner}/{repo}`, returned as `owner.login` and
+      // `name`.
+      //
+      // Code that runs, not just code that is written, needs this. The
+      // offline test transport resolves a request parameter against a
+      // stored record, and a record whose identifying values are nested
+      // (or named differently) cannot be matched by parameter name alone —
+      // it matched nothing, so every seeded composite record was
+      // unfindable. `clean` drops the key for the ordinary entity whose
+      // model carries no descriptor, so nothing else moves.
+      id: e.id,
       name: e.name,
       op: withPointParts(e.op),
       relations: e.relations,