fix: use dedicated embedding context lifecycle

Author: William

.github/workflows/release.yml

@@ -22,20 +22,14 @@ jobs:
           node-version: 20
           registry-url: https://registry.npmjs.org
 
-      - name: Validate tag matches package version
-        run: |
-          PKG_VERSION=$(node -p "require('./package.json').version")
-          TAG_VERSION="${GITHUB_REF_NAME#v}"
-          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
-            echo "Tag version ($TAG_VERSION) does not match package.json version ($PKG_VERSION)"
-            exit 1
-          fi
+      - name: Validate release
+        run: npm run verify:release -- "$GITHUB_REF_NAME" --check-registry
 
       - name: Install dependencies
         run: npm ci
 
-      - name: Build package
-        run: npm run build
+      - name: Test package
+        run: npm test && npm run typecheck && npm audit
 
       - name: Pack package
         run: npm pack --dry-run

CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## [0.3.0] - 2026-07-14
+
+### Changed
+
+- Added a dedicated, branded embedding-context handle and required
+  `freeEmbeddingContext` native destructor. Native adapters must implement the
+  updated contract before upgrading.
+- Reject embedding operations after disposal before tokenization begins.
+
+### Security
+
+- Updated locked build dependencies to patched versions.
+
+[0.3.0]: https://github.com/hilum-labs/local-llm-js-core/releases/tag/v0.3.0

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "local-llm-js-core",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Shared core runtime and native contract for local-llm packages",
   "type": "module",
   "main": "dist/index.js",
@@ -20,11 +20,14 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
     "build": "tsup src/index.ts src/native.ts --format esm --dts",
+    "test": "npm run build && node --test tests/*.test.mjs",
     "typecheck": "tsc --noEmit",
+    "verify:release": "node scripts/validate-release.mjs",
     "release": "node scripts/release.mjs"
   },
   "keywords": [
@@ -47,5 +50,8 @@
   "devDependencies": {
     "tsup": "^8.0.0",
     "typescript": "^5.4.0"
+  },
+  "overrides": {
+    "esbuild": "^0.28.1"
   }
 }

package.json

