fix(service-automation): the http node's url and headers describes route an outbound credential to a connector's credentialRef, and the showcase says its webhook url is served (#20590)

[objectstack-fleet]

Fixes #20590
Clause-②: no

What this changes

This is the domain:services face of triage's direction A on this card (ruling 5891721503, "Direction: A, taken whole"), scoped by the claim 5891908897. It carries two guidance edits and nothing else. Nothing new is withheld on read.

1. The http action descriptor's configSchema (packages/services/service-automation/src/builtin/http-nodes.ts). The url field read "Target URL" and the headers field read "Request headers". Both now say that the value is stored in the flow definition, that a flow definition is served to every member who can read flows, and that an outbound credential goes to a connector_action on a declarative connector whose auth.credentialRef names the secret. (Seat's correction after patch round 1: that holds for headers. For url, a query-string key goes to a declarative rest connector with api-key auth (paramName, auth.credentialRef), and a webhook whose path is the secret goes to a token-authenticated connector such as slack, since no credentialRef variant carries a path-borne secret.) Of this node's config, only signingSecret is withheld on read (FLOW_NODE_CREDENTIAL_KEYS), so url and headers are served as authored. A code comment beside the two fields records that.
2. The showcase's webhook-url teaching site (examples/app-showcase/src/automation/flows/index.ts, the slack_post node in showcase_fan_out_notify). The branch comment used to teach "post through an incoming webhook". It now sends a real post through a connector, as TaskCompletedSlackFlow already does. A comment directly above the placeholder url says that the url is served with the flow definition to every member who can read flows, and that an incoming-webhook url's path is its secret, so a real one never goes there.

A changeset (patch, @objectstack/service-automation) covers the descriptor text, which ships in that package's dist. The showcase is private, so it takes no changeset.

Mechanism assumptions, measured at 992c9ac87

A1: where the descriptor text reaches an author. AutomationEngine.getActionDescriptors() backs the runtime automation domain's GET /automation/actions, which is the designer palette's feed. The client SDK calls it as automation.listActions. The configSchema it serves is what the Studio property form is built from (io-node-form-zod-ledger.test.ts header).

