@reunionstudio/airlock-mcp 0.1.6 → 0.1.8

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

@@ -194,6 +194,19 @@ Use three delivery modes:
 - Co-development: develop the app and specs together, keeping the contract and
   experience visible side by side.
 
+Treat Airlock's built-in Streamlit Native App as a generic operating and
+fallback surface. It is appropriate for administration, inspection, evidence,
+workflow, and occasional manual action. It is not intended to become the best
+domain application for every spec.
+
+Recommend a purpose-built app when repeated, high-value work such as
+reimbursement review, vendor onboarding, or employee-record changes benefits
+from specialized summaries, calculations, terminology, evidence layout, or
+controls. The app owns that experience while Airlock owns access, validation,
+expectations, evidence, workflow, activity, and observable governance. Keep UI
+layout and aggregation choices in app code unless they are genuinely governed
+business semantics shared across interfaces.
+
 Start by identifying:
 
 1. The app goal: what the user needs to orient around or decide.
@@ -216,6 +229,63 @@ Airlock:
 - `airlock.admin.*` performs administrative changes and operational mutations.
 - `airlock.agent.*` performs governed user or agent work in the actor's scope.
 
+Treat every mutating human or automated agent as an attributable Snowflake
+principal. Direct work uses that principal's Airlock assignments. Work for
+another principal requires explicit Airlock delegation and
+`on_behalf_of_user`; pass `delegation_id` only when Airlock reports more than
+one matching active grant. Snowflake user type and agent-session metadata are
+informational, not authority. Never map workspace roles, channel membership,
+reactions, or chat approval into Airlock permissions.
+A `DELEGATED_ACTION` event records the authorized attempt and actor/principal
+identity; the mutation result and normal file, attachment, or workflow events
+provide commitment evidence.
+
+Stored-procedure events may expose
+`EVENT_CONTEXT.snowflake_agent_active` as informational provenance. Never use
+that marker to grant access, infer delegation, classify billing, or replace the
+authenticated Snowflake principal.
+
+A read-only channel may use a dedicated observer principal with
+`app_observer`, a distinct Airlock role/assignment, and explicit per-spec
+`observer_access`. Do not reuse that observer principal for mutation, and do
+not share one mutating principal across human or automated actors.
+
+Use `agent.list_my_work` as the actor's single operational inbox for workflow,
+watcher, deadline, overdue, and exception work. Use `observe.work` for the
+read-only account-wide current-work projection and `observe.activity` for event
+history. Do not call the retired split work procedures.
+
+For efficient watcher loops, call `agent.spec_state` first and cache the
+role-scoped `STATE_TOKEN`. Retrieve `describe_spec`, file listings, or governed
+data only after it changes. Poll `agent.list_my_work` independently because
+deadlines and expectation windows can change without a spec mutation. For one selected logical file, compare
+`agent.file_state(...).FILE_STATE_ID`; it rotates for data replacement,
+workflow, attachment, and exact-reference changes. Use `observe.spec_state` and
+`observe.file_state` only with observer/admin authority for account-wide state.
+Do not substitute global observer tokens for an agent's scoped token.
+
+After every supported `agent.*` or intentional `admin.*` mutation, preserve a
+bounded `airlock.commitment-receipt/v1` in the external workspace history.
+Record the procedure and authenticated Snowflake principal; derive any
+represented principal and delegation id from the actual procedure arguments.
+Retain the target spec/path/filename, returned status/code/message and issues,
+and timestamp. After a successful direct file mutation, call `agent.file_state`
+with the returned target and retain its `UPLOAD_ID`, `FILE_STATE_ID`, workflow
+state, attachment count, and reference count. Do not make that direct actor
+state read after delegated work; leave `committed_state` null unless the actor
+performs a separate independently authorized observation. Keep a denied
+mutation as a receipt with no committed state. Never use a chat display name as
+the Snowflake actor or describe workspace approval as an Airlock commitment.
+
+Required source references are exact governed evidence, not filename fields.
+When an active downstream-to-source link has `min_count > 0`, load the
+downstream file into Draft, discover eligible sources with
+`agent.list_eligible_source_files`, pin exact manifest rows with
+`agent.add_file_reference`, and then call
+`agent.edit_file_workflow(action => 'advance')`. Branch on
+`SOURCE_REFERENCE_REQUIRED` and `SOURCE_REFERENCE_CHECK_FAILED`; do not bypass
+the gate by copying an identifier into submitted business data.
+
 For app-first work, prefer `observe.procedures`, `observe.specs`,
 `observe.spec`, `observe.governance_map`, `observe.explain_access`,
 `observe.health`, `observe.activity`, `observe.admin_activity`,
@@ -227,6 +297,36 @@ 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.
 
+For a structural spec change with active files, treat
+`SPEC_MIGRATION_REQUIRED` as a governed lifecycle, not an error to bypass. Use
+`admin.create_spec_revision`, `admin.create_spec_migration`,
+`admin.validate_spec_migration`, `admin.approve_spec_migration`,
+`admin.activate_spec_migration`, bounded `admin.run_spec_migration` calls,
+`observe.spec_migrations`, `observe.spec_migration`, and
+`admin.retire_spec_migration`. Before activation, an abandoned `draft`,
+`planned`, `validated`, or `approved` migration may be released with
+`admin.cancel_spec_migration`; never describe cancellation as rollback after
+activation. Preserve the full
+proposed config, use only the bounded declarative transform over immutable
+`column_id` values, and surface stable status, issue, progress, and lineage
+fields. Never invent direct SQL/Python migration escape hatches.
+
+If activation returns `SPEC_MIGRATION_ACTIVATED_WITH_REPAIR_REQUIRED`, the
+target is already active. Repair the reported target view or materialized
+table, call `admin.rebuild_access_index(TRUE)`, and re-read
+`observe.spec_migration`; do not retry activation. Airlock intentionally keeps
+stale surfaces unavailable and compiled agent access invalidated until repair.
+
+The migration runner claims bounded work before stage or manifest effects.
+Treat header renames as transformed successors, never zero-copy. For sequential
+migrations, effective source currency comes from append-only valid
+attestations. Re-attest an upgraded active file with unknown provenance by
+loading its existing staged path; Airlock validates its exact digest and updates
+the manifest in place. `source_preserved` keeps transformed source bytes out of
+ordinary retention purge. `SPEC_MIGRATION_ACTIVE` blocks a second data-contract
+revision until retirement but still permits metadata and governance repairs on
+the current data version.
+
 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
