@reunionstudio/airlock-mcp 0.1.9 → 0.1.10

package/.agents/skills/airlock-mcp/SKILL.md

@@ -83,6 +83,12 @@ deterministic checker for local spec drafts.
    `airlock.admin.sync_okf_bundle_metadata(...)`, and exposes authoritative
    accepted context through `AIRLOCK_DATA.ACTIVE.V_OKF_CONCEPT_METADATA`.
    Draft and rejected bundles are not authoritative agent context.
+   Use OKF v0.2 `generated`, `sources`, `verified`, and lifecycle metadata;
+   legacy v0.1 bundles still work. See the pattern README for field shapes.
+   Verification and `status: stable` are producer claims, not Airlock approval
+   or authenticated identities. Neither `human:` nor other producer labels
+   grant authority. Never execute bundle computations or attesters as part of
+   validation/loading. Airlock retains its bounded Markdown-only profile.
 6. Use `airlock-mcp import-spec <json-file> <name>` when starting from a
    spec-library file, an exported `SPEC_CONFIG`, or an existing canonical config.
    If the source is from `airlock-specs`, treat it as a reusable draft pattern.

package/.cortex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "airlock-mcp",
   "description": "Governed Airlock spec, observation, and commitment guidance for Snowflake principals.",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "author": {
     "name": "Reunion Studio",
     "url": "https://github.com/reunionstudio/airlock-mcp"
@@ -15,7 +15,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@reunionstudio/airlock-mcp@0.1.9",
+        "@reunionstudio/airlock-mcp@0.1.10",
         "server"
       ]
     }

package/SECURITY.md

@@ -12,6 +12,12 @@ operation surface.
 - Validates MCP server names before passing them to `codex mcp add`.
 - Passes npm or GitHub package specs as argv entries, never through a shell.
 - Rejects package specs with whitespace or control characters.
+- Runs the bundled Python workbench in isolated mode from a trusted launcher;
+  project modules, user site-packages, and ambient `PYTHONPATH` do not enter its
+  import path. The selected Python interpreter and installed system packages
+  remain trusted. `cwd` controls workspace paths, not code discovery.
+- Rejects malformed JSON-RPC envelopes without terminating the server.
+  Notifications never dispatch side-effecting workbench tools.
 - Does not read local secrets, call Snowflake, or contact network services.
   Workbench tools write only the project files explicitly requested by the
   caller.

package/docs/workflows.md

@@ -425,6 +425,11 @@ Do not treat draft or rejected Markdown bundles as authoritative agent context.
 The MCP local checker validates the spec workspace; bundle validation belongs
 to Airlock's OKF validator and installed procedures.
 
