Merge remote-tracking branch 'origin/main' into claude/issue-24197-adr-0079-note

Author: claude

.changeset/24251-mcp-anonymous-first.md

@@ -0,0 +1,13 @@
+---
+'@objectstack/runtime': patch
+---
+
+fix(runtime): an anonymous caller of `/api/v1/mcp` is answered `401 UNAUTHENTICATED` whatever `OS_MCP_SERVER_ENABLED` or the `mcp` service says
+
+Clause-②: no
+
+ADR-0138 D2 takes the anonymous decision once per domain, as the domain's first statement. The `/mcp` domain checked the `OS_MCP_SERVER_ENABLED` switch and the `mcp` service before it, so an anonymous caller was answered `404 RESOURCE_NOT_FOUND` with the switch off and `501 NOT_IMPLEMENTED` with no MCP service installed, and learned whether the deployment runs MCP before it was refused. Measured on both hosts, the standalone server (`HonoServerPlugin` with the dispatcher plugin) and a `createHonoApp` host.
+
+- An anonymous request on `/api/v1/mcp` (any verb) is now refused `401 UNAUTHENTICATED` first, in every composition. Only the order of the refusals moves: no request that was refused before is accepted.
+- A signed-in caller, or a system principal, keeps the switch's `404` and the service's `501`, in that order.
+- The `401` advertises RFC 9728 resource metadata (`WWW-Authenticate: Bearer … resource_metadata="…"`) only where the resource is served: the switch on, an `mcp` service that can take the request, and an auth service that answers a metadata URL. With the switch off or no service the `401` is the plain API-key one, so it never points a client at a protected resource the deployment does not serve.

.changeset/24293-filter-token-message.md

@@ -0,0 +1,15 @@
+---
+"@objectstack/lint": patch
+---
+
+fix(lint): `filter-token-unknown` states what the runtime does with an unresolvable filter placeholder: the data engine refuses the query with `FILTER_TOKEN_UNKNOWN` / 400
+
+Clause-②: no
+
+The finding's message said the value "is sent to the data engine as a literal string, matches no record, and the surface renders empty". The runtime does not do that. The data engine refuses a query that carries an unresolvable placeholder, `FILTER_TOKEN_UNKNOWN` with HTTP 400, rather than compare it as a literal string. The message now reads:
+
+```text
+Filter value "{current_user}" is not a resolvable placeholder. The data engine refuses a query that carries it (`FILTER_TOKEN_UNKNOWN`, 400), so the surface never shows the data the filter meant.
+```
+
+Unchanged: the rule id, its severity (`error`), the finding's `path`, its `hint` (the `fix:` line), and which values the rule reports. The message's first sentence is unchanged as well. `os explain filter-token-unknown` already stated the refusal and is unchanged.

.github/workflows/scheduled-full-run-card.yml

@@ -42,9 +42,19 @@ name: Scheduled Full Run Card
 #              REFUSES rather than filing. The oldest match wins — it is the one
 #              any duplicates were closed against, and the one the devx seat
 #              already graded.
-#   REFRESH    the body is rewritten in place, never a comment per run. ⛔ Labels
-#              are applied on CREATE only: grading is the seat's and a refresh
-#              must not undo it.
+#   REFRESH    the body is rewritten in place, never a comment per run. ⛔ Grade
+#              labels (priority, lane, type) are applied on CREATE only:
+#              grading is the seat's and a refresh must not undo it. The one
+#              label a refresh may move is a STATE: a card still `pm:blocked`
+#              whose every `Blocked-by:` target (body or comments) is a LOCAL
+#              card that has closed goes back to `pm:queue` — a new red after
+#              the last blocker's fix landed on this `main` is new work, and
+#              `pm:blocked` hides it from every seat. ⛔ A closed CROSS-REPO
+#              target never releases it: closed there is merged upstream, not
+#              consumable here through the `.objectui-sha` pin. That, any
+#              target open or unreadable, no target and an assignee are among
+#              the cases where no label moves; every case and its reason:
+#              "A STALE `pm:blocked`" in the module.
 #   BODY       the run link, and the commits between the previous GREEN
 #              scheduled run of THIS workflow and this one. That range is the
 #              hour in which `main` broke, and an EMPTY range is a reading of
@@ -113,7 +123,7 @@ jobs:
     permissions:
       actions: read # list the previous green scheduled run
       contents: read # checkout, and the compare API
-      issues: write # the card, and nothing else
+      issues: write # the card (body, and the stale-block label swap) and the reads that judge it
     steps:
       - name: Checkout repository
         uses: actions/checkout@v7