@@ -328,6 +428,8 @@ human decisions remain.
 
 - Local checks are not Airlock authority.
 - Installed Airlock procedures remain the execution contract.
+- Every mutating actor keeps an attributable Snowflake principal; shared
+  integration identities and workspace roles are not authorization shortcuts.
 - Do not write directly to Airlock-owned tables, stages, generated views, or
   generated tables.
 - Do not put Airlock workflow state, reviewer comments, approval status, or

package/.cortex-plugin/activation.md

@@ -0,0 +1,14 @@
+# Airlock MCP activation
+
+Use the bundled Airlock skill when a task concerns Airlock specs, governed
+Snowflake work, read-only governance observation, delegation, expectations,
+attachments, workflow, state polling, or commitment receipts.
+
+Before acting, preserve the authenticated Snowflake principal. Workspace roles
+and chat identity are not Airlock authority. Use `airlock.agent.*` for governed
+work, `airlock.observe.*` for read-only observation, and `airlock.admin.*` only
+for intentional administration. Use explicit Airlock delegation when the
+connected principal acts for another principal.
+
+Never store credentials in this plugin or its workspace files. Configure the
+Airlock MCP connection through the supported environment or connection setup.

package/.cortex-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "airlock-mcp",
+  "description": "Governed Airlock spec, observation, and commitment guidance for Snowflake principals.",
+  "version": "0.1.8",
+  "author": {
+    "name": "Reunion Studio",
+    "url": "https://github.com/reunionstudio/airlock-mcp"
+  },
+  "skills": [
+    "./.agents/skills"
+  ],
+  "mcpServers": {
+    "airlock": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@reunionstudio/airlock-mcp@0.1.8",
+        "server"
+      ]
+    }
+  }
+}

package/README.md

@@ -28,15 +28,25 @@ Airlock MCP gives agents four kinds of Airlock help:
    procedures to inspect setup, access, activity, billing events, health,
    context packets, and governance maps before deciding what an app or agent
    should do.
+5. Workspace interoperability: preserve principal identity, poll scoped state,
+   commit only through installed procedures, and retain portable Airlock
+   receipts in external workspace history.
 
 ## Installed Airlock Contract
 
 Current Airlock separates procedure intent:
 
 - `airlock.observe.*` is the read-only governance observation surface. It is
-  available to `app_admin` and `app_observer` and is the preferred path for
-  discovery, health checks, access explanation, governance maps, activity,
-  billing event context, and list/detail context packets.
+  available at the Snowflake object layer to `app_admin` and `app_observer`.
+  Airlock assignments and per-spec `observer_access` rules scope ordinary
+  observers; account-wide surfaces require `app_admin` or the locked Airlock
+  role `global_observer`. That reserved role is observation-only: it cannot own
+  specs, receive guest/reviewer grants, or manage child roles.
+  Account-wide auditors should use `airlock.observe.observers(...)` for a flat
+  user, assignment, observer-role, spec/path/workflow, and license inventory.
+  `active_seat_observer_only` means the identity is observer-only now but still
+  has a billable seat that must be explicitly unassigned; role changes never
+  silently rewrite billing history.
 - `airlock.admin.*` is for admin changes and operational actions such as
   creating specs, changing roles, loading OKF bundles, rerunning setup, or
   deleting purge candidates.
@@ -44,12 +54,124 @@ Current Airlock separates procedure intent:
   specs, validating/loading data, workflow actions, attachments, delegations,
   and references.
 
+Every mutating human or automated agent should connect as its own attributable
+Snowflake principal. When it acts for another principal, use explicit Airlock
+delegation. Snowflake user type, chat identity, channel membership, workspace
+roles, and reactions do not create Airlock authority. A read-only channel may
+use a distinct scoped observer principal, but that principal must not be reused
+for mutation.
+
+Stored-procedure activity includes the informational
+`EVENT_CONTEXT.snowflake_agent_active` marker when Snowflake exposes it. The
+marker identifies execution context for observation; it never changes Airlock
+access, workflow, expectations, billing, or receipt identity.
+A `DELEGATED_ACTION` event records an authorized attempt, not proof that its
+mutation committed. Commitment receipts derive delegation identity from the
+actual call arguments, and only successful direct file mutations are hydrated
+through `agent.file_state`; delegated work leaves `committed_state` null unless
+the actor performs a separate independently authorized observation.
+
+Use `airlock.agent.list_my_work(...)` for the current actor's unified workflow,
+read-only observation, deadline, overdue, and exception inbox. Use
+`airlock.observe.work(...)` for the read-only assignment-scoped projection of
+current work, and
+`airlock.observe.activity(...)` for historical events. The older split work
+procedures are retired.
+
+Polling agents should call `airlock.agent.spec_state(...)` before retrieving a
+complete descriptor, file list, or governed dataset. Cache the
+authorization-scoped `STATE_TOKEN` and perform the heavier read only when it
+changes. Poll `airlock.agent.list_my_work(...)` independently because deadlines
+and expectation windows can change with time without rotating a spec token.
+After selecting a logical file, compare
+`airlock.agent.file_state(...).FILE_STATE_ID`; that UUID rotates when its data,
+workflow, attachments, exact source references, or retained version history
+change. Observer clients use
+the authorization-scoped, read-only `observe.spec_state(...)` and
+`observe.file_state(...)` equivalents. A missing object or revoked observer
+grant returns no row, which is the terminal polling signal; authorized query
+failures remain procedure errors.
+
+### Observer Access And Seats
+
+An observe-only integration does not claim or consume a named Airlock seat.
+`airlock.agent.*` and the built-in Streamlit app remain seat-gated. Moving an
+existing identity to observe-only does not silently remove a seat that was
+previously assigned or claimed; an administrator should explicitly call
+`airlock.admin.unassign_license(...)` after confirming the identity no longer
+uses those surfaces.
+
+Specs grant read-only visibility with canonical `observer_access` config:
+
+```json
+{
+  "observer_access": {
+    "enabled": true,
+    "observer_roles": [
+      {
+        "role_name": "finance_observer",
+        "path_filter": "finance",
+        "workflow_states": ["Approved"]
+      }
+    ]
+  }
+}
+```
+
+Grant the integration Snowflake application role `app_observer`, create or
+reuse the Airlock observer role, and assign the integration's Snowflake
+username to it. Use a distinct observer principal per channel so attribution,
+scope, and revocation remain independent. Observe procedures return governance
+metadata only, never governed payload rows or attachment bytes.
+
+Set up an observer in four explicit steps: grant the observer principal's Snowflake role
+`<APP_NAME>.app_observer`, create and assign a distinct Airlock role, publish
+that role in each intended spec's `observer_access`, then verify the result with
+`observe.observers(...)`. Audit assignment creation, changes, and removal with
+`observe.admin_activity(..., action_family => 'assignments')`; its structured
+event context includes before/after state. See [docs/workflows.md](docs/workflows.md)
+for the operating checklist and billing cleanup boundary.
+
 When building an app or workflow, prefer `observe.*` for read-only setup and
 monitoring questions, `agent.*` for governed submissions in the actor's scope,
 and `admin.*` only for intentional administrative mutation. Do not use retired
 admin read wrappers such as `admin.list_specs`, `admin.describe_role`, or
 `admin.list_events`; use the matching observe procedures instead.
 
