@reunionstudio/airlock-mcp 0.1.7 → 0.1.8

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

@@ -229,6 +229,27 @@ 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
@@ -243,6 +264,19 @@ 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
@@ -394,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,22 +54,83 @@ 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,
-watcher, deadline, overdue, and exception inbox. Use `airlock.observe.work(...)`
-for the read-only account-wide projection of current work, and
+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.
 
-Watcher agents should poll `airlock.agent.spec_state(...)` before retrieving a
+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, or exact source references change. Observer clients use
-the account-wide read-only `observe.spec_state(...)` and
-`observe.file_state(...)` equivalents.
+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,
@@ -115,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:
 
@@ -133,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
@@ -273,8 +361,8 @@ 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 all current work; historical questions
-belong to `observe.activity`.
+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

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

@@ -175,9 +175,39 @@ Use the installed Airlock procedure grammar:
 - `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 account-wide current work and
-`observe.activity` for historical events. Do not recreate separate workflow
-and expectation inbox calls in app code.
+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
@@ -185,9 +215,35 @@ 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, or exact-reference changes. Observer
-services may use the global read-only `observe.spec_state` and
-`observe.file_state` equivalents.
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reunionstudio/airlock-mcp",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Single-install MCP interface for Airlock agents.",
   "type": "module",
   "repository": {
@@ -30,6 +30,7 @@
     "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.7",
+    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.7"
+__version__ = "0.1.8"

package/src/mcp.mjs

@@ -44,7 +44,7 @@ export function handleMcpRequest(message) {
       },
       serverInfo: {
         name: "airlock",
-        version: "0.1.7",
+        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,14 +62,47 @@ 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. For watcher loops, cache the role-scoped
+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,
-or exact-reference changes. Observer services may use the account-wide
-\`observe.spec_state\` and \`observe.file_state\` equivalents. Offer to run \`airlock-mcp init-app-context\`
+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
@@ -131,7 +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 watcher polling
+  - 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
@@ -225,11 +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. For watcher loops, poll
+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
-services use \`observe.spec_state\` and \`observe.file_state\` for account-wide
-read-only state. Do not use retired admin
+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