@@ -3,7 +3,7 @@
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import { spawnSync } from 'node:child_process';
-import { readFileSync, writeFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -29,12 +29,23 @@ function run(cmd, args, opts = {}) {
   return (res.stdout || '').trim();
 }
 
-function readPackageJson() {
-  return JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+function ensureVersionAvailableOnNpm(pkgName, version) {
+  const result = spawnSync('npm', ['view', `${pkgName}@${version}`, 'version'], {
+    cwd: repoRoot,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+  });
+  if (result.status === 0) throw new Error(`${pkgName}@${version} is already published on npm.`);
+
+  const output = `${result.stdout || ''}\n${result.stderr || ''}`;
+  if (!/E404|404 Not Found/i.test(output)) {
+    if (output.trim()) console.error(output.trim());
+    throw new Error(`Could not verify npm availability for ${pkgName}@${version}.`);
+  }
 }
 
-function writePackageJson(pkg) {
-  writeFileSync(packageJsonPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+function readPackageJson() {
+  return JSON.parse(readFileSync(packageJsonPath, 'utf8'));
 }
 
 function parseSemver(v) {
@@ -74,14 +85,16 @@ async function main() {
 
     console.log(`Current version: ${current}`);
     console.log('Select release type:');
+    console.log('0) release current prepared version');
     console.log('1) patch');
     console.log('2) minor');
     console.log('3) major');
     console.log('4) custom');
 
     const choice = (await rl.question('Choice [1]: ')).trim() || '1';
     let nextVersion;
-    if (choice === '1') nextVersion = bump(current, 'patch');
+    if (choice === '0') nextVersion = current;
+    else if (choice === '1') nextVersion = bump(current, 'patch');
     else if (choice === '2') nextVersion = bump(current, 'minor');
     else if (choice === '3') nextVersion = bump(current, 'major');
     else if (choice === '4') {
@@ -104,12 +117,23 @@ async function main() {
     ensureCleanGit();
     ensureMainBranch();
     run('git', ['pull', '--rebase']);
+    ensureVersionAvailableOnNpm(pkg.name, nextVersion);
 
-    pkg.version = nextVersion;
-    writePackageJson(pkg);
+    if (nextVersion !== current) {
+      run('npm', ['version', nextVersion, '--no-git-tag-version']);
+    }
+
+    run('npm', ['ci']);
+    run('npm', ['test']);
+    run('npm', ['run', 'typecheck']);
+    run('npm', ['audit']);
+    run('npm', ['pack', '--dry-run']);
+    run('npm', ['run', 'verify:release', '--', tag]);
 
-    run('git', ['add', 'package.json', '.github/workflows/release.yml', 'scripts/release.mjs']);
-    run('git', ['commit', '-m', `chore(release): v${nextVersion}`]);
+    if (nextVersion !== current) {
+      run('git', ['add', 'package.json', 'package-lock.json']);
+      run('git', ['commit', '-m', `chore(release): v${nextVersion}`]);
+    }
     run('git', ['tag', '-a', tag, '-m', tag]);
     run('git', ['push', 'origin', 'HEAD']);
     run('git', ['push', 'origin', tag]);

scripts/release.mjs

@@ -0,0 +1,31 @@
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+const args = process.argv.slice(2).filter((arg) => arg !== '--');
+const tag = args.find((arg) => arg !== '--check-registry') ?? process.env.GITHUB_REF_NAME;
+const checkRegistry = args.includes('--check-registry');
+if (!tag?.startsWith('v') || !/^\d+\.\d+\.\d+$/.test(tag.slice(1))) {
+  throw new Error(`expected a v-prefixed semantic version tag; received ${JSON.stringify(tag)}`);
+}
+
+const manifest = JSON.parse(readFileSync('package.json', 'utf8'));
+const version = tag.slice(1);
+if (manifest.version !== version) {
+  throw new Error(`package.json has version ${manifest.version}; expected ${version} from tag ${tag}`);
+}
+
+if (checkRegistry) {
+  const spec = `${manifest.name}@${version}`;
+  const result = spawnSync('npm', ['view', spec, 'version'], { encoding: 'utf8' });
+  if (result.status === 0) {
+    throw new Error(`${spec} is already published`);
+  }
+
+  const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`;
+  if (!/E404|404 Not Found/i.test(output)) {
+    process.stderr.write(output);
+    throw new Error(`could not verify npm availability for ${spec}`);
+  }
+}
+
+console.log(`Validated ${manifest.name}@${version}`);

scripts/validate-release.mjs

@@ -1,4 +1,11 @@
-import { getNativeAddon, type NativeAddon, type NativeModel, type NativeContext, type NativeMtmdContext } from './native.js';
+import {
+  getNativeAddon,
+  type NativeAddon,
+  type NativeContext,
+  type NativeEmbeddingContext,
+  type NativeModel,
+  type NativeMtmdContext,
+} from './native.js';
 import type {
   ModelOptions,
   ContextOptions,
@@ -832,10 +839,10 @@ function poolingTypeToNative(pooling: EmbeddingPoolingType): number {
 export class EmbeddingContext {
   private native: NativeAddon;
   private modelHandle: NativeModel;
-  private handle: NativeContext | null;
+  private handle: NativeEmbeddingContext | null;
   private dimensionValue: number;
 
-  constructor(native: NativeAddon, modelHandle: NativeModel, handle: NativeContext, dimension: number) {
+  constructor(native: NativeAddon, modelHandle: NativeModel, handle: NativeEmbeddingContext, dimension: number) {
     this.native = native;
     this.modelHandle = modelHandle;
     this.handle = handle;
@@ -846,24 +853,26 @@ export class EmbeddingContext {
     return this.dimensionValue;
   }
 
-  private ensureHandle(): NativeContext {
+  private ensureHandle(): NativeEmbeddingContext {
     if (!this.handle) throw new Error('EmbeddingContext has been disposed');
     return this.handle;
   }
 
   embed(text: string): Float32Array {
+    const handle = this.ensureHandle();
     const tokens = this.native.tokenize(this.modelHandle, text);
-    return this.native.embed(this.ensureHandle(), this.modelHandle, tokens);
+    return this.native.embed(handle, this.modelHandle, tokens);
   }
 
   embedBatch(texts: string[]): Float32Array[] {
+    const handle = this.ensureHandle();
     const tokenArrays = texts.map((text) => this.native.tokenize(this.modelHandle, text));
-    return this.native.embedBatch(this.ensureHandle(), this.modelHandle, tokenArrays);
+    return this.native.embedBatch(handle, this.modelHandle, tokenArrays);
   }
 
   dispose(): void {
     if (this.handle) {
-      this.native.freeContext(this.handle);
+      this.native.freeEmbeddingContext(this.handle);
       this.handle = null;
     }
   }

src/engine.ts

@@ -3,6 +3,7 @@ type Brand<T, B> = T & { readonly [__brand]: B };
 
 export type NativeModel = Brand<object, 'NativeModel'>;
 export type NativeContext = Brand<object, 'NativeContext'>;
+export type NativeEmbeddingContext = Brand<object, 'NativeEmbeddingContext'>;
 export type NativeMtmdContext = Brand<object, 'NativeMtmdContext'>;
 
 export interface NativeAddon {
@@ -181,10 +182,11 @@ export interface NativeAddon {
   createEmbeddingContext(
     model: NativeModel,
     options?: { n_ctx?: number; n_batch?: number; n_threads?: number; pooling_type?: number },
-  ): NativeContext;
+  ): NativeEmbeddingContext;
 
-  embed(ctx: NativeContext, model: NativeModel, tokens: Int32Array): Float32Array;
-  embedBatch(ctx: NativeContext, model: NativeModel, tokenArrays: Int32Array[]): Float32Array[];
+  freeEmbeddingContext(ctx: NativeEmbeddingContext): void;
+  embed(ctx: NativeEmbeddingContext, model: NativeModel, tokens: Int32Array): Float32Array;
+  embedBatch(ctx: NativeEmbeddingContext, model: NativeModel, tokenArrays: Int32Array[]): Float32Array[];
 
   quantize(
     inputPath: string,

src/native.ts

@@ -0,0 +1,25 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { EmbeddingContext } from '../dist/index.js';
+
+test('EmbeddingContext uses the embedding destructor exactly once', () => {
+  const model = {};
+  const handle = {};
+  const calls = [];
+  const native = {
+    freeContext() {
+      assert.fail('EmbeddingContext must not call freeContext');
+    },
+    freeEmbeddingContext(value) {
+      calls.push(value);
+    },
+  };
+
+  const context = new EmbeddingContext(native, model, handle, 384);
+  context.dispose();
+  context.dispose();
+
+  assert.deepEqual(calls, [handle]);
+  assert.throws(() => context.embed('disposed'), /EmbeddingContext has been disposed/);
+});