+Structural spec changes with active data use Airlock's governed migration
+lifecycle. Agents should preserve the proposed config and guide an
+administrator through immutable revision, declarative migration planning,
+all-row proof, approval, activation, bounded execution, observable lineage, and
+source retirement. `SPEC_MIGRATION_REQUIRED` is a safety boundary; it is not a
+reason to mutate Airlock-owned storage directly.
+
+Migration execution claims bounded work before storage effects. Renamed headers
+produce transformed successors, sequential migrations rely on append-only
+validation attestations, and upgraded files with unknown provenance are
+re-attested in place through normal `load_data`. `source_preserved` protects
+transformed source bytes from ordinary retention purge, while
+`SPEC_MIGRATION_ACTIVE` prevents another data-contract revision until the
+current migration retires.
+
+## Built-In UI And Purpose-Built Apps
+
+Airlock's Streamlit Native App is deliberately a generic operating and fallback
+surface. It supports administration, inspection, governed data and attachment
+review, workflow visibility, and safe manual action. It should not be treated as
+a universal domain application builder.
+
+Repeated, high-value decisions such as reimbursements, vendor onboarding, or
+employee-record changes may deserve purpose-built interfaces. Airlock MCP should
+recommend app-first or co-development for those cases and help build the custom
+surface against Airlock contracts. The app owns domain summaries,
+calculations, terminology, and interaction design; Airlock continues to own
+access, validation, expectations, evidence, workflow, activity, and observable
+governance.
+
+Do not add UI layout or aggregation fields to a spec merely to make the generic
+Native App imitate custom software. Presentation belongs in app code unless it
+is genuinely governed business semantics shared across interfaces.
+
 ## Install
 
 Dogfood directly from GitHub:
