@reunionstudio/airlock-mcp 0.1.4 → 0.1.5

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

@@ -227,6 +227,25 @@ as `admin.list_specs`, `admin.describe_role`, `admin.get_spec`, or
 Use `admin.*` only when the app is intentionally changing Airlock setup or
 running an admin operation.
 
+Restricted references are one-record interaction contracts for read-only
+reference specs. If `agent.describe_spec`, `observe.spec`,
+`observe.spec_config`, or `observe.reference_context` shows
+`restricted_reference` or `reference_config.restricted_reference`, do not
+enumerate the protected reference, build a populated picker, or use broad
+`agent.select_reference_data` for that object path. Get the lookup value from
+the user's case/work context, then call `agent.get_reference_record` with the
+configured `object_key`, lookup value, purpose, and role lens. The procedure
+returns at most one `RECORD`, applies reference row filters, checks active
+`action_limit` Expectations before returning data, and records the safe
+`REFERENCE_READ` event used for usage budgeting. Branch on stable codes such
+as `OK`, `NOT_FOUND`, `NON_UNIQUE_LOOKUP_KEY`, `PURPOSE_REQUIRED`,
+`USAGE_LIMIT_BLOCKED`, and `REFERENCE_READ_EVENT_FAILED`; expose
+`USAGE_CONTEXT` fields such as `action_limit_used` and `action_time_period`.
+For read-only planning and audit, use `observe.reference_context`,
+`observe.usage_limits`, `observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+without querying raw reference rows.
+
 Help the app follow the loop:
 
 - Observe/read: fetch existing governed data through approved Airlock or

package/README.md

@@ -221,6 +221,25 @@ For app-first work against installed Airlock, start with `observe.procedures`,
 before designing direct SQL helpers. These payloads are intended to be useful
 to agents as well as humans.
 
+Restricted references are one-record interaction contracts. When
+`observe.reference_context`, `observe.spec_config`, or `agent.describe_spec`
+shows `restricted_reference` or `reference_config.restricted_reference`, agents
+must not call broad
+`agent.select_reference_data` for that object path and must not enumerate values
+or build a populated picker from the protected reference. The agent should get
+the lookup value from the user's case/work context, then call
+`agent.get_reference_record` with the configured `object_key`, lookup value,
+purpose, and role lens. The procedure applies configured reference row filters,
+checks active `action_limit` Expectations before returning a record, always
+records the safe `REFERENCE_READ` event used for budgeting, and returns at most
+one `RECORD`. Branch on codes such as `OK`, `NOT_FOUND`,
+`NON_UNIQUE_LOOKUP_KEY`, `PURPOSE_REQUIRED`, `USAGE_LIMIT_BLOCKED`, and
+`REFERENCE_READ_EVENT_FAILED`, and report `USAGE_CONTEXT` fields such as
+`action_limit_used` and `action_time_period`. Auditors and planning agents can
+inspect `observe.usage_limits`, `observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+without reading raw reference rows.
+
 For governed Markdown knowledge, use the `okf-knowledge-bundle` pattern. It
 sets `core_config.payload_adapter` to `okf_knowledge_bundle` so installed
 Airlock can load locally validated bundles through

package/docs/install-surface.md

@@ -30,6 +30,13 @@ For installed Airlock access, teach the current procedure split:
 administrative mutation. App-first and audit-style workflows should use
 observe payloads for discovery, context, health, access explanation, activity,
 billing events, and governance maps before considering custom SQL helpers.
