docs: add plan for local embeddings smoke public version

docs/superpowers/plans/2026-05-11-managed-local-embeddings-smoke-public-version.md

@@ -0,0 +1,239 @@
+# Managed Local Embeddings Smoke Public Version Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make the opt-in local embeddings release smoke validate the public
+`@kaelio/ktx` package version instead of the private workspace version.
+
+**Architecture:** Reuse the public package constants from
+`scripts/build-public-npm-package.mjs` inside the local embeddings smoke. Add a
+small exported RegExp helper so the unit test can lock the version expectation
+without running the expensive model-download smoke.
+
+**Tech Stack:** Node.js ESM scripts, `node:test`, pnpm release scripts.
+
+---
+
+## Current State
+
+The npm-managed Python runtime spec is
+`docs/superpowers/specs/2026-05-11-npm-managed-python-runtime-design.md`.
+The current branch already contains implementation commits for each existing
+plan derived from that spec.
+
+Implemented spec-derived plans:
+
+- `docs/superpowers/plans/2026-05-11-bundled-python-runtime-wheel.md`
+- `docs/superpowers/plans/2026-05-11-managed-python-runtime-installer.md`
+- `docs/superpowers/plans/2026-05-11-managed-python-runtime-command-integration.md`
+- `docs/superpowers/plans/2026-05-11-managed-python-runtime-daemon-lifecycle.md`
+- `docs/superpowers/plans/2026-05-11-managed-local-embeddings-runtime.md`
+- `docs/superpowers/plans/2026-05-11-public-kaelio-ktx-npm-package.md`
+- `docs/superpowers/plans/2026-05-11-managed-python-runtime-release-smoke.md`
+- `docs/superpowers/plans/2026-05-11-managed-local-embeddings-release-smoke.md`
+- `docs/superpowers/plans/2026-05-11-managed-agent-mcp-semantic-runtime.md`
+- `docs/superpowers/plans/2026-05-11-managed-local-ingest-daemon-runtime.md`
+- `docs/superpowers/plans/2026-05-11-managed-runtime-docs-and-postgres-smoke-cleanup.md`
+- `docs/superpowers/plans/2026-05-11-published-package-managed-runtime-smoke.md`
+- `docs/superpowers/plans/2026-05-11-public-npm-release-handoff.md`
+- `docs/superpowers/plans/2026-05-11-managed-runtime-prune-smoke-and-docs.md`
+- `docs/superpowers/plans/2026-05-11-managed-runtime-uv-prerequisite-contract.md`
+- `docs/superpowers/plans/2026-05-11-single-public-runtime-artifact-cleanup.md`
+
+The remaining gap is in
+`scripts/local-embeddings-runtime-smoke.mjs`. The script selects and installs a
+public tarball named `kaelio-ktx-*.tgz` and writes a smoke package dependency on
+`@kaelio/ktx`, but line 267 still expects `@kaelio/ktx 0.0.0-private`. The
+public package builder defines `PUBLIC_NPM_PACKAGE_VERSION = '0.1.0'`, and the
+main packed-package smoke already expects `@kaelio/ktx 0.1.0`.
+
+## File Structure
+
+This change keeps the release version source of truth in one script and reuses
+it from the opt-in smoke.
+
+- Modify `scripts/local-embeddings-runtime-smoke.mjs`: import the public package
+  constants, export `expectedPublicKtxVersionPattern()`, and use that pattern
+  for the smoke version assertion.
+- Modify `scripts/local-embeddings-runtime-smoke.test.mjs`: import
+  `expectedPublicKtxVersionPattern()` and assert that it accepts
+  `@kaelio/ktx 0.1.0` and rejects `@kaelio/ktx 0.0.0-private`.
+
+### Task 1: Align the local embeddings smoke version assertion
+
+**Files:**
+- Modify: `scripts/local-embeddings-runtime-smoke.mjs:1-267`
+- Modify: `scripts/local-embeddings-runtime-smoke.test.mjs:5-118`
+- Test: `scripts/local-embeddings-runtime-smoke.test.mjs`
+
+- [ ] **Step 1: Write the failing version-pattern test**
+
+In `scripts/local-embeddings-runtime-smoke.test.mjs`, update the import block
+to include `expectedPublicKtxVersionPattern`:
+
+```js
+import {
+  buildLocalEmbeddingsSmokeEnv,
+  expectedPublicKtxVersionPattern,
+  localEmbeddingsSmokeCommands,
+  localEmbeddingsSmokeOptIn,
+  parseDaemonBaseUrl,
+  publicKtxTarballName,
+  validateEmbeddingResponse,
+} from './local-embeddings-runtime-smoke.mjs';
+```
+
+Then add this test after the `publicKtxTarballName` describe block:
+
+```js
+describe('expectedPublicKtxVersionPattern', () => {
+  it('matches the public package version and rejects the private workspace version', () => {
+    const pattern = expectedPublicKtxVersionPattern();
+
+    assert.match('@kaelio/ktx 0.1.0\n', pattern);
+    assert.doesNotMatch('@kaelio/ktx 0.0.0-private\n', pattern);
+  });
+});
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run:
+
+```bash
+node --test scripts/local-embeddings-runtime-smoke.test.mjs
+```
+
+Expected: FAIL with an ESM export error that says
+`expectedPublicKtxVersionPattern` is not exported from
+`./local-embeddings-runtime-smoke.mjs`.
+
+- [ ] **Step 3: Import the public package constants**
+
+In `scripts/local-embeddings-runtime-smoke.mjs`, add this import after the
+existing Node imports:
+
+```js
+import {
+  PUBLIC_NPM_PACKAGE_NAME,
+  PUBLIC_NPM_PACKAGE_VERSION,
+} from './build-public-npm-package.mjs';
+```
+
+The top of the file becomes:
+
+```js
+import { execFile } from 'node:child_process';
+import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+
+import {
+  PUBLIC_NPM_PACKAGE_NAME,
+  PUBLIC_NPM_PACKAGE_VERSION,
+} from './build-public-npm-package.mjs';
+```
+
+- [ ] **Step 4: Add the version-pattern helper**
+
+In `scripts/local-embeddings-runtime-smoke.mjs`, add these functions after the
+`OPT_IN_MESSAGE` constant:
+
+```js
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function expectedPublicKtxVersionPattern() {
+  return new RegExp(
+    `${escapeRegExp(PUBLIC_NPM_PACKAGE_NAME)} ${escapeRegExp(PUBLIC_NPM_PACKAGE_VERSION)}`,
+  );
+}
+```
+
+- [ ] **Step 5: Use the helper in the smoke**
+
+In `scripts/local-embeddings-runtime-smoke.mjs`, replace this line:
+
+```js
+requireOutput(commands[0].label, version, /@kaelio\/ktx 0\.0\.0-private/);
+```
+
+with:
+
+```js
+requireOutput(commands[0].label, version, expectedPublicKtxVersionPattern());
+```
+
+- [ ] **Step 6: Run the focused test**
+
+Run:
+
+```bash
+node --test scripts/local-embeddings-runtime-smoke.test.mjs
+```
+
+Expected: PASS. The new test proves the smoke accepts `@kaelio/ktx 0.1.0` and
+rejects `@kaelio/ktx 0.0.0-private`.
+
+- [ ] **Step 7: Run related release-script tests**
+
+Run:
+
+```bash
+node --test scripts/local-embeddings-runtime-smoke.test.mjs scripts/build-public-npm-package.test.mjs scripts/package-artifacts.test.mjs
+```
+
+Expected: PASS. These tests cover the public package constants, tarball name,
+artifact smoke source, and local embeddings smoke helpers.
+
+- [ ] **Step 8: Run a stale-expectation search**
+
+Run:
+
+```bash
+rg -n "@kaelio/ktx 0\\.0\\.0-private|0\\\\\\.0\\\\\\.0-private" scripts/local-embeddings-runtime-smoke.mjs
+```
+
+Expected: no output. The opt-in local embeddings smoke no longer contains the
+private package version expectation. The test file still uses
+`@kaelio/ktx 0.0.0-private` as a negative fixture.
+
+- [ ] **Step 9: Commit**
+
+Run:
+
+```bash
+git add scripts/local-embeddings-runtime-smoke.mjs scripts/local-embeddings-runtime-smoke.test.mjs
+git commit -m "fix: align local embeddings smoke with public version"
+```
+
+## Verification
+
+Run these checks before marking the plan complete:
+
+```bash
+node --test scripts/local-embeddings-runtime-smoke.test.mjs scripts/build-public-npm-package.test.mjs scripts/package-artifacts.test.mjs
+rg -n "@kaelio/ktx 0\\.0\\.0-private|0\\\\\\.0\\\\\\.0-private" scripts/local-embeddings-runtime-smoke.mjs
+```
+
+Expected results:
+
+- `node --test ...` exits with code 0.
+- `rg ...` prints no matches.
+- No Python files changed, so the repository Python pre-commit requirement does
+  not apply.
+
+## Self-Review
+
+- Spec coverage: this plan fixes the opt-in local embeddings release smoke from
+  the npm-managed runtime spec so it validates the public npm package produced
+  by the current release artifact flow.
+- Placeholder scan: the plan contains concrete file paths, code blocks,
+  commands, and expected outcomes.
+- Type consistency: the helper name is consistently
+  `expectedPublicKtxVersionPattern`, and it uses
+  `PUBLIC_NPM_PACKAGE_NAME` plus `PUBLIC_NPM_PACKAGE_VERSION` from the public
+  package builder.