@@ -214,11 +224,13 @@ jobs:
 
             // The DECISION is the module's, driven offline by its self-test
             // against a mutable board (one red run files one card; the next
-            // refreshes it and files no second). What is left here is three
-            // callbacks over the API.
+            // refreshes it and files no second; a refresh of a card whose
+            // every blocker is a closed LOCAL card moves `pm:blocked` to
+            // `pm:queue`). What is left here is thin callbacks over the API.
             const outcome = await mod.fileOrRefreshCard({
               identity,
               body,
+              ownerRepo: `${owner}/${repo}`,
               perPage: 100,
               maxPages: 10,
               listPage: async (page) => {
@@ -236,10 +248,31 @@ jobs:
                 const res = await github.rest.issues.create({ owner, repo, title, body: b, labels });
                 return { number: res.data.number };
               },
+              // Read only for a card carrying `pm:blocked`.
+              listComments: async ({ number, page, perPage }) => {
+                const res = await github.rest.issues.listComments({
+                  owner, repo, issue_number: number, per_page: perPage, page,
+                });
+                return res.data;
+              },
+              getIssue: async ({ repo: target, number }) => {
+                const [targetOwner, targetRepo] = target.split('/');
+                const res = await github.rest.issues.get({ owner: targetOwner, repo: targetRepo, issue_number: number });
+                return { state: res.data.state, closed_at: res.data.closed_at };
+              },
+              // The swap: an additive POST and ONE remove by name.
+              addLabels: async ({ number, labels }) => {
+                await github.rest.issues.addLabels({ owner, repo, issue_number: number, labels });
+              },
+              removeLabel: async ({ number, name }) => {
+                await github.rest.issues.removeLabel({ owner, repo, issue_number: number, name });
+              },
             });
 
             core.info(`${outcome.action} ${identity.marker} card #${outcome.number} (${body.length} chars)`);
-            core.notice(`${run.name} is red on the hourly full run — card #${outcome.number} ${outcome.action}.`);
+            if (outcome.block) core.info(`block: ${outcome.blockSummary}`);
+            const moved = outcome.block === 'expired' ? ' (every blocker closed: pm:blocked moved to pm:queue)' : '';
+            core.notice(`${run.name} is red on the hourly full run — card #${outcome.number} ${outcome.action}${moved}.`);
             core.setOutput('action', outcome.action);
             core.setOutput('number', String(outcome.number));
 

content/docs/ai/connect-mcp.mdx

@@ -12,8 +12,9 @@ about the only thing left to do: **connecting a client and proving it works**.
 
 <Callout type="info">
 To turn the surface off, set `OS_MCP_SERVER_ENABLED=false` — the endpoint then