+When a read-only reference spec declares `restricted_reference` or
+`reference_config.restricted_reference`, agents should avoid broad
+`agent.select_reference_data` reads and use `agent.get_reference_record` for a
+known lookup value and purpose, with `observe.reference_context`,
+`observe.usage_limits`, `observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+for planning and audit.
 
 The connector package and MCP server live in `reunionstudio/airlock-mcp`.
 This workbench provides the spec-building implementation inside that one

package/docs/workflows.md

@@ -172,6 +172,21 @@ For app-first work, start with observe payloads such as `observe.procedures`,
 wrappers such as `admin.list_specs`, `admin.describe_role`, `admin.get_spec`,
 or `admin.list_events`; use observe list/detail procedures instead.
 
+Restricted references are one-record interaction contracts for read-only
+reference specs. When `observe.reference_context`, `observe.spec_config`, or
+`agent.describe_spec` shows `restricted_reference` or
+`reference_config.restricted_reference`, do not enumerate the protected
+reference, build a populated picker, or use broad `agent.select_reference_data`
+for that object path. Get the lookup value from the user's case/work context,
+then call `agent.get_reference_record` with the configured `object_key`, lookup
+value, purpose, and role lens. The procedure returns at most one `RECORD`,
+applies reference row filters, checks active `action_limit` Expectations before
+returning data, and records the safe `REFERENCE_READ` event used for usage
+budgeting. Use `observe.reference_context`, `observe.usage_limits`,
+`observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+for planning and audit without reading raw reference rows.
+
 The app should follow the loop:
 
 1. Observe/read governed records through approved Airlock or Snowflake surfaces.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reunionstudio/airlock-mcp",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Single-install MCP interface for Airlock agents.",
   "type": "module",
   "repository": {

package/patterns/starter-posts/sample.records.json

@@ -5,7 +5,7 @@
     {
       "post_id": "POST-001",
       "reply_to_post_id": "",
-      "submitted_by": "agent.deb",
+      "submitted_by": "agent.csmith",
       "posted_at": "2026-06-13 09:00:00",
       "body": "Please make reimbursements easier to prepare and submit.",
       "tags": "#request #finance #reimbursements",
@@ -19,7 +19,7 @@
           "desired_outcome": "An approved agent can prepare a draft reimbursement with receipt evidence."
         },
         "agent": {
-          "name": "Deb"
+          "name": "csmith"
         }
       }
     }

package/setup.py