+The [pattern README](../patterns/okf-knowledge-bundle/README.md) describes the
+OKF v0.2 profile and backward compatibility. Preserve provenance, verification,
+and lifecycle claims as metadata. Never interpret them as Airlock permission or
+approval, and never run a computation or attester during bundle loading.
+
 ## Start From A Known Process
 
 Use this when the process is known but the data shape is not.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reunionstudio/airlock-mcp",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Single-install MCP interface for Airlock agents.",
   "type": "module",
   "repository": {
@@ -22,7 +22,7 @@
     "airlock-mcp": "bin/airlock-mcp.mjs"
   },
   "scripts": {
-    "test": "node test/smoke.mjs"
+    "test": "node test/smoke.mjs && node test/mcp-boundaries.mjs"
   },
   "files": [
     "bin",

package/patterns/okf-knowledge-bundle/README.md

@@ -4,7 +4,7 @@ Use `okf-knowledge-bundle` when the team wants governed Markdown knowledge for
 people and agents to use as accepted business context.
 
 This pattern is for Airlock's `okf_knowledge_bundle` payload adapter. It is
-inspired by Google's Open Knowledge Format, but Airlock applies a narrower
+aligned with Google's Open Knowledge Format v0.2, but Airlock applies a narrower
 profile so accepted bundles can become governed context instead of loose wiki
 content.
 
@@ -25,9 +25,44 @@ content.
 - Every non-reserved Markdown file is a concept document with YAML frontmatter.
 - Concept documents require `type`.
 - Recommended concept fields are `title`, `description`, `resource`, `tags`,
-  `timestamp`, and `source_links`.
+  `generated`, and `sources`. Legacy v0.1 `timestamp` and `source_links` work too.
+- New root indexes should declare `okf_version: "0.2"`.
 - `index.md` and `log.md` are reserved at every hierarchy level.
 
+## V0.2 Example
+
+```markdown
+---
+type: Metric
+title: Net Revenue
+generated: {by: process:finance-context, at: "2026-09-01T00:00:00Z"}
+verified: {by: process:finance-check, at: "2026-09-02T00:00:00Z"}
+status: stable
+stale_after: "2026-10-01T00:00:00Z"
+sources:
+  - id: revenue-policy
+    resource: https://example.com/revenue-policy
+---
+Revenue less refunds and adjustments.[^revenue-policy]
+
+[^revenue-policy]: Finance revenue policy
+```
+
+Airlock normalizes a single `verified` object to an array and preserves source
+IDs, producer identities, freshness, and extension fields in each parsed row's
+`metadata`. All v0.2 datetimes need an explicit UTC offset. Optional families
+may be omitted. External body links can be declared by `sources[].resource`
+or legacy `source_links`. The existing timestamp projection uses `generated.at`
+when `generated` exists, otherwise legacy `timestamp`.
+
+`status: stable` and `verified` are producer claims, not Airlock approval or
+authenticated identities. A `human:` verifier has no extra authority. Airlock
+workflow, PDP, and separately configured Expectations remain authoritative;
+`stale_after` does not create an Expectation. `Attested Computation` descriptors
+can be stored, but Airlock does not execute computations or attesters, fetch
+their resources, or verify their results. Bundles remain Markdown-only with
+bounded size and strict paths/body links, not universal OKF v0.2 packages.
+
 ## Airlock Contract
 
 The spec must declare:
@@ -54,7 +89,11 @@ authoritative only from:
 AIRLOCK_DATA.ACTIVE.V_OKF_CONCEPT_METADATA
 ```
 
-Draft and rejected bundles are not authoritative agent context.
+Draft and rejected bundles are not authoritative agent context. In the view,
+normalized frontmatter is under `METADATA:metadata`, not top-level columns
+named after every new OKF field. Verify that the installed Airlock release
+includes the v0.2 metadata update before relying on its normalization; updating
+this local MCP package does not deploy the Native App.
 
 ## Local Workbench Notes
 

package/patterns/okf-knowledge-bundle/sample.records.json

@@ -5,12 +5,12 @@
     {
       "concept_path": "runbooks/monthly-close",
       "concept_type": "Runbook",
-      "bundle_version": "2026.06"
+      "bundle_version": "2026.09"
     },
     {
       "concept_path": "metrics/net-revenue",
       "concept_type": "Metric",
-      "bundle_version": "2026.06"
+      "bundle_version": "2026.09"
     }
   ]
 }

package/patterns/okf-knowledge-bundle/spec.config.json

@@ -55,7 +55,7 @@
   "sample_data": {
     "sample_data_acknowledged": true,
     "sample_rows": [],
-    "edited_sample_data": "concept_path,concept_type,bundle_version\nrunbooks/monthly-close,Runbook,2026.06\nmetrics/net-revenue,Metric,2026.06\n"
+    "edited_sample_data": "concept_path,concept_type,bundle_version\nrunbooks/monthly-close,Runbook,2026.09\nmetrics/net-revenue,Metric,2026.09\n"
   },
   "attachment_policy": {
     "attachments_enabled": true,

package/setup.py

@@ -27,7 +27,7 @@ def data_files():
 
 setup(
     name="airlock-mcp",
-    version="0.1.9",
+    version="0.1.10",
     description="Codex-first workbench and CLI for drafting Airlock specs.",
     packages=find_packages("src"),
     package_dir={"": "src"},

package/src/airlock_mcp/__init__.py

@@ -1,3 +1,3 @@
 """Airlock MCP CLI package."""
 
-__version__ = "0.1.9"
+__version__ = "0.1.10"

package/src/airlock_mcp/app_context.py

@@ -20,6 +20,14 @@ The canonical specs live in the specs repo or installed Airlock. Files here are
 snapshots, samples, generated helpers, and planning context for app development.
 Refresh them when the canonical spec changes.
 
+For governed knowledge, the `okf-knowledge-bundle` pattern uses Airlock's bounded
+Markdown-only OKF v0.2 profile with legacy v0.1 support. Producer `verified`,
+`generated`, lifecycle, and computation metadata do not grant Airlock authority
+or approval. Loading never executes computations or attesters. Consume current
+accepted context through `AIRLOCK_DATA.ACTIVE.V_OKF_CONCEPT_METADATA`; normalized
+frontmatter is under `METADATA:metadata`. Verify the installed Airlock release
+supports v0.2 normalization before relying on it.
+
 Airlock's built-in Streamlit Native App is a generic operating and fallback
 surface. A purpose-built app is the preferred place for domain-specific
 summaries, calculations, evidence layout, terminology, and controls when those

package/src/airlock_mcp/bootstrap.py

@@ -86,6 +86,13 @@ plan for more. Do not create the first workspace until the user chooses a path.
 Create `posts` only when the user wants a shared feedback loop or explicitly
 asks for the posts pattern.
 
+For governed Markdown knowledge, use `okf-knowledge-bundle`. The Airlock profile
+supports OKF v0.2 provenance, verification, and lifecycle metadata with legacy
+v0.1 support. Read the pattern README for examples. `verified` and
+`status: stable` are producer claims, never Airlock permissions or acceptance.
+Bundle loading does not execute computations or attesters. Use the bounded
+Markdown-only profile and verify the installed Airlock release has the update.
+
 ## Building Apps With Existing Specs
 
 Use this path when the user wants to build an app, dashboard, approval queue,

package/src/airlock_mcp/launcher.py

@@ -0,0 +1,10 @@
+"""Start the bundled workbench under Python isolated mode (including Python 3.9)."""
+
+from pathlib import Path
+import runpy
+import sys
+
+
+if __name__ == "__main__":
+    sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+    runpy.run_module("airlock_mcp", run_name="__main__")

package/src/mcp.mjs

@@ -38,6 +38,21 @@ export function makeError(id, code, message) {
 }
 
 export function handleMcpRequest(message) {
+  const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+  const validId = typeof message?.id === "string" || (typeof message?.id === "number" && Number.isFinite(message.id));
+  if (
+    !isObject(message) ||
+    message.jsonrpc !== "2.0" ||
+    typeof message.method !== "string" ||
+    !message.method ||
+    (Object.hasOwn(message, "id") && !validId) ||
+    (Object.hasOwn(message, "params") && !isObject(message.params))
+  ) {
+    return makeError(validId ? message.id : null, -32600, "invalid request");
+  }
+  // Notifications have no response and must not dispatch side-effecting tools.
+  if (!Object.hasOwn(message, "id")) return undefined;
+
   const { id, method, params } = message;
 
   if (method === "initialize") {
@@ -50,7 +65,7 @@ export function handleMcpRequest(message) {
       },
       serverInfo: {
         name: "airlock",
-        version: "0.1.9",
+        version: "0.1.10",
       },
       instructions:
         "Airlock MCP is the local spec workbench and app-context bootstrap server. Use airlock_start for orientation or the airlock_* tools to bootstrap, draft, check, summarize, export, and render specs. Installed Airlock can separately expose opt-in Snowflake-managed read-only MCP endpoints; read airlock://native-app-managed-mcp for their fixed tools and security boundary.",
@@ -183,18 +198,13 @@ export async function runServer({ input = process.stdin, output = process.stdout
       continue;
     }
 
-    if (message.id === undefined) {
-      handleMcpRequest(message);
-      continue;
-    }
-
     try {
       const response = handleMcpRequest(message);
       if (response) {
         output.write(encodeMessage(response));
       }
     } catch (error) {
-      output.write(encodeMessage(makeError(message.id, -32603, error.message)));
+      output.write(encodeMessage(makeError(message?.id ?? null, -32603, error.message)));
     }
   }
 }

package/src/text.mjs

@@ -332,6 +332,11 @@ creates a spec with \`core_config.payload_adapter\` set to
 \`airlock.admin.load_okf_bundle(...)\`, can sync parsed metadata with
 \`airlock.admin.sync_okf_bundle_metadata(...)\`, and exposes authoritative
 accepted context through \`AIRLOCK_DATA.ACTIVE.V_OKF_CONCEPT_METADATA\`.
+The profile supports OKF v0.2 provenance, verification, and lifecycle metadata,
+with legacy v0.1 support. Read the pattern README for examples. Verification
+claims and \`status: stable\` do not grant Airlock approval or permissions.
+Bundles remain bounded Markdown-only packages; loading never executes a
+computation or attester. This MCP workbench does not deploy that Native App update.
 
 Give Codex the messy version of the process. Airlock MCP should help turn it
 into a small first Airlock spec and a plan for more.

package/src/workbench.mjs

@@ -1,4 +1,4 @@
-import { existsSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
@@ -24,6 +24,9 @@ const workspaceProperty = {
 };
 
 const appModeValues = ["spec-first", "app-first", "co-development"];
+const patternValues = JSON.parse(
+  readFileSync(new URL("../patterns/manifest.json", import.meta.url), "utf8"),
+).patterns.map((pattern) => pattern.name);
 
 export const WORKBENCH_TOOLS = [
   {
@@ -82,7 +85,7 @@ export const WORKBENCH_TOOLS = [
       {
         pattern: {
           type: "string",
-          enum: ["blank", "okf-knowledge-bundle", "posts"],
+          enum: patternValues,
           description: "Pattern to inspect.",
         },
         files: {
@@ -106,7 +109,7 @@ export const WORKBENCH_TOOLS = [
         },
         pattern: {
           type: "string",
-          enum: ["blank", "okf-knowledge-bundle", "posts"],
+          enum: patternValues,
           description: "Starting pattern. Defaults to blank.",
         },
         output: {
@@ -330,12 +333,12 @@ function cliArgsForTool(name, args = {}) {
     case "airlock_list_patterns":
       return { cwd, cliArgs: ["list-patterns"] };
     case "airlock_show_pattern": {
-      const cliArgs = ["show-pattern", requiredEnum(args, "pattern", ["blank", "posts"])];
+      const cliArgs = ["show-pattern", requiredEnum(args, "pattern", patternValues)];
       if (optionalBoolean(args, "files")) cliArgs.push("--files");
       return { cwd, cliArgs };
     }
     case "airlock_init_workspace": {
-      const cliArgs = ["init", requiredString(args, "name"), "--pattern", optionalEnum(args, "pattern", ["blank", "posts"], "blank")];
+      const cliArgs = ["init", requiredString(args, "name"), "--pattern", optionalEnum(args, "pattern", patternValues, "blank")];
       maybePush(cliArgs, "--output", optionalString(args, "output", undefined));
       if (force) cliArgs.push("--force");
       return { cwd, cliArgs };
@@ -374,15 +377,15 @@ function cliArgsForTool(name, args = {}) {
 export function runWorkbenchCli(cliArgs, { cwd, env = process.env, spawn = spawnSync } = {}) {
   const root = packageRoot();
   const python = env.AIRLOCK_MCP_PYTHON || env.PYTHON || "python3";
-  const pythonPath = [path.join(root, "src"), env.PYTHONPATH].filter(Boolean).join(path.delimiter);
-  const result = spawn(python, ["-m", "airlock_mcp", ...cliArgs], {
+  // Keep cwd for workspace paths, but never import Python code from that project.
+  const launcher = path.join(root, "src", "airlock_mcp", "launcher.py");
+  const result = spawn(python, ["-I", launcher, ...cliArgs], {
     cwd,
     encoding: "utf8",
     maxBuffer: OUTPUT_MAX_BUFFER,
     env: {
       ...env,
       AIRLOCK_MCP_HOME: root,
-      PYTHONPATH: pythonPath,
     },
   });