Merge remote-tracking branch 'origin/main' into claude/objectql-protocol-layering-s2sn67

# Conflicts:
#	packages/qa/dogfood/test/showcase-declarative-mcp.dogfood.test.ts
#	pnpm-lock.yaml

Author: claude

.changeset/console-23d65c396b8c.md

@@ -0,0 +1,27 @@
+---
+"@objectstack/console": patch
+---
+
+Console (objectui) refreshed to `23d65c396b8c`. Frontend changes in this range:
+
+- fix(i18n): drop try/catch-around-hook in createSafeTranslation / useSafeTranslate (#2605)
+- fix(app-shell): Studio Access matrix — history opens in-place sheet, breadcrumb stops escaping the pillar (#2599)
+- fix(data-objectstack): emit mutation events from batchTransaction/bulk so related lists refresh after master-detail saves (#2607)
+- fix(metadata-admin): follow the live app locale, not just navigator.language (#2602)
+- feat(detail+fields+components+app-shell): record inline-edit polish (#2572) (#2604)
+- fix(app-shell+kanban+list): row-predicate CEL authoring advertises runtime-bound roots; kanban binds host scope (#2571 follow-up) (#2603)
+- fix(plugin-list): spec bare-string sort form crashed ListView (#2578 shape-mismatch audit) (#2601)
+- fix(app-shell): lock the Access pillar permission matrix in read-only packages (#2570)
+- fix(fields): localize relative-date humanize via Intl.RelativeTimeFormat (framework#3040) (#2593)
+- fix(components): pin sticky leading cells at measured header widths (#2592)
+- fix(app-shell,core): keep error-envelope objects out of toast.error — React #31 page crash (#2579) (#2580)
+- feat(flow-designer): pick the target node per branch in the Decision Branches editor (#1942) (#2568)
+- fix(core+data-objectstack+app-shell): canonicalize reference/reference_to at the schema chokepoints (#2407) (#2598)
+- fix(dashboard-filters): spec-form filter options crashed the dashboard; add guide screenshots (#2578) (#2597)
+- fix(fields): PeoplePicker cursor resets only on real result changes (de-flakes keyboard test) (#2594)
+- fix(studio): stop force-opening the new-object dialog on empty packages (#2569)
+- feat(studio): CEL editor with validate + autocomplete for field conditional rules (#1582) (#2571)
+- feat(kanban): default lane field honours the ADR-0085 stageField role (#2596)
+- fix(fields+detail): resolve pre-existing rules-of-hooks violations in cell renderers (#2595)
+
+objectui range: `fb35e4828fdb...23d65c396b8c`

.changeset/console-b8967495be73.md

@@ -0,0 +1,12 @@
+---
+"@objectstack/console": minor
+---
+
+Console (objectui) refreshed to `b8967495be73`. Frontend changes in this range:
+
+- fix(app-shell): guard unsaved OWD overview rows in the Access rail and Studio header nav (#2600 follow-up) (#2610)
+- fix(actions): defuse the three action-visibility traps (#2358) (#2611)
+- fix(studio): confirm before header SPA nav discards unsaved pillar edits (#2600) (#2606)
+- feat(studio): CEL formula editor with inferred result type; structured summary roll-up editor (#1582) (#2609)
+
+objectui range: `23d65c396b8c...b8967495be73`

.objectui-sha

@@ -1 +1 @@
-fb35e4828fdb3b6ecc23761a82e9ec4a13890727
+b8967495be738780b3bf2e42b0eaeeb8fd127fa8

content/docs/automation/flows.mdx

@@ -117,6 +117,8 @@ Each node performs a specific action in the flow.
 | `map` | Sequential multi-instance — run a per-item subflow for each element, one at a time (each may pause); batch approval (ADR-0039) |
 | `connector_action` | Execute an external connector action |
 
+`connector_action` dispatches against the runtime **connector registry**, which connector plugins populate. The three **generic executors** — `rest`, `openapi`, and `mcp` — double as provider factories: with them in your app's `plugins:`, a declarative `connectors:` entry that names a `provider` is materialized into a live, dispatchable connector at boot with no plugin code (ADR-0097; the showcase example wires all three). Brand connectors (Slack, …) are installed separately. One security note: a declarative `mcp` instance using a **stdio** transport spawns a local process from metadata and is therefore denied by default — the host opts in with `new ConnectorMcpPlugin({ declarativeStdio: ['<trusted-command>'] })`; `http` transports need no opt-in.
+
 ### Node Structure
 
 ```typescript

examples/app-showcase/objectstack.config.ts

@@ -1,6 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { defineStack } from '@objectstack/spec';
+import { ConnectorMcpPlugin } from '@objectstack/connector-mcp';
 import { ConnectorOpenApiPlugin } from '@objectstack/connector-openapi';
 import { ConnectorRestPlugin } from '@objectstack/connector-rest';
 import { ConnectorSlackPlugin } from '@objectstack/connector-slack';
@@ -112,8 +113,19 @@ export default defineStack({
   //               (ADR-0097), which materializes the StatusOpenApiConnector
   //               declarative instance below — its OpenAPI document is a
   //               package-relative FILE PATH read at boot (#3016).
+  //   • mcp     → contributes the `mcp` provider factory, which materializes
+  //               the DevToolsMcpConnector declarative instance from the
+  //               in-repo stdio fixture (scripts/mcp-fixture.mjs). The
+  //               `declarativeStdio` allowlist is the #3055 security opt-in:
+  //               declarative stdio transports spawn a local process from
+  //               METADATA, so they are denied by default; this host
+  //               deliberately trusts `node` to run the in-repo fixture.
+  //               (A coarse boundary by design — trusting `node` trusts what
+  //               it is asked to run; real deployments should list specific
+  //               server binaries.)
   plugins: [
     new ConnectorOpenApiPlugin(),
+    new ConnectorMcpPlugin({ declarativeStdio: ['node'] }),
     new ConnectorRestPlugin({
       name: 'rest',
       baseUrl: process.env.SHOWCASE_SELF_URL ?? 'http://127.0.0.1:3000',

examples/app-showcase/package.json

@@ -22,7 +22,9 @@
     "test:smoke": "playwright test --config=playwright.config.ts"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@objectstack/cloud-connection": "workspace:*",
+    "@objectstack/connector-mcp": "workspace:*",
     "@objectstack/connector-openapi": "workspace:*",
     "@objectstack/connector-rest": "workspace:*",
     "@objectstack/connector-slack": "workspace:*",

examples/app-showcase/scripts/mcp-fixture.mjs

@@ -0,0 +1,54 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+//
+// Tiny in-repo MCP server (stdio) — the deterministic target for the
+// showcase's declarative `provider: 'mcp'` connector instance (#3056,
+// completing the live demo deferred from #3017 / ADR-0097 §6).
+//
+// Why a fixture instead of a real server: the demo must materialize during
+// BOOT in CI (the Dogfood Regression Gate), so the target has to exist with
+// no network, no ports, and no boot-ordering coupling. A stdio child process
+// spawned at materialization is exactly that. The spawn is allowlisted by the
+// host via `new ConnectorMcpPlugin({ declarativeStdio: ['node'] })` in
+// objectstack.config.ts — dogfooding the #3055 opt-in.
+//
+// One deliberately boring, deterministic tool: `echo_upper` upper-cases the
+// input text, so the flow run's captured output proves the whole chain
+// (metadata entry → mcp provider factory → tools/list → connector_action
+// dispatch → tools/call) with zero flakiness.
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+const server = new Server(
+  { name: 'showcase-mcp-fixture', version: '1.0.0' },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'echo_upper',
+      description: 'Upper-case the input text (deterministic showcase demo tool).',
+      inputSchema: {
+        type: 'object',
+        properties: { text: { type: 'string', description: 'Text to upper-case' } },
+        required: ['text'],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  if (req.params.name !== 'echo_upper') {
+    return { content: [{ type: 'text', text: `unknown tool: ${req.params.name}` }], isError: true };
+  }
+  const text = String(req.params.arguments?.text ?? '');
+  const upper = text.toUpperCase();
+  return {
+    content: [{ type: 'text', text: upper }],
+    structuredContent: { upper },
+  };
+});
+
+await server.connect(new StdioServerTransport());

examples/app-showcase/src/automation/flows/index.ts

@@ -445,6 +445,55 @@ export const ShowcaseDeclarativeConnectorPingFlow = defineFlow({
   ],
 });
 
+/**
+ * MCP Connector Echo (ADR-0097 / #3056) — dispatches through the DECLARATIVE
+ * MCP instance `showcase_mcp_tools` (src/system/connectors/index.ts), which the
+ * `mcp` provider materialized at boot from the in-repo stdio fixture server:
+ * its `tools/list` became the action list, and this `connector_action` invokes
+ * the `echo_upper` tool via `tools/call`. The run's captured output
+ * (`structuredContent.upper === 'OBJECTSTACK'`) proves the full chain —
+ * metadata entry → provider factory → MCP handshake → flow dispatch — with no
+ * external dependency. Completes the `provider: 'mcp'` acceptance demo from
+ * ADR-0097 §6, deferred at #3017.
+ */
+export const ShowcaseMcpConnectorEchoFlow = defineFlow({
+  name: 'showcase_mcp_connector_echo',
+  label: 'MCP Connector Echo (ADR-0097)',
+  description:
+    'Dispatches the echo_upper tool of showcase_mcp_tools — a declarative MCP connector instance materialized ' +
+    'at boot from the in-repo stdio fixture (scripts/mcp-fixture.mjs).',
+  type: 'autolaunched',
+  // Surface the tool result on the run output, so the flow run view (and the
+  // dogfood proof) can assert the MCP round-trip observably.
+  variables: [{ name: 'echo.structuredContent', type: 'json', isOutput: true }],
+  nodes: [
+    {
+      id: 'start',
+      type: 'start',
+      label: 'On Task Created',
+      config: {
+        objectName: 'showcase_task',
+        triggerType: 'record-after-create',
+      },
+    },
+    {
+      id: 'echo',
+      type: 'connector_action',
+      label: 'echo_upper via MCP (declarative)',
+      connectorConfig: {
+        connectorId: 'showcase_mcp_tools',
+        actionId: 'echo_upper',
+        input: { text: 'objectstack' },
+      },
+    },
+    { id: 'end', type: 'end', label: 'End' },
+  ],
+  edges: [
+    { id: 'e1', source: 'start', target: 'echo' },
+    { id: 'e2', source: 'echo', target: 'end' },
+  ],
+});
+
 /**
  * Task Follow-up Reminder — the worked `wait` (durable timer) example.
  *
@@ -1327,6 +1376,7 @@ export const allFlows = [
   ScheduledDigestFlow,
   TaskCompletedRestPingFlow,
   ShowcaseDeclarativeConnectorPingFlow,
+  ShowcaseMcpConnectorEchoFlow,
   TaskFollowUpFlow,
   NotifyOwnerSubflow,
   TaskDoneNotifyOwnerFlow,

examples/app-showcase/src/coverage.ts

@@ -184,7 +184,7 @@ export const STACK_COLLECTION_COVERAGE: Record<string, KindCoverage> = {
     status: 'demonstrated',
     files: ['src/system/connectors/index.ts', 'src/automation/flows/index.ts'],
     notes:
-      'Both connector kinds are demonstrated. (1) Provider-bound INSTANCES (ADR-0097 / #2977): StatusApiConnector declares `provider: rest` (inline config) and StatusOpenApiConnector declares `provider: openapi` with its OpenAPI document referenced as a package-relative FILE PATH (#3016, read at boot and confined to the package root) — both are materialized into live, dispatchable connectors at boot; ShowcaseDeclarativeConnectorPingFlow calls the rest instance via connector_action and both appear in GET /connectors. (2) Catalog DESCRIPTOR (#2612): ErpCatalogConnector has no provider, so it stays inert metadata; enabled:false marks the deliberate catalog entry and silences the boot audit. Plugin-registered connectors (ConnectorRestPlugin/ConnectorSlackPlugin in objectstack.config.ts) are also exercised by the connector flows.',
+      'Both connector kinds are demonstrated. (1) Provider-bound INSTANCES (ADR-0097 / #2977) cover all three generic executors: StatusApiConnector declares `provider: rest` (inline config), StatusOpenApiConnector declares `provider: openapi` with its OpenAPI document referenced as a package-relative FILE PATH (#3016, read at boot and confined to the package root), and DevToolsMcpConnector declares `provider: mcp` against the in-repo stdio fixture (scripts/mcp-fixture.mjs, #3056) — spawned under the host declarativeStdio allowlist (#3055) and mapped tools/list → actions. All three are materialized into live, dispatchable connectors at boot; ShowcaseDeclarativeConnectorPingFlow calls the rest instance and ShowcaseMcpConnectorEchoFlow calls the mcp instance via connector_action, and all appear in GET /connectors. (2) Catalog DESCRIPTOR (#2612): ErpCatalogConnector has no provider, so it stays inert metadata; enabled:false marks the deliberate catalog entry and silences the boot audit. Plugin-registered connectors (ConnectorRestPlugin/ConnectorSlackPlugin in objectstack.config.ts) are also exercised by the connector flows.',
   },
 };
 

examples/app-showcase/src/system/connectors/index.ts

@@ -91,6 +91,45 @@ export const StatusOpenApiConnector = defineConnector({
   auth: { type: 'none' },
 });
 
+/**
+ * ADR-0097 provider-bound instance, **mcp** form (#3056, completing the live
+ * demo deferred from #3017): the entry points at the tiny in-repo MCP fixture
+ * server (`scripts/mcp-fixture.mjs`) over a **stdio** transport. At boot the
+ * `mcp` provider factory (ConnectorMcpPlugin in objectstack.config.ts) spawns
+ * the fixture, calls `tools/list`, and maps its one deterministic tool
+ * (`echo_upper`) to a connector action — no network, no ports, no boot-ordering
+ * coupling, so the demo is CI-deterministic.
+ *
+ * Two platform behaviors are dogfooded here:
+ * - **#3055 stdio policy**: a declarative stdio transport spawns a local
+ *   process from metadata, so it is denied by default; the host opts in via
+ *   `new ConnectorMcpPlugin({ declarativeStdio: ['node'] })` in
+ *   objectstack.config.ts. Remove that option and boot fails loudly with the
+ *   opt-in instructions — try it.
+ * - **#3049 degrade + retry**: if the fixture were unreachable (e.g. the
+ *   script path wrong), boot would NOT crash — the instance registers
+ *   `state: 'degraded'` on GET /connectors and the platform retries with
+ *   backoff until it heals.
+ */
+export const DevToolsMcpConnector = defineConnector({
+  name: 'showcase_mcp_tools',
+  label: 'Dev Tools (Declarative MCP Instance)',
+  type: 'api',
+  description:
+    'Provider-bound declarative connector instance (ADR-0097) backed by a Model Context Protocol server: the ' +
+    'in-repo stdio fixture (scripts/mcp-fixture.mjs). Its tools/list becomes the action list — echo_upper is ' +
+    'dispatched end-to-end by ShowcaseMcpConnectorEchoFlow.',
+  provider: 'mcp',
+  providerConfig: {
+    // Spawned at materialization; the path is relative to the app's working
+    // directory (`os dev`/`serve` run from the app root). The command must be
+    // allowlisted by the host's declarativeStdio policy (#3055) — see
+    // objectstack.config.ts.
+    transport: { kind: 'stdio', command: 'node', args: ['./scripts/mcp-fixture.mjs'] },
+  },
+  auth: { type: 'none' },
+});
+
 export const ErpCatalogConnector = defineConnector({
   name: 'showcase_erp_catalog',
   label: 'ERP Integration (Catalog Descriptor)',
@@ -143,4 +182,9 @@ export const ErpCatalogConnector = defineConnector({
   enabled: false,
 });
 
-export const allConnectors: Connector[] = [StatusApiConnector, StatusOpenApiConnector, ErpCatalogConnector];
+export const allConnectors: Connector[] = [
+  StatusApiConnector,
+  StatusOpenApiConnector,
+  DevToolsMcpConnector,
+  ErpCatalogConnector,
+];