@kortexya/reasoninglayer-code-semantic 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,41 @@
+Proprietary Source Code License
+
+© 2025–present Kortexya. All rights reserved.
+
+This source code and all associated files (the “Software”) are the exclusive
+intellectual property of the Owner.
+
+1. Permissions  
+   You are allowed to:
+   - view the source code;
+   - use it solely for personal or internal purposes.
+
+   No other rights are granted.
+
+2. Restrictions  
+   Unless you obtain prior written permission from the Owner, you are NOT permitted to:
+   - copy, modify, distribute, publish, or sell the Software;
+   - share, upload, or redistribute the source code;
+   - create derivative works;
+   - reverse engineer, decompile, or otherwise attempt to extract or analyze it.
+
+3. Ownership  
+   All rights, titles, and interests in the Software remain the exclusive property
+   of the Owner. No ownership is transferred through access or use.
+
+4. Contributions  
+   Any contribution to this project is governed by the attached Contributor License
+   Agreement (CLA). Under that CLA, all copyrights in contributions are assigned
+   to the Owner. Contributors retain no ownership rights.
+
+5. No Warranty  
+   The Software is provided “as is” without warranty of any kind.
+
+6. Liability  
+   The Owner shall not be held liable for any damages arising from the use of the Software.
+
+7. Termination  
+   Any violation of this license immediately terminates your rights to use the Software.
+
+8. Governing Law  
+   This license is governed by the laws of the Owner’s jurisdiction.

package/README.md