@@ -27,7 +27,7 @@ def data_files():
 
 setup(
     name="airlock-mcp",
-    version="0.1.4",
+    version="0.1.5",
     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.4"
+__version__ = "0.1.5"

package/src/airlock_mcp/app_context.py

@@ -44,6 +44,16 @@ timeline. For `alter_spec` activity, use `CHANGED_SECTIONS` and
 Do not use retired admin read wrappers such as `admin.list_specs`,
 `admin.describe_role`, or `admin.list_events`; use the matching observe procedure.
 
+Restricted references are one-record interaction contracts. If a reference
+spec declares `restricted_reference` or `reference_config.restricted_reference`,
+do not enumerate values or use broad `agent.select_reference_data` for that
+object path. Get the lookup value from the user's case/work context and call
+`agent.get_reference_record` with the configured `object_key`, lookup value,
+purpose, and role lens. Use `observe.reference_context`,
+`observe.usage_limits`, `observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+for planning and audit without reading raw reference rows.
+
 Do not store credentials here. Do not write directly to Airlock-owned tables,
 stages, generated views, or generated tables. Use approved Airlock/Snowflake
 access paths and submit governed decisions or actions through spec contracts.
@@ -85,6 +95,13 @@ Installed Airlock procedure grammar:
 - `agent.*` is governed agent work in the actor's scope.
 - `admin.*` is administrative mutation. Do not use retired admin read wrappers;
   use observe list/detail procedures instead.
+
+For restricted reference specs, do not enumerate protected object paths or use
+broad `agent.select_reference_data`. Use `agent.get_reference_record` for a
+known lookup value and purpose, and use `observe.reference_context`,
+`observe.usage_limits`, `observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+for planning and audit.
 """
 
 
@@ -144,6 +161,7 @@ def _manifest(mode: str, entries: list[dict[str, Any]]) -> dict[str, Any]:
             "observe": "read-only governance observation, context, activity, health, billing events, and access explanation",
             "agent": "governed agent work in the actor scope",
             "admin": "administrative mutation and operational changes",
+            "restricted_reference": "one-record reference lookup through agent.get_reference_record; do not enumerate protected reference paths",
         },
         "specs": entries,
         "tracks": {

package/src/airlock_mcp/bootstrap.py

@@ -127,6 +127,18 @@ activity, use `CHANGED_SECTIONS` and `CHANGED_FIELDS` to triage what changed
 before fetching version snapshots. Do not call retired admin read wrappers such as `admin.list_specs`, `admin.describe_role`,
 or `admin.list_events`; use the matching observe list/detail procedure.
 
+Restricted references are one-record interaction contracts for read-only
+reference specs. If `agent.describe_spec`, `observe.spec_config`, or
+`observe.reference_context` shows `restricted_reference` or
+`reference_config.restricted_reference`, do not enumerate the protected
+reference, build a populated picker, or use broad `agent.select_reference_data`
+for that object path. Get the lookup value from the user's case/work context,
+then call `agent.get_reference_record` with the configured `object_key`, lookup
+value, purpose, and role lens. Use `observe.usage_limits`,
+`observe.usage_limit`, and
+`observe.explain_access(action => 'get_reference_record', object_key => ...)`
+for planning and audit without reading raw reference rows.
+
 The app may orient the user with summaries, comparisons, rankings, exception
 queues, proposals, or dashboards. It should submit governed choices back
 through an Airlock spec contract. Do not write directly to Airlock-owned tables,

package/src/mcp.mjs

@@ -44,7 +44,7 @@ export function handleMcpRequest(message) {
       },
       serverInfo: {
         name: "airlock",
-        version: "0.1.4",
+        version: "0.1.5",
       },
       instructions:
         "Airlock MCP helps agents improve processes with Airlock specs and build apps or workflows that use existing specs. Use airlock_start for orientation or the airlock_* tools to bootstrap, draft, check, summarize, export, and render specs.",

package/src/text.mjs

@@ -65,6 +65,21 @@ activity, use \`CHANGED_SECTIONS\` and \`CHANGED_FIELDS\` to triage what changed
 before fetching version snapshots. Offer to run \`airlock-mcp init-app-context\`
 in the app repo to seed \`airlock/specs.manifest.json\`, spec snapshots, sample records, and
 generated helper folders. Help code the app using approved Airlock/Snowflake access paths.
+When a reference spec declares \`restricted_reference\` or
+\`reference_config.restricted_reference\`, do not enumerate values, build a
+populated picker, or call broad \`agent.select_reference_data\`. Get the lookup
+value from the user's case/work context and call
+\`agent.get_reference_record\` for the configured \`object_key\`, purpose, and
+role lens. It returns at most one record, applies reference row filters, checks
+\`action_limit\` before returning data, and always records the safe
+\`REFERENCE_READ\` event used for budgeting. Branch on \`OK\`, \`NOT_FOUND\`,
+\`NON_UNIQUE_LOOKUP_KEY\`, \`PURPOSE_REQUIRED\`, \`USAGE_LIMIT_BLOCKED\`, and
+\`REFERENCE_READ_EVENT_FAILED\`; report \`USAGE_CONTEXT\` fields such as
+\`action_limit_used\` and \`action_time_period\`. Use
+\`observe.reference_context\`, \`observe.usage_limits\`, \`observe.usage_limit\`,
+and \`observe.explain_access(action => 'get_reference_record', object_key => ...)\`
+for read-only planning and audit.
+
 Do not use retired admin read wrappers such as
 \`admin.list_specs\`, \`admin.describe_role\`, or \`admin.list_events\`; use
 the matching observe procedure. Do not write directly to Airlock-owned tables
@@ -185,7 +200,10 @@ read-side discovery with observe payloads such as \`observe.procedures\`,
 for \`alter_spec\` activity, use \`CHANGED_SECTIONS\` and \`CHANGED_FIELDS\` to
 triage what changed before fetching version snapshots. Do not use retired admin
 read wrappers such as \`admin.list_specs\`, \`admin.describe_role\`, or
-\`admin.list_events\`. It can
+\`admin.list_events\`. If a reference spec declares \`restricted_reference\` or
+\`reference_config.restricted_reference\`, do not enumerate the protected
+reference; use \`agent.get_reference_record\` for a known lookup value and
+\`observe.usage_limits\` / \`observe.usage_limit\` for budget visibility. It can
 seed an app repo with \`airlock/specs.manifest.json\`, spec snapshots, sample
 records, and generated helper folders. The app should submit decisions,
 approvals, actions, comments, or follow-ups through Airlock spec contracts, not