@@ -64,6 +186,19 @@ Install from npm:
 npx @reunionstudio/airlock-mcp install
 ```
 
+Install the bundled Cortex Code plugin from GitHub:
+
+```bash
+cortex plugin install reunionstudio/airlock-mcp
+```
+
+The `.cortex-plugin/plugin.json` manifest loads the same Airlock skill and pins
+the stdio MCP server to this package version. Keep Snowflake and MCP credentials
+outside the manifest. When the Cortex Code CLI is available locally, validate a
+checkout with `cortex plugin validate` before distributing it. Account-local
+Cortex Extension sharing remains subject to Snowflake's current preview and
+RBAC requirements.
+
 Today this package is a small installer and MCP launcher. For Codex, install
 registers a local stdio server with:
 
@@ -82,6 +217,10 @@ person through process discovery, and entering the bundled spec-building
 workbench when a first spec is ready to draft. It also guides agents building
 apps or workflows that use specs the user already has access to.
 
+See [principal and workspace interoperability](docs/principal-workspace-interoperability.md)
+for the identity matrix, state-polling contract, and portable commitment
+receipt.
+
 Workspace summaries are structured spec cards. They present the current spec
 core, file rules, attachment policy, guest access, column rules, sample record
 shape, note-file status, and local check status so Codex can reflect the draft
@@ -221,6 +360,31 @@ 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.
 
+For operational queues, call `agent.list_my_work` in the actor's scope. An
+observer may call `observe.work` for current work in its assigned scope;
+historical questions belong to `observe.activity`.
+
+Required source references are a governed submission contract. When a
+downstream spec has an active source link with `min_count > 0`, load the file
+into Draft, discover eligible evidence with `agent.list_eligible_source_files`,
+pin exact manifest rows with `agent.add_file_reference`, and only then call
+`agent.edit_file_workflow(action => 'advance')`. Missing, removed, or
+wrong-workflow-state evidence returns `SOURCE_REFERENCE_REQUIRED` without
+moving the file. Do not replace the exact Airlock reference with a filename or
+identifier copied into business data.
+
+Structural spec changes with active files use Airlock's governed two-version
+migration lifecycle. Treat `SPEC_MIGRATION_REQUIRED` as a request to create an
+immutable revision and migration, validate and approve it, activate the target,
+drain bounded batches with `admin.run_spec_migration`, inspect progress and
+lineage through `observe.spec_migration`, and retire the source only after the
+evidence gate passes. Use `observe.spec_migrations` to discover and filter
+migrations. Before activation, an abandoned `draft`, `planned`, `validated`, or
+`approved` migration may be released with `admin.cancel_spec_migration`;
+cancellation is not rollback after activation. The transform language is intentionally limited to
+mechanical mappings, defaults, and safe casts; semantic transforms belong in a
+purpose-built process that reloads through normal Airlock validation.
+
 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

package/docs/install-surface.md

@@ -46,6 +46,15 @@ access uses Snowflake download links when available. Successful PDF page
 previews emit metadata-only `ATTACHMENT_PREVIEW` activity. This UI capability
 does not grant MCP clients direct stage access.
 
+The Native App is deliberately a generic operating and fallback surface. It
+should support administration, inspection, evidence, workflow, and safe manual
+action without accumulating every domain's presentation rules. Airlock MCP
+should recommend app-first or co-development when repeated, high-value work
+deserves a purpose-built interface. The custom app owns domain summaries,
+calculations, terminology, and controls while Airlock remains the governed
+backend. UI layout and aggregation hints should not be added to specs merely to
+polish the generic app.
+
 The connector package and MCP server live in `reunionstudio/airlock-mcp`.
 This workbench provides the spec-building implementation inside that one
 installed Airlock MCP experience.

package/docs/principal-workspace-interoperability.md

@@ -0,0 +1,101 @@
+# Principal and workspace interoperability
+
+Airlock treats a workspace as a place for discussion, drafts, monitoring, and
+automation. It does not treat workspace roles, channel membership, reactions,
+or chat approvals as Snowflake authority.
+
+## Required identity model
+
+- Every mutating human or automated agent connects as its own attributable
+  Snowflake principal.
+- Direct work uses that principal's Airlock assignments.
+- Work for another principal uses an explicit Airlock delegation and
+  `on_behalf_of_user`; pass `delegation_id` only when Airlock reports multiple
+  matching active grants.
+- Snowflake user type and agent-session metadata are informational. They do not
+  create Airlock authority or change policy, workflow, expectations, or
+  billing.
+- Stored-procedure activity exposes `event_context.snowflake_agent_active` when
+  Snowflake supplies the execution-context marker. Use it for observation only;
+  the authenticated principal remains the authoritative actor.
+- A read-only channel may use a dedicated observer principal with
+  `<APP_NAME>.app_observer` and explicit per-spec `observer_access`. Never reuse
+  that principal for mutation.
+
+## Polling
+
+Use state tokens before larger reads:
+
+- `agent.spec_state(...).STATE_TOKEN` for the actor's visible contract, data,
+  and access state;
+- `agent.file_state(...).FILE_STATE_ID` for one visible file's data, workflow,
+  attachment, reference, and retained-version state;
+- `observe.spec_state` and `observe.file_state` for a scoped observer principal;
+  and
+- `agent.list_my_work` or `observe.work` on a separate cadence for deadlines
+  and current work.
+
+A missing state row is the terminal result for that cursor. Return to discovery
+instead of inferring whether the object was deleted, retired, or became
+inaccessible.
+
+## Commitment receipts
+
+After every supported `agent.*` or intentional `admin.*` mutation, store a
+bounded receipt in the workspace event history:
+
+```json
+{
+  "schema": "airlock.commitment-receipt/v1",
+  "procedure": "airlock.agent.load_data",
+  "actor": {
+    "snowflake_principal": "CSMITH",
+    "on_behalf_of": "ASMITH",
+    "delegation_id": null
+  },
+  "target": {
+    "spec_name": "reimbursements",
+    "path": "asmith",
+    "filename": "expense_2026_08_08"
+  },
+  "outcome": {
+    "status": "ok",
+    "code": "LOADED",
+    "message": null,
+    "issues": []
+  },
+  "committed_state": null,
+  "operation_identity": {},
+  "recorded_at": "2026-08-08T12:00:00Z"
+}
+```
+
+Bind `actor.snowflake_principal` to the authenticated connection identity, not
+a chat display name. Preserve the procedure's stable status, code, message,
+and issues. Derive `on_behalf_of` and `delegation_id` from the actual procedure
+arguments and reject conflicting receipt metadata.
+
+After a successful direct file mutation, call `agent.file_state` with the
+returned spec, path, and filename to populate `committed_state`. Do not make
+that direct actor state read after delegated work because `agent.file_state`
+has no delegated call shape. Leave `committed_state` null unless the actor
+performs a separate independently authorized observation. For attachment
+mutations, retain the returned `ATTACHMENT_ID` in `operation_identity`.
+
+A `DELEGATED_ACTION` event records the authorized delegated attempt and its
+actor/principal identity. It does not by itself prove that the requested
+mutation committed; use the procedure outcome and normal mutation events as
+commitment evidence.
+
+Denied mutations are receipts too. Preserve the denial code and issues, omit
+committed state, and never describe workspace approval as an Airlock
+commitment.
+
+## Cortex Code plugin
+
+This repository includes `.cortex-plugin/plugin.json`, which loads the bundled
+Airlock skill and starts the pinned Airlock MCP package over stdio. Install from
+the Git repository with Cortex Code's plugin command, inspect the version, and
+keep credentials outside the plugin manifest. Account-local Cortex Extension
+sharing may be used where enabled; follow Snowflake's current preview and RBAC
+requirements.

package/docs/workflows.md

@@ -154,6 +154,17 @@ unless the user asks to change specs. Start by asking for:
 - the available Airlock/Snowflake access path
 - identity, evidence, timestamp, approval, and separation-of-duties needs
 
+Airlock's built-in Streamlit Native App is a generic operating and fallback
+surface, not a universal domain application builder. Use it for administration,
+inspection, governed evidence, workflow, and occasional manual action. For
+repeated high-value decisions, prefer a purpose-built app when domain-specific
+summaries, calculations, evidence layout, terminology, or controls materially
+improve the work.
+
+Keep those presentation choices in app code. Do not add layout or aggregation
+fields to an Airlock spec merely to make the generic UI imitate custom
+software. Airlock remains the governed backend for either surface.
+
 Use the installed Airlock procedure grammar:
 
 - `airlock.observe.*` is read-only and should answer discovery, governance,
@@ -163,6 +174,125 @@ Use the installed Airlock procedure grammar:
   delegations.
 - `airlock.admin.*` is for administrative mutation and operational changes.
 
+For work discovery, use `agent.list_my_work` as the current actor's unified
+inbox. Observers use `observe.work` for current work within their assignment and
+spec scope, and `observe.activity` for scoped historical events. `app_admin`
+and the locked Airlock role `global_observer` receive the account-wide forms.
+Do not recreate separate workflow and expectation inbox calls in app code.
+
+For an account-wide observer audit, call `observe.observers(...)`. It flattens
+the current user assignment, effective observer role, spec/path/workflow scope,
+and named-license posture. Treat `active_seat_observer_only` as an explicit
+administrative cleanup state: observer calls are free, but a previously claimed
+seat remains billable until `admin.unassign_license(...)` is called.
+
+When asked to set up an observer principal for a channel, keep these controls
+separate and apply them in order:
+
+1. Grant a dedicated Snowflake account role the installed app's
+   `<APP_NAME>.app_observer` application role.
+2. Create a distinct Airlock role with `admin.create_roles(...)`, then assign
+   the observer principal's Snowflake username with
+   `admin.create_assignments(...)`.
+3. Add that role to each intended spec's `observer_access.observer_roles`, using
+   `path_filter` and `workflow_states` when narrower visibility is required.
+4. As `app_admin` or `global_observer`, verify the result with
+   `observe.observers(...)` and audit the setup through
+   `observe.admin_activity(procedure_name => 'create_assignments', action_family
+   => 'assignments', ...)`.
+
+Assignment create, alter, and drop activity includes structured
+`EVENT_CONTEXT.before`, `EVENT_CONTEXT.after`, and
+`EVENT_CONTEXT.changed_fields`. Expect `free_observer_only` when the principal
+has no agent access or active seat. If it reports `active_seat_observer_only`,
+confirm the principal no longer needs `agent.*` or Streamlit before calling
+`admin.unassign_license(...)`. Never share one Snowflake username across
+channels merely to simplify setup; that collapses attribution and revocation.
+
+Watcher loops should call `agent.spec_state` before larger reads. Cache its
+authorization-scoped `STATE_TOKEN` and retrieve descriptors, file lists, or
+governed data only when it changes. Poll `agent.list_my_work` independently
+because deadlines and expectation windows can change without rotating the spec
+token. Once the app tracks one logical file,
+compare `agent.file_state(...).FILE_STATE_ID` to detect data replacement,
+workflow movement, attachment changes, exact-reference changes, or retained
+version-history changes. Observer principals use the authorization-scoped,
+read-only `observe.spec_state` and `observe.file_state` equivalents. A missing
+object or revoked grant returns no row as the terminal polling signal;
+authorized query failures remain procedure errors.
+
+Every mutating human or automated agent should connect as an attributable
+Snowflake principal. When it acts for another principal, use explicit Airlock
+delegation and `on_behalf_of_user`; pass `delegation_id` only when multiple
+active grants match. Workspace roles, channel membership, reactions, and chat
+approvals remain collaboration context, not Airlock authority.
+A `DELEGATED_ACTION` event records the authorized attempt and actor/principal
+identity; it does not by itself prove that the requested mutation committed.
+
+When activity includes `EVENT_CONTEXT.snowflake_agent_active`, treat it as
+informational execution provenance. It does not grant authority, prove
+delegation, or change policy and billing.
+
+After each supported `agent.*` or intentional `admin.*` mutation, store an
+`airlock.commitment-receipt/v1` in workspace history. Preserve the authenticated
+Snowflake actor and derive any represented principal and delegation id from the
+actual call arguments. Retain the target, stable status/code/message/issues,
+and timestamp. For a successful direct file mutation, follow with
+`agent.file_state` and retain `UPLOAD_ID`, `FILE_STATE_ID`, workflow state,
+attachment count, and reference count. Do not make that direct actor state read
+after delegated work; leave `committed_state` null unless the actor performs a
+separate independently authorized observation. A denied call is still a
+receipt, but it has no committed state. See
+`docs/principal-workspace-interoperability.md` for the complete shape.
+
+For downstream work that requires governed source evidence, use the installed
+source-reference sequence: load the downstream Draft, call
+`agent.list_eligible_source_files`, pin exact source manifest rows with
+`agent.add_file_reference`, then advance workflow. Active source links with
+`min_count > 0` are enforced by `agent.edit_file_workflow`; required sources
+must still exist, remain unremoved, and match any configured
+`required_workflow_status`. Branch on `SOURCE_REFERENCE_REQUIRED` or
+`SOURCE_REFERENCE_CHECK_FAILED` and show the returned `ISSUES` instead of
+guessing at alternate source identifiers.
+
+When an app or administrator changes a spec's data contract, do not work around
+`SPEC_MIGRATION_REQUIRED` with direct table, stage, or view changes. Use the
+installed governed lifecycle: `admin.create_spec_revision`,
+`admin.create_spec_migration`, `admin.validate_spec_migration`,
+`admin.approve_spec_migration`, `admin.activate_spec_migration`, bounded calls
+to `admin.run_spec_migration`, inspection through
+`observe.spec_migrations` and `observe.spec_migration`, and finally
+`admin.retire_spec_migration`. Before activation, use
+`admin.cancel_spec_migration` to release an abandoned `draft`, `planned`,
+`validated`, or `approved` migration. Cancellation is not rollback after
+activation. The
+transform is declarative and keyed by immutable `column_id` values; arbitrary
+SQL or Python is not part of the contract. Approval is intent, activation is
+the write-version switch, and retirement is a separate guarded action.
+
+Treat `SPEC_MIGRATION_ACTIVATED_WITH_REPAIR_REQUIRED` as a committed activation,
+not a retryable pre-activation failure. Follow the returned issues to rebuild
+the target view or materialized table, then call
+`admin.rebuild_access_index(TRUE)` and re-read `observe.spec_migration`. Airlock
+keeps stale read surfaces unavailable and compiled agent access invalidated
+until repair succeeds.
+
+`admin.run_spec_migration` claims each bounded item batch before stage or
+manifest side effects. A header rename always creates a transformed successor;
+zero-copy is reserved for stored headers and values that already satisfy the
+target contract. Use append-only valid attestations, not only the manifest's
+original version pointer, when a file moves through sequential migrations.
+
+An upgraded active file may have `validation_provenance_status = 'unknown'`.
+Re-load its existing staged path through `load_data`: after validation and an
+exact digest recheck, Airlock re-attests the existing manifest in place instead
+of creating a duplicate stage-path owner. A `source_preserved` migration keeps
+transformed source bytes outside ordinary retention purge; `forward_only`
+allows normal retention. While a migration is active,
+`SPEC_MIGRATION_ACTIVE` blocks another data-contract revision until retirement,
+although metadata, access, policy, expectation, and workflow repairs remain
+allowed on the current data version.
+
 For app-first work, start with observe payloads such as `observe.procedures`,
 `observe.specs`, `observe.spec`, `observe.governance_map`,
 `observe.explain_access`, `observe.health`, `observe.activity`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reunionstudio/airlock-mcp",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Single-install MCP interface for Airlock agents.",
   "type": "module",
   "repository": {
@@ -27,8 +27,10 @@
   "files": [
     "bin",
     "docs",
-    "src",
+    "src/*.mjs",
+    "src/airlock_mcp/*.py",
     ".agents",
+    ".cortex-plugin",
     "patterns",
     "schemas",
     "workspaces",

package/setup.py

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

package/src/airlock_mcp/app_context.py

@@ -20,6 +20,12 @@ 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.
 
+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
+features materially improve repeated, high-value work. Keep presentation in
+app code rather than adding UI layout or aggregation hints to Airlock specs.
+
 Use:
 
 - `specs.manifest.json` to track which specs the app reads from or writes to.
@@ -36,6 +42,28 @@ Installed Airlock separates procedure intent:
 - `agent.*`: governed agent work in the actor's scope.
 - `admin.*`: administrative mutation and operational changes.
 
+Use `agent.list_my_work` for the actor's unified current-work inbox,
+`observe.work` for account-wide current work, and `observe.activity` for
+historical events. The older split workflow/expectation work calls are retired.
+
+Required source references are exact governed evidence. For an active source
+link with `min_count > 0`, load the downstream Draft, discover eligible files
+with `agent.list_eligible_source_files`, pin exact manifest rows with
+`agent.add_file_reference`, and then advance workflow. Missing or invalid
+evidence returns `SOURCE_REFERENCE_REQUIRED` without moving the file.
+
+Structural spec changes with active files use a governed two-version migration
+lifecycle. Treat `SPEC_MIGRATION_REQUIRED` as a request to create an immutable
+revision and migration, validate and approve it, activate the target, run
+bounded migration batches, list work with `observe.spec_migrations`, inspect
+evidence with `observe.spec_migration`, and retire the source only after Airlock
+reports that it is drained. Before activation, an abandoned `draft`, `planned`,
+`validated`, or `approved` migration may be cancelled with
+`admin.cancel_spec_migration`; cancellation is not rollback. Use only the
+declarative mechanical transform keyed by immutable `column_id`; semantic
+transforms belong in a purpose-built process that reloads through normal
+Airlock validation.
+
 Prefer `observe.*` for app read-side setup and monitoring questions. Use
 `observe.admin_activity` for broad admin mutation and maintenance audit
 questions, and `observe.spec_admin_activity` for one spec's definition-change
@@ -72,6 +100,13 @@ APP_AGENTS = """# Airlock App Guidance
 
 This repo may contain application code that uses Airlock specs.
 
+Treat the built-in Streamlit Native App as a generic operating and fallback
+surface. Build a purpose-built interface when domain-specific presentation
+materially improves repeated, high-value work. The custom app owns the
+experience; Airlock remains the governed backend for access, validation,
+expectations, evidence, workflow, activity, and observability. Do not add UI
+layout or aggregation fields to specs solely for the built-in app.
+
 ## Modes
 
 - Spec-first: design governed specs before building the app surface.
@@ -104,6 +139,18 @@ Installed Airlock procedure grammar:
 - `admin.*` is administrative mutation. Do not use retired admin read wrappers;
   use observe list/detail procedures instead.
 
+Use `agent.list_my_work` for the current actor's unified work inbox. Use
+`observe.work` for account-wide current work and `observe.activity` for event
+history.
+
+For structural spec changes with active files, treat
+`SPEC_MIGRATION_REQUIRED` as the start of Airlock's governed two-version
+lifecycle. Use immutable revisions, bounded `admin.run_spec_migration` calls,
+`observe.spec_migrations` discovery, `observe.spec_migration` evidence, and
+guarded source retirement. Before activation, `admin.cancel_spec_migration` may
+release an abandoned migration; it is not a post-activation rollback. Do not bypass
+the lifecycle with direct stage, table, or view changes.
+
 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`,
