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

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:

import {
  buildLocalEmbeddingsSmokeEnv,
  expectedPublicKtxVersionPattern,
  localEmbeddingsSmokeCommands,
  localEmbeddingsSmokeOptIn,
  parseDaemonBaseUrl,
  publicKtxTarballName,
  validateEmbeddingResponse,
} from './local-embeddings-runtime-smoke.mjs';

Then add this test after the publicKtxTarballName describe block:

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:

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:

import {
  PUBLIC_NPM_PACKAGE_NAME,
  PUBLIC_NPM_PACKAGE_VERSION,
} from './build-public-npm-package.mjs';

The top of the file becomes:

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:

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:

requireOutput(commands[0].label, version, /@kaelio\/ktx 0\.0\.0-private/);

with:

requireOutput(commands[0].label, version, expectedPublicKtxVersionPattern());

• Step 6: Run the focused test

Run:

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:

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:

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:

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:

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.