-returns 404 and the **Connect an Agent** page disappears with it, along with
-both its Setup and Account navigation entries. See
+returns 404 to a caller with an API key or token (an anonymous caller still gets
+401 first, with no OAuth metadata advertised), and the **Connect an Agent** page
+disappears with it, along with both its Setup and Account navigation entries. See
 [environment variables](/docs/deployment/environment-variables#mcp-server).
 </Callout>
 
@@ -380,8 +381,8 @@ skill and a guided `/objectstack:connect` command.
 | **✘ Failed to connect** / `ConnectionRefused` on a server that used to work | The app is not running. Start it — the client reconnects on its own, no need to re-register |
 | The server is missing from `/mcp` in a running session | Sessions read MCP config at start — open a new one. If it is still missing, you registered at **local** scope from another directory; re-add with `-s user` |
 | `Object 'x' not found` on `query_records` / `get_record` | Wrong object name — pass the API name from `list_objects` in **`objectName`** (`crm_opportunity`, not `opportunity`) |
-| `404` on `/api/v1/mcp` | The HTTP surface is disabled — unset `OS_MCP_SERVER_ENABLED` (default is on) |
-| `501 Not Implemented` | The MCP plugin isn't part of this build — check your stack's plugins |
+| `404` on `/api/v1/mcp` | The HTTP surface is disabled — unset `OS_MCP_SERVER_ENABLED` (default is on). A client with an API key or token sees the `404`; an anonymous client, including an OAuth client before it signs in, sees a plain `401` with no `resource_metadata` in `WWW-Authenticate` |
+| `501 Not Implemented` | The MCP plugin isn't part of this build — check your stack's plugins. A client with an API key or token sees the `501`; an anonymous client sees a plain `401` with no `resource_metadata` |
 | `mcp` missing from `GET /api/v1/discovery` and no Connect-an-Agent card, but `OS_MCP_SERVER_ENABLED` is on | The same cause as the `501` above, seen from the other side: the surface is *enabled* but not *serveable*, so discovery declines to advertise a route that would 501 rather than over-promising it (`declared === enforced`). Load the MCP plugin — `os serve` / `os dev` do it for you; a host that embeds `@objectstack/rest` directly must add `@objectstack/mcp` itself |
 | stdio won't start / boot fails closed | `OS_MCP_STDIO_ENABLED=true` but `OS_MCP_STDIO_API_KEY` is missing, unknown, revoked, or expired — fail-closed by design (ADR-0101). Set a valid `osk_` key; there is no unscoped or `system` fallback |
 | `401` on every call | Anonymous or invalid credentials. Interactive clients: complete the browser login (the `WWW-Authenticate` header advertises the OAuth metadata). Headless: check the `osk_` key and header spelling |

content/docs/deployment/environment-variables.mdx

@@ -268,7 +268,7 @@ OS_MCP_STDIO_ENABLED=true OS_MCP_STDIO_API_KEY=osk_... os start   # start the lo
 
 | Variable | Type | Default | Description |
 |:---|:---|:---|:---|
-| `OS_MCP_SERVER_ENABLED` | boolean | `true` | The MCP **HTTP** surface (`/api/v1/mcp`) is a core capability and defaults **on**. Set `false` to disable it (endpoint 404s, the Connect-an-Agent page disappears). |
+| `OS_MCP_SERVER_ENABLED` | boolean | `true` | The MCP **HTTP** surface (`/api/v1/mcp`) is a core capability and defaults **on**. Set `false` to disable it (the endpoint answers 404 to a caller with an API key or token and 401 to an anonymous one, and the Connect-an-Agent page disappears). |
 | `OS_MCP_STDIO_ENABLED` | boolean | `false` | Auto-start the long-lived **stdio** transport at boot. Opt-in and **stricter** than the HTTP surface. **Requires `OS_MCP_STDIO_API_KEY`** — stdio runs as that key's identity with RLS/FLS/tenant applied; if the key is missing or invalid, boot **fails closed** (stdio refuses to start). See ADR-0101. |
 | `OS_MCP_STDIO_API_KEY` | string | — | The `osk_...` API key the **stdio** transport runs as. Resolved through the same verify chain as the HTTP/REST surfaces, so reads are scoped to that identity's permissions. Mint one from the **Connect an Agent** page — **Account → Developer** for any signed-in user, **Setup → Connect an Agent** for platform admins — or `POST /api/v1/keys`. For full authority, mint a key on a platform-admin or dedicated **service** identity — there is deliberately no `system`/unscoped bypass. |
 | `OS_MCP_SERVER_NAME` | string | `objectstack` | Server name advertised to MCP clients. |

packages/lint/src/authoring-rules.ts

@@ -914,9 +914,10 @@ export const AUTHORING_RULES: readonly AuthoringRule[] = [
       'saves, a rollout decision over stored tenant rows the in-repo corpus does not measure.',
     run: (stack) => validateDashboardWidgetOptions(stack),
   },
-  // #3574 — a filter value like `{current_user}` resolves in no vocabulary,
-  // reaches the data engine as a literal and matches nothing. The surface
-  // renders empty with no error, and a silent zero is indistinguishable from a
+  // #3574 — a filter value like `{current_user}` resolves in no vocabulary. The
+  // data engine refuses a query carrying it (`FILTER_TOKEN_UNKNOWN`, 400). When
+  // #3574 was filed it reached the engine as a literal and matched nothing: the
+  // surface rendered empty with no error, a silent zero indistinguishable from a
   // genuine one at review time.
   {
     name: 'validateFilterTokens',

packages/lint/src/validate-dataset-references.ts

@@ -33,10 +33,11 @@
  *
  * ## Why a dataset's dangling reference is worse than most
  *
- * `filter-token-unknown`'s own wording states the failure mode it exists to
- * prevent: the value is *"sent to the data engine as a literal string, matches
- * no record, and the surface renders empty."* A dangling field path produces
- * the same outcome from the same node.
+ * `filter-token-unknown` judges the VALUE at that same node, and the value it
+ * reports does not fail quietly: the data engine refuses the query
+ * (`FILTER_TOKEN_UNKNOWN`, 400). A dangling field path there is the quiet
+ * failure. By the severity note below, every outcome it produces reaches a
+ * human as a chart that rendered successfully.
  *
  * A dataset is the semantic layer — dashboards and reports bind its dimensions
  * and measures BY NAME (ADR-0021) — and the CONSUMER end of that binding is

packages/lint/src/validate-filter-tokens.test.ts

@@ -56,6 +56,18 @@ describe('validateFilterTokens', () => {
     expect(findings[0].hint).toContain('{current_user_id}');
   });
 
+  // [#24293] The message states the runtime's answer: the data engine refuses a
+  // query carrying the value (`UnknownFilterTokenError` in `@objectstack/core`,
+  // `FILTER_TOKEN_UNKNOWN` / 400). Held as that code, the named subject, not as
+  // the prose around it.
+  it('names the code the data engine refuses the query with, near miss or not', () => {
+    const findings = validateFilterTokens({
+      dashboards: [{ name: 'd', widgets: [{ id: 'w', filter: { a: '{current_user}', b: '{whoever_is_watching}' } }] }],
+    });
+    expect(findings.map((f) => f.path)).toEqual(['dashboards[0].widgets[0].filter.a', 'dashboards[0].widgets[0].filter.b']);
+    for (const f of findings) expect(f.message, f.path).toContain('`FILTER_TOKEN_UNKNOWN`');
+  });
+
   it('accepts the correct spelling alongside date macros', () => {
     expect(
       validateFilterTokens({

packages/lint/src/validate-filter-tokens.ts

@@ -22,22 +22,27 @@ import { recordsOf } from './object-graph.js';
  * Exactly two vocabularies resolve inside a filter value: context tokens
  * (`{current_user_id}`, `{current_org_id}` — see `context-tokens.zod.ts`) and
  * date macros (`{today}`, `{30_days_ago}` — see `date-macros.zod.ts`).
- * Anything else is passed to the data engine **verbatim**, matches no row, and
- * the surface renders an empty result.
+ * Anything else does not resolve: the data engine refuses a query that carries
+ * it (`FILTER_TOKEN_UNKNOWN`, 400 — `UnknownFilterTokenError` in
+ * `@objectstack/core`'s `filter-tokens.ts`), so the surface never shows the
+ * data the filter meant.
  *
  * ## Why this is an error, not a warning
  *
- * The runtime failure mode is silent and indistinguishable from success. A
- * metric widget filtered on an unresolved `{current_user}` renders `0`, which
- * looks exactly like a metric that is legitimately zero — no console error, no
- * server log, nothing for a human reviewer to notice. Issue #3574 found a
- * dashboard that had been broken this way since the day it was written.
+ * The rule is older than that refusal. When issue #3574 was filed, the runtime
+ * substituted no placeholder: the value reached the data engine verbatim and
+ * matched no row. A metric widget filtered on an unresolved `{current_user}`
+ * rendered `0`, which looks exactly like a metric that is legitimately zero —
+ * no console error, no server log, nothing for a human reviewer to notice.
+ * Issue #3574 found a dashboard that had been broken this way since the day it
+ * was written. The runtime now refuses the query instead, so the failure is no
+ * longer silent, but it still shows only when someone opens the surface.
  *
- * That failure mode is worse for AI authors than for humans. An AI reads a
- * successful query returning `0` as a correct answer and builds on it — it has
- * no instinct that the number looks wrong. Its correction loop is
- * "author → validate → fix", so a diagnostic only reaches it if the diagnostic
- * can fail the build. A runtime warning in a server log is invisible to it.
+ * Neither form reaches an AI author. An AI read the old `0` as a correct answer
+ * and built on it — it has no instinct that the number looks wrong. Its
+ * correction loop is "author → validate → fix", so a diagnostic only reaches it
+ * if the diagnostic can fail the build. A server log line, or a refusal that
+ * arrives when a surface is opened after the build passed, is invisible to it.
  * Hence: authoring-time error.
  *
  * The near-miss spellings this catches are not hypothetical. Each is a correct
@@ -103,7 +108,7 @@ export const FILTER_TOKEN_UNKNOWN = 'filter-token-unknown';
 export type FilterTokenSeverity = 'error' | 'warning';
 
 export interface FilterTokenFinding {
-  /** Always `error` today — an unresolved placeholder silently matches nothing. */
+  /** Always `error` today — the data engine refuses a query carrying an unresolvable placeholder. */
   severity: FilterTokenSeverity;
   /** Diagnostic rule id. */
   rule: string;
@@ -233,8 +238,9 @@ function walkFilterValues(
         where,
         path,
         message:
-          `Filter value "${node}" is not a resolvable placeholder. It is sent to the ` +
-          `data engine as a literal string, matches no record, and the surface renders empty.`,
+          `Filter value "${node}" is not a resolvable placeholder. The data engine refuses a ` +
+          `query that carries it (\`FILTER_TOKEN_UNKNOWN\`, 400), so the surface never shows ` +
+          `the data the filter meant.`,
         hint: suggestion && isRecordContextToken(suggestion)
           ? `Did you mean "{${suggestion}}"? It resolves only in a filter on a component of a ` +
             `\`type: 'record'\` page, to the id of the record in view.`