• Measured with a one-shot probe (not committed): the real runtime HttpDispatcher, over a real AutomationEngine with installBuiltinNodes, answered GET /automation/actions with 200 and 17 descriptors. The http descriptor's url and headers descriptions are the new text.
• NOT MEASURED: how the Studio renderer shows a field description. That lives in the sibling UI repository, which is outside this run's scope.
• connector_action: its descriptor publishes no configSchema. That is deliberate: the executor reads only the FlowNodeSchema.connectorConfig sibling block. The same probe answered configSchema: null for it, and io-node-form-zod-ledger.test.ts and config-schemas.test.ts both pin it. So there is no services-side input describe to steer. The connectorConfig.input describe lives in packages/spec, which is spec+lint: flow http headers / connector input / url describes route credentials to credentialRef, and one exported predicate draws an author-time advisory on a credential-shaped literal (the spec half of #20590) #20654's face.
• Wording: the text matches the spec describes spec+lint: flow http headers / connector input / url describes route credentials to credentialRef, and one exported predicate draws an author-time advisory on a credential-shaped literal (the spec half of #20590) #20654 will carry, in substance: a flow definition is served to every member who can read flows, and an outbound credential goes to a declarative connector's auth.credentialRef. It also agrees with the flows guide sentence docs(automation): say an http node's url and headers are served; route credentials to connector credentialRef #20663 landed. The exact words are this PR's own.

A2: the showcase site. The showcase could not simply take the connector route.

• showcase_fan_out_notify is the platform checklist's parallel + http fixture (docs/qa/platform-checklist/areas/automation.json, automation.flow-node-type-matrix). That item locates the http variant's step in this flow's runs. Turning slack_post into a connector_action would move the tested surface.
• A provider-bound connector with a real credentialRef fails the boot when the reference does not resolve (resolveInstanceAuth, ADR-0097 §3). That is why every showcase instance declares auth: { type: 'none' }. Adding one would also touch src/system/connectors/index.ts, which is outside this card's file surface.
• So the url stays, and the comment beside it says plainly that it is served. The edit is comment-only: with whitespace minified, esbuild 0.28.1 compiles the file at the merge base and at 992c9ac87 to byte-identical JavaScript (sha256 prefix 6197a04e663ec0d8, 31,595 bytes). The positive control is a one-character change in the same url, which does change the output.

Tests, at 992c9ac87

• @objectstack/service-automation: 154 test files and 1,913 tests passed (vitest run --maxWorkers=2). typecheck passed, including check:test-typecheck. tsconfig.test.json compiles http-nodes.test.ts (counted with --listFiles).
• New pin in http-nodes.test.ts: the url and headers descriptions each name auth.credentialRef and connector_action. It asserts the named route, not the prose.
• Ablation, with the fix committed first, through scripts/ablation-replace.mjs in wrap mode plus a shell trap. The mutation put both descriptions back to their pre-fix text. On disk: auth.credentialRef count 2 to 0, and the old one-line fields 0 to 1 each. Result: exactly the two new cases failed, "2 failed, 8 passed", with the messages "expected 'Target URL' to contain 'auth.credentialRef'" and "expected 'Request headers' ...". Restore proof: blob 67f3d9d05a64 equals the HEAD blob, and git diff HEAD is empty. The test imports the source file directly, so no build sits in the path.
• Published surface: the built dist/index.js and dist/index.cjs each carry the new text twice, and the old headers description zero times. The positive control, the unchanged method description, appears once in each. files[] is dist, README.md, CHANGELOG.md.
• @objectstack/example-showcase: typecheck passed, and the full suite passed: 29 files, 385 tests.
• Lint, narrowed to the three touched .ts files: 3 files, 0 errors, 0 warnings (eslint --no-inline-config --format json). The narrowing is sound for three reasons. --print-config resolves a rule set for each file, so none is ignored. No parserOptions.project or projectService is set, so linting is not type-aware. A diff therefore cannot move any untouched file's verdict. The full pnpm lint is CI's.

Gates

node scripts/pm/dispatch-gates.mjs --commands at 992c9ac87 derived 63 commands. All 63 were run with each exit code captured before any pipe, and all exit 0. --ran reconciles "63 derived, 63 run, 0 NOT-MEASURED, 0 UNRUN", with every code recorded.

• check:dual-build-cjs-loads and check:type-check-debt first answered PREREQUISITE NOT MET (exit 3). They were re-run after a turbo build of every package, and both then passed.
• The four roster families were run separately, and each exited 0: node scripts/check-changeset-fixed.mjs, pnpm check:authz-resolver, pnpm check:error-code-casing and pnpm check:filter-alias-parity.
• The derivation reports that origin/main has moved five commits past this branch's base. None of those commits touches a path in this diff.

Acceptance notes

• content/docs/automation/flows.mdx still lists "an http node posting to an incoming webhook" as the replacement for the retired Slack actionType, in its retired-shapes table. The docs face's PR recorded the same line. It is outside this card's file surface.
• spec+lint: flow http headers / connector input / url describes route credentials to credentialRef, and one exported predicate draws an author-time advisory on a credential-shaped literal (the spec half of #20590) #20654 (spec describes, and the lint predicate and advisory) and skills(objectstack-automation): the http example routes an outbound credential to credentialRef and stops teaching a secret-bearing webhook url (the skills half of #20590) #20657 (the automation skill) remain open, and each carries its own face. The flows guide face landed separately.

Patch round 1 (the seat's append)

• R1 (at-tier record 5894416988): ConnectorInstanceAuthSchema has no variant for a secret in the url path, so the url describe no longer sends a path-secret webhook to auth.credentialRef. It routes by shape:
  • a query-string key goes to a declarative rest connector with api-key auth (paramName, auth.credentialRef);
  • a path-secret webhook goes to a token-authenticated connector (the slack bot token).
  • Every named route was verified at source (connector-auth.zod.ts, plugin.ts resolveInstanceAuth, rest-connector.ts applyAuth, slack-connector.ts).
  • The headers describe is unchanged. The code comment no longer claims the spec describes already match (spec+lint: flow http headers / connector input / url describes route credentials to credentialRef, and one exported predicate draws an author-time advisory on a credential-shaped literal (the spec half of #20590) #20654 is open).
• The changeset lists the three routes.
• At 695bb749: service-automation 1913 passed, typecheck exit 0. The ablation of the url clause turned exactly the url pin red, with the headers pin green, and the restore was proven. dist carries the new clause. 63 / 63 derived gates and the 4 ⛔ rosters exit 0.
• The same over-reach elsewhere: the landed flows.mdx callout and its retired-shapes row are docs(automation): flows.mdx routes a secret-bearing webhook url to auth.credentialRef, which no connector auth variant can carry, and still offers an http node posting to an incoming webhook as the Slack replacement #20682. spec+lint: flow http headers / connector input / url describes route credentials to credentialRef, and one exported predicate draws an author-time advisory on a credential-shaped literal (the spec half of #20590) #20654 and skills(objectstack-automation): the http example routes an outbound credential to credentialRef and stops teaching a secret-bearing webhook url (the skills half of #20590) #20657 carry wording guards.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 6 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 9a4b2bb38f9fb82c8e970d4f8d66d72379faa345 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from f01f1d1ec9951d4ab49469b601ba7b770c41e7ed — the merge of head 695bb749a0fe12d9899e19109f2e4515349c296f into base 9a4b2bb38f9fb82c8e970d4f8d66d72379faa345, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin f01f1d1ec9951d4ab49469b601ba7b770c41e7ed && git checkout f01f1d1ec9951d4ab49469b601ba7b770c41e7ed
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 9a4b2bb38f9fb82c8e970d4f8d66d72379faa345 695bb749a0fe12d9899e19109f2e4515349c296f && git checkout -B drift-repro 9a4b2bb38f9fb82c8e970d4f8d66d72379faa345 && git merge --no-ff 695bb749a0fe12d9899e19109f2e4515349c296f

node scripts/docs-audit/affected-docs.mjs --json 9a4b2bb38f9fb82c8e970d4f8d66d72379faa345

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.