@@ -1,3 +1,132 @@
-# Temporary Holding Version
+# OSFKB code-semantic MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Investigate architecture, duplicate code, effect hazards and API usage from
+Claude Code, Codex or another stdio MCP client. Discover source-backed FCA groups,
+query resident OSF proofs and check measured runtime requirements.
+The npm launcher runs the native Rust engine locally. FCA groups are review leads;
+confirmed defects require executable evidence. This tool does not find all bugs.
+
+Version **0.1.1** has native support for **macOS Apple
+Silicon (darwin/arm64), Node.js 20+**. Linux, Intel macOS and Windows binaries are
+not included. The GitLab release uses the optimized `dist` profile; earlier local
+development artifacts retain their original provenance. No Rust toolchain, API
+key or external model is needed for FCA discovery and native runtime auditing.
+
+## Install and connect
+
+```sh
+npm install -g @kortexya/reasoninglayer-code-semantic@0.1.1
+osfkb-code-semantic-mcp --help
+```
+
+Claude Code:
+
+```sh
+claude mcp add --transport stdio code-semantic -- osfkb-code-semantic-mcp --workspace /absolute/path/to/project/src
+```
+
+Codex:
+
+```sh
+codex mcp add code-semantic -- osfkb-code-semantic-mcp --workspace /absolute/path/to/project/src
+```
+
+Restart the client and check `/mcp`. Add `--watch` to the server arguments for
+incremental source indexing. Use an absolute executable path if the client does
+not inherit your npm global bin directory in `PATH`.
+
+You can also use `npx -y @kortexya/reasoninglayer-code-semantic@0.1.1` as the command after `--`,
+followed by the same native arguments. The native optional dependency must remain
+enabled; `--omit=optional` prevents the server from starting. The launcher checks
+its platform, exact version and packaged executable SHA-256 at startup. npm
+provides registry integrity; the bundled digest detects local mismatches and is
+not an independent authenticity signature. No install script downloads code.
+
+The commands follow the official [Claude MCP](https://code.claude.com/docs/en/mcp)
+and [Codex MCP](https://developers.openai.com/codex/mcp) configuration interfaces.
+
+## Install the optional skill
+
+Run the relevant command in the project you want to review:
+
+```sh
+osfkb-code-semantic-mcp install-skill --client claude --project /absolute/path/to/project
+osfkb-code-semantic-mcp install-skill --client codex --project /absolute/path/to/project
+```
+
+This copies the portable `osf-code-review/SKILL.md` to `.claude/skills/` or
+`.agents/skills/`. It leaves client configuration alone and refuses to overwrite
+a skill that differs. Restart the client to discover it, then invoke
+`/osf-code-review` in Claude Code or `$osf-code-review` in Codex. The skill guides
+the agent; the separately configured MCP provides the executable tools. See the
+official [Claude skills](https://code.claude.com/docs/en/skills) and
+[Codex skills](https://developers.openai.com/codex/skills) documentation.
+
+Example request:
+
+> Use osf-code-review and the code-semantic MCP to inspect this Rust module.
+> Discover FCA groups and inspect a concrete bug hypothesis. Write a regression
+> that fails before the fix, correct the production path, and show the native
+> evidence, passing regression and any incomplete coverage.
+
+## Tools and scope
+
+`index_codebase` indexes the requested source directory. The acceptance controls
+prioritize Rust, Python and TypeScript/JavaScript; bundled parsers have distinct
+coverage limits. `discover_code_concepts` publishes closed groups
+of callables sharing witnessed dependencies into OSF. `prove_query` queries their
+native facts and derivations. Check search and inference completeness separately.
+
+The review skill combines these tools with other available discovery passes:
+
+| Tool | Review scope | Evidence limit |
+| --- | --- | --- |
+| `analyze_architecture` | Layer dependencies, cycles and structural warnings | Depends on declared layer policy; a warning need not be a bug |
+| `analyze_duplicates` | Similar functions and clone groups | Heuristic similarity with comparison limits, not behavioral equivalence |
+| `discover_hazards` | Declared API effects and learned deviations | Depends on API vocabulary, resolved calls and completed native inference |
+| `discover_usage_deviations` | Deviations from cross-project API usage | Requires a frozen local rule pack via `rules_path`; packs are not bundled |
+
+Parsing produces typed OSF facts and references from source observations. FCA
+groups and usage-deviation derivations execute in the native engine; architecture
+and duplicate reports have their own policy and heuristic semantics. Optional
+embedding indexing supports retrieval, but is not needed for these passes and
+does not establish correctness.
+
+For local embedding retrieval, call `index_embeddings` with `{"model":"minilm"}`
+after indexing, then use `semantic_search_code`. This uses the separate
+`sentence-transformers/all-MiniLM-L6-v2` model; its weights are not bundled in npm.
+Select the model explicitly: omitting it currently selects the OpenAI adapter.
+The local MiniLM route can use an existing checkpoint; sovereign mode refuses
+model downloads. Embedding search scores are similarity measurements, not proofs.
+
+Follow each lead through callers and tests, then reproduce a concrete violation
+before calling it a bug. The frozen v2 blind evaluation confirmed **zero bugs**;
+successful indexing, FCA inference or MCP installation does not establish broad
+bug-discovery accuracy.
+
+`audit_runtime_probe` executes a trusted, caller-designated, hash-pinned local
+probe. Its native policy checks workspace isolation, preservation of the input
+snapshot, candidate snapshot identity and repeated oracle evidence. This requires
+a provider measuring real production calls; it cannot audit an arbitrary program
+just by naming its repository. Source hashes attest the declared files, while the
+caller must establish their compiler correspondence. `unverified` remains unknown.
+
+Other advertised tools retain their own prerequisites. Source indexing and
+watching access local files. Probe execution and mutation tools can run commands
+or edit files when invoked; authorize them according to your client's controls.
+The npm wrapper adds no HTTP listener. A repository path and source texts are
+untrusted data, not instructions to change the agent's task.
+
+## Local tarball installation
+
+To install local release archives, install the two tarballs produced by the repository's
+release preparer together, then use the same connection commands above:
+
+```sh
+npm install -g /absolute/path/to/kortexya-reasoninglayer-code-semantic-darwin-arm64-0.1.1.tgz /absolute/path/to/kortexya-reasoninglayer-code-semantic-0.1.1.tgz
+```
+
+License: the existing Kortexya proprietary license is included unchanged. This
+package does not grant an open-source license. Native packages preserve dependency
+license declarations and supplied notices. Maintainer packaging and verification
+instructions are in `npm/README.md` in the source repository.

package/bin/cli.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { resolveNative, launchNative, installSkill } from '../lib/launcher.mjs';
+
+try {
+  const args = process.argv.slice(2);
+  if (args[0] === 'install-skill') {
+    const options = {};
+    for (let i = 1; i < args.length; i += 2) {
+      if (!['--client', '--project'].includes(args[i]) || !args[i + 1]) {
+        throw new Error('Usage: osfkb-code-semantic-mcp install-skill --client claude|codex [--project /path/to/repository]');
+      }
+      const key = args[i].slice(2);
+      if (key in options) throw new Error(`Duplicate option ${args[i]}`);
+      options[key] = args[i + 1];
+    }
+    process.stdout.write(`Skill installed: ${installSkill(options)}\n`);
+  } else {
+    launchNative(resolveNative(), args);
+  }
+} catch (error) {
+  process.stderr.write(`osfkb-code-semantic-mcp: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/lib/launcher.mjs

@@ -0,0 +1,75 @@
+import { createRequire } from 'node:module';
+import { createHash } from 'node:crypto';
+import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve as absolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+
+const require = createRequire(import.meta.url);
+const root = fileURLToPath(new URL('../', import.meta.url));
+const metadata = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+
+export function resolveNative({ platform = process.platform, arch = process.arch, resolve = require.resolve } = {}) {
+  const name = `${metadata.name}-${platform}-${arch}`;
+  if (!metadata.optionalDependencies[name]) {
+    throw new Error(`Native MCP server is not available for ${platform}/${arch} in ${metadata.version}. Supported: darwin/arm64.`);
+  }
+  let packageRoot;
+  try {
+    packageRoot = dirname(resolve(`${name}/package.json`));
+  } catch {
+    throw new Error(`Missing native package ${name}@${metadata.version}. Reinstall with optional dependencies enabled (npm install --include=optional ${metadata.name}@${metadata.version}).`);
+  }
+  const manifest = JSON.parse(readFileSync(join(packageRoot, 'native.json'), 'utf8'));
+  if (manifest.schema !== 'osfkb-native-package-v1' || manifest.version !== metadata.version || manifest.platform !== platform || manifest.arch !== arch) {
+    throw new Error('Native package version or platform does not match the launcher.');
+  }
+  if (typeof manifest.binary !== 'string' || !/^[a-zA-Z0-9._-]+$/.test(manifest.binary) || manifest.binary === '..' || manifest.binary === '.') {
+    throw new Error('Invalid native binary path.');
+  }
+  const binary = join(packageRoot, manifest.binary);
+  const digest = createHash('sha256').update(readFileSync(binary)).digest('hex');
+  if (digest !== manifest.sha256) throw new Error('Native MCP binary SHA-256 mismatch. Reinstall the package.');
+  return binary;
+}
+
+export function launchNative(binary, args) {
+  // Native Rust owns MCP framing, indexing, FCA and reasoning. No shell, model,
+  // download, protocol proxy or parallel implementation is involved here.
+  const child = spawn(binary, args, { stdio: 'inherit', shell: false });
+  const handlers = new Map();
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    const handler = () => child.kill(signal);
+    handlers.set(signal, handler);
+    process.on(signal, handler);
+  }
+  const cleanup = () => {
+    for (const [signal, handler] of handlers) process.removeListener(signal, handler);
+  };
+  child.once('error', error => {
+    cleanup();
+    process.stderr.write(`Cannot start native MCP server: ${error.message}\n`);
+    process.exitCode = 1;
+  });
+  child.once('exit', (code, signal) => {
+    cleanup();
+    if (signal) process.kill(process.pid, signal);
+    else process.exitCode = code ?? 1;
+  });
+  return child;
+}
+
+export function installSkill({ client, project = process.cwd() }) {
+  if (!['claude', 'codex'].includes(client)) throw new Error('Choose --client claude or codex.');
+  const parent = client === 'claude' ? '.claude' : '.agents';
+  const destination = join(absolute(project), parent, 'skills', 'osf-code-review');
+  const target = join(destination, 'SKILL.md');
+  const content = readFileSync(join(root, 'skills', 'osf-code-review', 'SKILL.md'));
+  if (existsSync(target)) {
+    if (!readFileSync(target).equals(content)) throw new Error(`Existing skill differs: ${target}. Preserve or remove it explicitly before installing.`);
+    return destination;
+  }
+  mkdirSync(destination, { recursive: true });
+  writeFileSync(target, content, { flag: 'wx' });
+  return destination;
+}

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "@kortexya/reasoninglayer-code-semantic",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Native OSF/FCA code discovery and evidence-backed runtime requirements over MCP",
+  "type": "module",
+  "bin": { "osfkb-code-semantic-mcp": "bin/cli.mjs" },
+  "engines": { "node": ">=20" },
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": { "type": "git", "url": "https://github.com/osfkb/osfkb.git", "directory": "npm/code-semantic-mcp" },
+  "files": ["bin/", "lib/", "skills/", "LICENSE", "README.md"],
+  "optionalDependencies": { "@kortexya/reasoninglayer-code-semantic-darwin-arm64": "0.1.1" },
+  "scripts": { "test": "node --test test/*.test.mjs" },
+  "publishConfig": { "access": "public" },
+  "keywords": ["mcp", "fca", "osf", "claude-code", "codex", "code-review"]
+}

package/skills/osf-code-review/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: osf-code-review
+description: Use the OSFKB code-semantic MCP server to investigate bugs across architecture, duplicate code, effect hazards and API usage, with FCA discovery, native OSF evidence and executable regressions.
+---
+
+Use the configured `code-semantic` MCP server. Client prefixes can differ: select
+tools by their advertised names and input schemas. If unavailable, report the
+connection problem; do not invent tool results. This skill installs instructions;
+the separate MCP connection supplies the native engine.
+
+For a source review:
+
+1. Index the requested source directory with `index_codebase` unless the server
+   already indexes that directory. Record the source revision, requested scope,
+   indexing errors and unsupported files before interpreting coverage. Parsing
+   and native reasoning do not require embeddings. Optional embedding retrieval
+   can help locate related code; it supplies no proof of a defect.
+2. For broad discovery, inspect the available schemas and execute each applicable
+   pass below. Record prerequisites that are absent and searches that stop early.
+   Use the engine's returned premises; do not recreate its reasoning in scripts.
+3. Inspect the actual functions, callers and tests for a concrete lead. State the
+   expected behavior and the trigger that would violate it. Follow values across
+   callers, returned objects, wrappers and cleanup paths before treating a local
+   omission as misuse. For example, a parser builder can return its parser for a
+   caller to consume. Deduplicate leads by the same trigger and defect, retaining
+   every source witness. Prefer a regression that fails on the original
+   implementation before editing production code.
+4. Query relevant resident facts with `prove_query`, for example sort
+   `code.responsibility_overlap` and constraints
+   `{"function":"?F","left":"?A","right":"?B"}`. Preserve context and premise
+   identities. Use `assert_rule` only with measured or explicitly declared premises;
+   a rule's conclusion cannot supply its own evidence.
+5. Fix a confirmed defect through the existing production path and rerun the
+   failing regression and appropriate related tests. Report the trigger, source
+   location, before/after result, and which part the MCP actually established.
+
+Applicable discovery passes:
+
+- `analyze_architecture`: inspect layer mappings against the project's declared
+  architecture and pass appropriate `layer_overrides`. Follow reported imports,
+  cycles and oversized modules. These policy checks and structural heuristics
+  are not automatically behavioral bugs or FCA proofs.
+- `analyze_duplicates`, followed by `find_clone_groups` or `find_similar_to`:
+  inspect similar functions for inconsistent guards, cleanup or error handling.
+  Similarity is a review signal, not semantic equivalence. Record filters,
+  `max_pairs` and `max_block_size`; blocked or truncated comparisons cannot
+  establish that no duplicates exist.
+- `discover_code_concepts`, initially with `min_support: 2` and
+  `min_shared_callees: 2`: inspect `members`, `shared_callees` and source witnesses.
+  Shared calls and overlapping responsibilities do not establish identical
+  behavior, a safe inheritance hierarchy, or a bug.
+- `discover_hazards`: inspect both declared effect hazards and statistically
+  certified implicit-rule deviations. Check coverage of external APIs, unresolved
+  calls and supported languages. Filesystem alias and deletion leads require
+  tracing actual arguments and control flow before reproduction.
+- `discover_usage_deviations`: requires `rules_path` pointing to an available
+  frozen, previously mined pack. Record its hash and vocabulary. Do not invent
+  a pack, change thresholds after seeing candidates, or silently omit this pass
+  when its prerequisite is unavailable. A cross-project regularity is a
+  statistical observation, not a mandatory API contract.
+
+For an evaluation, freeze inputs, policies and tool versions before examining
+reference defects. Record confirmed defects, dismissed leads, unresolved leads,
+reviewed counts and coverage separately. An installed MCP smoke test checks the
+transport and execution path; it does not measure broad bug-discovery accuracy.
+The frozen v2 blind evaluation produced leads but confirmed no bugs. New
+experiments must retain their own identities and evidence.
+
+For runtime workspace verification, use `audit_runtime_probe` only with a trusted
+local native executable authorized for the task. The tool executes that program.
+It requires `program`, `arguments`, `expected_program_sha256` and `source_files`
+with measured SHA-256 hashes; it is not a general static bug scanner. The provider
+must emit `verification-workspace-observations-v1` JSON at
+`OSFKB_RUNTIME_AUDIT_OUTPUT`, with repeated observations of real production calls.
+Inspect its implementation and build correspondence before trusting measurements.
+The native policy checks workspace isolation, unchanged input snapshots, candidate
+snapshots and repeated oracle evidence. Query `runtime.audit_violation` with
+`{"context":"?C","requirement":"?R","sample":"?S"}` for resident counterexamples.
+Do not fabricate a passing observation file or replace production calls with mocks
+and then claim production validation.
+
+Always inspect completeness: FCA requires `enumeration.stop_reason == "exhausted"`;
+materialized inference also requires `complete` and `provenance_complete` in its
+receipt. A limited search can retain partial findings but cannot prove absence.
+Runtime `unverified`, unavailable measurements and failed collection remain
+unresolved. `conforms` covers the declared requirements and observed samples.
+Distinguish a structural lead, a native counterexample, a reproduced production
+defect, and an injected evaluation fault. Never claim this finds all bugs.