@@ -173,9 +220,13 @@ def _manifest(mode: str, entries: list[dict[str, Any]]) -> dict[str, Any]:
         "installed_airlock_contract": {
             "observe": "read-only governance observation, context, activity, health, billing events, and access explanation",
             "agent": "governed agent work in the actor scope",
+            "work": "agent.list_my_work is the actor inbox; observe.work is account-wide current work; observe.activity is history",
+            "required_source_references": "load Draft, list eligible sources, pin exact manifest rows, then advance; SOURCE_REFERENCE_REQUIRED blocks missing evidence",
+            "spec_migration": "immutable two-version lifecycle; list with observe.spec_migrations, run bounded admin migration batches, inspect observe.spec_migration evidence, cancel only before activation, and retire only after the source is drained",
             "admin": "administrative mutation and operational changes",
             "restricted_reference": "one-record reference lookup through agent.get_reference_record; do not enumerate protected reference paths",
             "attachment_preview": "governed Streamlit preview emits metadata-only ATTACHMENT_PREVIEW; MCP clients do not get direct stage access",
+            "application_surface": "built-in Streamlit is a generic operating/fallback surface; purpose-built apps own domain UI and use Airlock as the governed backend",
         },
         "specs": entries,
         "tracks": {

package/src/airlock_mcp/bootstrap.py

@@ -99,6 +99,14 @@ Airlock context. It creates `airlock/specs.manifest.json`,
 folders. These files are app-local references, not canonical specs. Canonical
 specs live in the specs repo or installed Airlock.
 
+Treat Airlock's built-in Streamlit Native App as a generic operating and
+fallback surface. It supports administration, inspection, evidence, workflow,
+and safe manual action; it is not a universal domain application builder.
+Recommend a purpose-built app when repeated, high-value work benefits from
+domain-specific summaries, calculations, evidence layout, terminology, or
+controls. Keep those presentation choices in app code. Do not add UI layout or
+aggregation fields to a spec merely to improve the generic app.
+
 Identify:
 
 - the app goal and decision the app should support
@@ -118,6 +126,28 @@ Installed Airlock separates procedure intent:
 - `agent.*`: governed agent work in the actor's scope.
 - `admin.*`: administrative mutation and operational changes.
 
+Use `agent.list_my_work` for the actor's unified current-work inbox,
+`observe.work` for account-wide current work, and `observe.activity` for
+historical events. The older split workflow/expectation work calls are retired.
+
+For active source links with `min_count > 0`, load the downstream file into
+Draft, discover eligible evidence with `agent.list_eligible_source_files`, pin
+exact manifest rows with `agent.add_file_reference`, and then advance workflow.
+Missing, removed, or wrong-state evidence returns `SOURCE_REFERENCE_REQUIRED`
+without moving the file.
+
+For a structural spec change with active files, treat
+`SPEC_MIGRATION_REQUIRED` as a governed two-version lifecycle. Create the
+immutable revision and migration, validate and approve it, activate the target,
+run bounded `admin.run_spec_migration` batches, inspect progress and lineage
+with `observe.spec_migration`, and retire the source only after it is drained.
+Use `observe.spec_migrations` to discover lifecycle work. Before activation,
+`admin.cancel_spec_migration` may release an abandoned `draft`, `planned`,
+`validated`, or `approved` migration; it is not rollback after activation. Use
+the bounded declarative transform for mechanical changes; semantic
+transforms belong in a purpose-built process that reloads through normal
+Airlock validation.
+
 For app-first work, use observe payloads such as `observe.procedures`,
 `observe.specs`, `observe.spec`, `observe.governance_map`,
 `observe.explain_access`, `observe.health`, `observe.activity`,

package/src/mcp.mjs

@@ -44,7 +44,7 @@ export function handleMcpRequest(message) {
       },
       serverInfo: {
         name: "airlock",
-        version: "0.1.6",
+        version: "0.1.8",
       },
       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

@@ -62,9 +62,62 @@ administrative mutation. Prefer observe payloads such as
 \`observe.activity\`, \`observe.admin_activity\`, \`observe.spec_admin_activity\`,
 and \`observe.billing_events\` before inventing custom read paths. For \`alter_spec\`
 activity, use \`CHANGED_SECTIONS\` and \`CHANGED_FIELDS\` to triage what changed
-before fetching version snapshots. Offer to run \`airlock-mcp init-app-context\`
+before fetching version snapshots. For polling loops, cache the role-scoped
+\`agent.spec_state(...).STATE_TOKEN\` and do larger reads only when it changes.
+After selecting one logical file, compare
+\`agent.file_state(...).FILE_STATE_ID\` to detect data, workflow, attachment,
+exact-reference, or retained version-history changes. Observer principals may use
+the authorization-scoped \`observe.spec_state\` and \`observe.file_state\`
+equivalents. A missing object or revoked observer grant returns no row as the
+terminal polling signal; authorized query failures remain errors. Holding
+\`app_observer\` opens only the read-only procedure family; Airlock
+assignments plus \`observer_access.observer_roles\` determine spec visibility,
+and account-wide observation requires \`app_admin\` or the locked Airlock role
+\`global_observer\`. That reserved role cannot own specs, receive guest/reviewer
+grants, or manage child roles. Observe-only calls do not consume a named seat, while
+\`agent.*\` and Streamlit remain seat-gated. Use a distinct Snowflake username
+per observer channel principal. For account-wide audits, call
+\`observe.observers(...)\` to join observer assignment/scope with agent-access
+and license posture. \`active_seat_observer_only\` means the identity remains
+billable until an administrator explicitly calls \`admin.unassign_license\`;
+never infer billing from role names alone. When asked to configure an observer
+principal, apply four explicit controls: grant its dedicated Snowflake role
+\`<APP_NAME>.app_observer\`, create and assign a distinct Airlock role, publish
+that role through each spec's \`observer_access\`, then verify scope and billing
+with \`observe.observers(...)\`. Audit assignment create, alter, and drop
+through \`observe.admin_activity(..., action_family => 'assignments')\`; use
+the structured \`EVENT_CONTEXT.before\`, \`after\`, and \`changed_fields\`
+instead of parsing descriptions. 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.
+Treat every mutating human or automated agent as an attributable Snowflake
+principal. Direct work uses that principal's assignments; work for another
+principal uses explicit Airlock delegation and \`on_behalf_of_user\`. Workspace
+roles, channel membership, reactions, and chat identity do not create Airlock
+authority. Treat \`EVENT_CONTEXT.snowflake_agent_active\` as informational
+provenance only. A \`DELEGATED_ACTION\` event records an authorized attempt, not
+proof that its mutation committed. After each supported mutation, retain an
+\`airlock.commitment-receipt/v1\` with the authenticated actor, delegation
+identity derived from the actual call arguments, target, stable result, and
+timestamp. Hydrate successful direct file mutations with \`agent.file_state\` so
+the receipt includes \`UPLOAD_ID\`, \`FILE_STATE_ID\`, and current workflow state.
+Leave delegated \`committed_state\` null unless the actor performs a separate
+independently authorized observation.
+Treat Airlock's built-in Streamlit app as a generic operating and fallback
+surface, not a universal domain app. When a repeated, high-value decision needs
+domain-specific summaries, calculations, evidence layout, terminology, or
+controls, recommend a purpose-built app and use Airlock as its governed backend.
+Keep those presentation choices in app code; do not add layout or aggregation
+fields to a spec merely to improve the generic UI.
+When a structural spec change with active files returns
+\`SPEC_MIGRATION_REQUIRED\`, use Airlock's governed two-version lifecycle:
+create the immutable revision and migration, validate and approve it, activate
+the target, drain bounded \`admin.run_spec_migration\` batches, inspect
+\`observe.spec_migrations\` and \`observe.spec_migration\`, and retire the source
+only after it is drained. Before activation, an abandoned migration may use
+\`admin.cancel_spec_migration\`; cancellation is not post-activation rollback.
+Use the declarative mechanical transform; semantic transforms belong in a
+purpose-built process that reloads through normal Airlock validation.
 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
@@ -111,6 +164,7 @@ Airlock MCP will offer:
   - spec design with the bundled workbench
   - Airlock operating patterns for OODA loops and separation of duties
   - read-only observe procedures for governance maps, health, access explanation, activity, billing events, and context packets
+  - scoped spec and file state tokens for efficient polling
   - app context seeding with spec snapshots and manifests
   - app and workflow coding against existing Airlock specs
   - observe specs for controlled interface ingestion
@@ -204,7 +258,38 @@ read-side discovery with observe payloads such as \`observe.procedures\`,
 \`observe.explain_access\`, \`observe.health\`, \`observe.activity\`,
 \`observe.admin_activity\`, \`observe.spec_admin_activity\`, and \`observe.billing_events\`;
 for \`alter_spec\` activity, use \`CHANGED_SECTIONS\` and \`CHANGED_FIELDS\` to
-triage what changed before fetching version snapshots. Do not use retired admin
+triage what changed before fetching version snapshots. For polling loops, poll
+\`agent.spec_state\` and compare its scoped \`STATE_TOKEN\` before larger reads;
+compare \`agent.file_state(...).FILE_STATE_ID\` for one selected file. Observer
+principals use \`observe.spec_state\` and \`observe.file_state\` for
+authorization-scoped read-only state. File-state UUIDs include retained
+version-history changes. A missing object or revoked grant returns no row as
+the terminal polling signal; authorized query failures remain errors.
+\`app_observer\` grants access to the
+read-only procedure family; Airlock assignments and
+\`observer_access.observer_roles\` grant spec visibility. Observe-only calls do
+not consume a named seat. Account-wide access requires \`app_admin\` or the
+locked \`global_observer\` Airlock role, which cannot own specs, receive
+guest/reviewer grants, or manage child roles. Account-wide auditors should call
+\`observe.observers(...)\` for flattened observer scope and license posture;
+\`active_seat_observer_only\` requires explicit \`admin.unassign_license\` to
+stop future seat billing. Observer setup should use a dedicated Snowflake
+username and account role, the \`<APP_NAME>.app_observer\` application role, a
+distinct Airlock role/assignment, and explicit per-spec \`observer_access\`.
+Verify it with \`observe.observers\` and audit structured assignment before/after
+evidence with \`observe.admin_activity(..., action_family => 'assignments')\`.
+Every mutating human or automated agent must keep an attributable Snowflake
+principal. Use explicit Airlock delegation when it acts for someone else; never
+turn workspace membership or chat approval into Airlock authority. Treat
+\`EVENT_CONTEXT.snowflake_agent_active\` as informational provenance only. A
+\`DELEGATED_ACTION\` event records an authorized attempt, not proof of commitment.
+Store each supported mutation as an \`airlock.commitment-receipt/v1\`, preserving
+the authenticated actor, delegation identity derived from the actual call
+arguments, stable status/code/issues, target, and timestamp. Follow successful
+direct file mutations with \`agent.file_state\` to retain \`UPLOAD_ID\`,
+\`FILE_STATE_ID\`, and workflow state. Leave delegated \`committed_state\` null
+unless the actor performs a separate independently authorized observation.
+Do not use retired admin
 read wrappers such as \`admin.list_specs\`, \`admin.describe_role\`, or
 \`admin.list_events\`. If a reference spec declares \`restricted_reference\` or
 \`reference_config.restricted_reference\`, do not enumerate the protected
@@ -216,7 +301,17 @@ must use Airlock procedures instead of direct stage reads. Airlock MCP 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
-direct table writes.
+direct table writes. Treat the built-in Streamlit app as a generic
+operating/fallback surface. Recommend a purpose-built app when recurring,
+high-value domain work benefits from specialized summaries, calculations,
+evidence presentation, terminology, or controls. Keep those choices in app code
+rather than adding UI layout or aggregation hints to Airlock specs. For a
+structural spec change with active files, treat \`SPEC_MIGRATION_REQUIRED\` as
+the governed two-version lifecycle: use immutable revisions, bounded
+\`admin.run_spec_migration\` calls, \`observe.spec_migrations\` discovery,
+\`observe.spec_migration\` evidence, and guarded source retirement instead of
+direct table, stage, or view changes. \`admin.cancel_spec_migration\` is only a
+pre-activation abandonment path, not rollback.
 In co-development mode, keep the spec track and app track visible side by side.`;
 }