Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Commit 1cb3732

Browse files
feat(app-shell): Setup shows a time-triggered flow disabled by deployment policy with the platform's reason, not as a binding failure (objectui#9217) (#11271)
Fixes #9217 Clause-②: no Setup › Packaged automation now shows the platform's reason for a packaged flow the engine has not armed. The sentence appears verbatim, in muted text, under the flow name. This is option **B** from the card's decision: the seat's answer is on the card, comment 5919298624. ## Why The page read only `name` and `enabled` from `GET /api/v1/automation/_status`. A time-triggered flow left unarmed by the deployment's scheduled-work switch (`OS_AUTOMATION_SCHEDULED_WORK_ENABLED` unset, the default in every posture) showed as a plain "On", the same as a flow that runs. A flow whose trigger failed to bind looked exactly the same. `@objectstack/spec` 17.5.0 now carries `FlowRuntimeState.reason`, and its contract says "Consumers RENDER it; ⛔ do not parse it". ## What changed - `packagedFlows.ts`: `FlowRuntimeStateRow` declares `reason?: unknown`. `joinPackagedFlows` copies it onto the row only when it is a non-empty string. Otherwise the key is absent, the same way the engine omits it. - `PackagedAutomationPage.tsx`: a row with a `reason` renders it under the flow name as a muted paragraph (`text-muted-foreground`). There is no `role=alert` and no destructive class, and the text is never parsed or compared. A row without one renders exactly as before. The header's ADR-0126 §7.4 note gains one sentence recording the exception. - No dependency, no locale key and no copy of any platform sentence is added. The test file transcribes the platform's policy sentence as fixture text only, and it is byte-identical to `SCHEDULED_WORK_DISABLED_REASON` in `@objectstack/types` 17.5.0 (checked with a node equality against the installed package). - One changeset: `@object-ui/app-shell` minor. ## Pins - `packagedFlows.test.ts`, describe "the unbound reason (objectui#9217)": a string reason passes through unchanged; the key is absent on rows that send none (older backend included); non-string or empty values (42, true, null, an object, an array, the empty string) are ignored. - `PackagedAutomationPage.test.tsx`, describe "the platform reason for an unbound flow": a policy row shows the platform sentence verbatim, muted, and not as an alert, with no "binding failed" wording added (acceptance ① and ③); a binding-failure row shows its own sentence the same way (acceptance ②); a row without a reason keeps exactly its old flow-cell text (bound, disabled and bare older-backend rows); a non-string reason is ignored. ## Evidence (HEAD `d1a24b8fb`, every run after the final commit, heavy runs under `os-verify-lock`) - `pnpm exec vitest run --reporter=verbose packages/app-shell/src/views/setup/` gave `Test Files 5 passed (5)` and `Tests 65 passed (65)`. - **Ablation** (`ablation-replace.mjs`, WRAP mode). The reason paragraph was replaced with `null` (anchor 1 to 0, blob `3c9713a98d6a` to `6d25c6141bfd`). The page suite went to `Tests 2 failed | 12 passed (14)`. The two red tests are exactly the policy row and the binding-failure row; "row without a reason" and "non-string reason" stayed green. Restore was proven: the blob equals HEAD `3c9713a98d6a` and `git diff HEAD` is empty. The subject is imported from source, not from `dist`, so no dist preflight applies. - `turbo run build --filter='@object-ui/app-shell^...' --concurrency=2`: 28/28 tasks successful. Then `pnpm --filter @object-ui/app-shell type-check`, which runs `tsc --noEmit && tsc -p tsconfig.test.json`, exited 0 with 0 `error TS`. Both projects include the changed files; `tsconfig.test.json` lists both test files. - `pnpm exec eslint` on the 4 changed source/test files: 4 files linted, 0 errors, 0 warnings (counts from `--format json`). - `node scripts/check-changeset-presence.mjs`, `node scripts/check-control-bytes.mjs`, `pnpm check:new-line-citations` (0 new), `pnpm changeset:check`, `pnpm check:pending-changeset-literals` and `pnpm check:changeset-claims` all exited 0. - The diff adds a markdown changeset, so `node scripts/markdown-test-inputs.mjs --audit` was run (exit 0), and so was `pnpm exec vitest run scripts/__tests__/`: `Test Files 177 passed | 2 skipped (179)`, `Tests 5371 passed | 2 skipped (5373)`. - Not run locally: the i18n checks (no locale key and no `t()` call moved) and the full `pnpm test` / `pnpm lint` farm, which is left to CI. ## Acceptance notes - **Premise, measured before any code.** Before this change the Setup page showed no binding state at all. A render probe fed it a policy row and a binding-failure row, both enabled, bound false and carrying a reason. Both rendered identically, as name, "On" and "Clone", with neither sentence and no alert. So a failure row gaining its platform sentence is new behaviour that acceptance ② asks for, not a regression. The seat's answer withdrew the dispatch's "any other reason keeps today's rendering" on that measurement. - **Not in this PR:** the Studio Automations rail's `FlowStatusDot` still titles every enabled unbound flow "Enabled · no trigger (run manually)", including a policy-unbound schedule flow. Its file, `StudioDesignSurface.tsx`, is held by objectui#11232. The seat has recorded the finding and will file it as a sub-issue of objectui#9217 once that file is free. --- _Generated by [Claude Code](https://claude.ai/code/session_011p7ikEivgXefNDaE5S5Uec)_ Co-authored-by: Claude <noreply@anthropic.com>
1 parent 52aad5c commit 1cb3732

5 files changed

Lines changed: 196 additions & 1 deletion

File tree

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
'@object-ui/app-shell': minor
3+
---
4+
5+
Setup › Packaged automation shows the platform's reason for a packaged flow the engine has not armed, verbatim and in muted text under the flow name (objectui#9217).
6+
7+
**What it was.** The page read only `name` and `enabled` from `GET /api/v1/automation/_status`. A time-triggered flow left unarmed because the deployment has package-authored scheduled work switched off (`OS_AUTOMATION_SCHEDULED_WORK_ENABLED` unset, the default in every posture) showed as a plain "On", the same as a flow that runs. A flow whose trigger failed to bind looked identical.
8+
9+
**What changed, in observable terms.**
10+
11+
- When a `_status` row carries `reason` (`FlowRuntimeState.reason`, `@objectstack/spec` 17.5.0), the sentence appears under the flow's name exactly as the platform sent it. A deployment-policy row shows the platform's policy sentence, which names the variable that switches scheduled work on. A binding-failure row shows the platform's failure sentence.
12+
- The sentence is muted text. It is not an alert and has no error styling, and the page does not parse, compare or reword it, as the contract asks ("Consumers RENDER it; do not parse it").
13+
- A row without a `reason` renders exactly as before. That covers bound flows, disabled flows, flows with no trigger, and older backends that do not send the field. A `reason` that is not a non-empty string is ignored.
14+
- No dependency, locale key or copy of a platform sentence is added.

‎packages/app-shell/src/views/setup/PackagedAutomationPage.test.tsx‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,10 @@
2525
* not display it. Pinning the rule at the RENDERER and not only at the
2626
* wire is the point — a response field is the cheapest place for ancestry
2727
* to reappear.
28+
* 6. **the unbound reason** (objectui#9217) — a runtime row's `reason` is the
29+
* platform's sentence for why the flow is not armed. It is shown VERBATIM
30+
* and muted, never as an alert, whether it names the deployment policy or
31+
* a real binding failure; a row without one renders exactly as before.
2832
*/
2933

3034
import '@testing-library/jest-dom/vitest';
@@ -78,6 +82,28 @@ const CLONE_NOTICE =
7882
'off-switch — a cloned record-change or schedule flow is bound to its trigger and will run alongside ' +
7983
'the flow it was copied from.';
8084

85+
/**
86+
* `SCHEDULED_WORK_DISABLED_REASON` (`@objectstack/types` 17.5.0), the sentence
87+
* the automation engine puts in `FlowRuntimeState.reason` for a time-triggered
88+
* flow the deployment's scheduled-work switch left unarmed. Transcribed here as
89+
* FIXTURE text only: `@object-ui/app-shell` does not depend on that package,
90+
* and the page keeps no copy of it — what is pinned is that whatever sentence
91+
* arrives is rendered unedited.
92+
*/
93+
const POLICY_REASON =
94+
'disabled by deployment policy — package-authored scheduled work is off on this deployment ' +
95+
'(OS_AUTOMATION_SCHEDULED_WORK_ENABLED is unset or not truthy), so no time trigger arms and no ' +
96+
'packaged `defineJob` is scheduled. This is not a binding failure and nothing about the flow ' +
97+
'needs fixing: set OS_AUTOMATION_SCHEDULED_WORK_ENABLED=true to run package-authored scheduled ' +
98+
"work on this deployment. It is OFF by default in every posture — a clock-driven workload's " +
99+
'cost is a fact about the deployment, not about the flow.';
100+
101+
/**
102+
* The automation engine's `describeUnboundReason` sentence for a trigger that
103+
* is registered but failed to bind. Fixture text, like the one above.
104+
*/
105+
const BINDING_FAILED_REASON = "trigger 'record_change' is registered but binding failed — see earlier warnings";
106+
81107
/* -------------------------------------------------------------------------- */
82108
/* Fake server */
83109
/* -------------------------------------------------------------------------- */
@@ -430,3 +456,92 @@ describe('no ancestry or drift surface', () => {
430456
expect(screen.queryByText(/v3/)).toBeNull();
431457
});
432458
});
459+
460+
/* -------------------------------------------------------------------------- */
461+
/* 6) The unbound reason, verbatim (objectui#9217) */
462+
/* -------------------------------------------------------------------------- */
463+
464+
describe('the platform reason for an unbound flow', () => {
465+
/** The flow cell of ONE named row — where the name, and any reason, render. */
466+
function flowCell(flowName: string): HTMLElement {
467+
const cell = screen.getByTestId(`packaged-flow-${flowName}`).querySelector('td');
468+
if (!cell) throw new Error(`no flow cell for ${flowName}`);
469+
return cell;
470+
}
471+
472+
/**
473+
* The one assertion every reason row owes: the platform's sentence is in its
474+
* row, whole and unedited, in muted text — and nothing in the row is an alert
475+
* or destructive-styled.
476+
*/
477+
function expectMutedVerbatim(flowName: string, sentence: string) {
478+
const row = screen.getByTestId(`packaged-flow-${flowName}`);
479+
const shown = within(row).getByText(sentence);
480+
expect(shown.textContent).toBe(sentence);
481+
expect(shown).toHaveClass('text-muted-foreground');
482+
expect(shown).not.toHaveClass('text-destructive');
483+
expect(within(row).queryAllByRole('alert')).toHaveLength(0);
484+
expect(row.querySelectorAll('.text-destructive')).toHaveLength(0);
485+
}
486+
487+
it('shows a deployment-policy row with the platform sentence, muted, and not as a binding failure', async () => {
488+
fixture.runtime = [
489+
...fixture.runtime,
490+
{ name: 'pkg_digest', enabled: true, bound: false, triggerType: 'schedule', reason: POLICY_REASON },
491+
];
492+
fixture.meta = [...fixture.meta, packagedItem('pkg_digest', 'Daily digest')];
493+
await renderPage();
494+
495+
expectMutedVerbatim('pkg_digest', POLICY_REASON);
496+
// The page adds no failure wording of its own around the policy sentence.
497+
expect(screen.getByTestId('packaged-flow-pkg_digest').textContent).not.toMatch(/binding failed/i);
498+
// The flow's activation is still shown as the engine reports it.
499+
expect(screen.getByRole('switch', { name: 'Activation for Daily digest' })).toBeChecked();
500+
});
501+
502+
it('shows a real binding failure in the platform words too, muted (acceptance ②)', async () => {
503+
fixture.runtime = [
504+
...fixture.runtime,
505+
{
506+
name: 'pkg_sync',
507+
enabled: true,
508+
bound: false,
509+
triggerType: 'record_change',
510+
reason: BINDING_FAILED_REASON,
511+
},
512+
];
513+
fixture.meta = [...fixture.meta, packagedItem('pkg_sync', 'Sync accounts')];
514+
await renderPage();
515+
516+
expectMutedVerbatim('pkg_sync', BINDING_FAILED_REASON);
517+
});
518+
519+
it('renders a row without a reason exactly as before, older backends included', async () => {
520+
// `pkg_notify` (bound) and `pkg_escalate` (disabled) come from the default
521+
// fixture and carry no reason; `pkg_legacy` is an older backend's bare row.
522+
fixture.runtime = [...fixture.runtime, { name: 'pkg_legacy' }];
523+
fixture.meta = [...fixture.meta, packagedItem('pkg_legacy', 'Legacy flow')];
524+
await renderPage();
525+
526+
expect(flowCell('pkg_notify').textContent).toBe('Notify ownerpkg_notify');
527+
expect(flowCell('pkg_escalate').textContent).toBe('Escalate casepkg_escalate');
528+
expect(flowCell('pkg_legacy').textContent).toBe('Legacy flowpkg_legacy');
529+
});
530+
531+
it('ignores a reason that is not a string', async () => {
532+
fixture.runtime = [
533+
...fixture.runtime,
534+
{ name: 'pkg_numeric', enabled: true, bound: false, reason: 42 },
535+
{ name: 'pkg_object', enabled: true, bound: false, reason: { code: 'policy' } },
536+
];
537+
fixture.meta = [
538+
...fixture.meta,
539+
packagedItem('pkg_numeric', 'Numeric reason'),
540+
packagedItem('pkg_object', 'Object reason'),
541+
];
542+
await renderPage();
543+
544+
expect(flowCell('pkg_numeric').textContent).toBe('Numeric reasonpkg_numeric');
545+
expect(flowCell('pkg_object').textContent).toBe('Object reasonpkg_object');
546+
});
547+
});

‎packages/app-shell/src/views/setup/PackagedAutomationPage.tsx‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,9 @@
3636
* For the same reason this page shows no `bound` / `status` column even though
3737
* `_status` carries both: §7.4 scopes it to what the activation ledger knows.
3838
* The Studio rail is where a flow's binding is diagnosed.
39+
* The one exception is an unbound row's `reason`: the platform's own sentence
40+
* for why the flow is not armed, shown verbatim and muted under its name
41+
* (objectui#9217) — never parsed, never styled as an error.
3942
*
4043
* ## Server refusals reach the operator VERBATIM
4144
*
@@ -421,6 +424,14 @@ export function PackagedAutomationPage() {
421424
<TableCell className="align-top">
422425
<div className="font-medium">{row.label}</div>
423426
<code className="font-mono text-xs text-muted-foreground">{row.name}</code>
427+
{row.reason && (
428+
// The PLATFORM's sentence for why the engine has not
429+
// armed this flow, verbatim. Muted and NOT an alert: a
430+
// deployment-policy refusal names its operator switch in
431+
// its own words, a binding failure says so in its own,
432+
// and neither is re-styled or read here (objectui#9217).
433+
<p className="mt-2 max-w-prose text-sm text-muted-foreground">{row.reason}</p>
434+
)}
424435
{refusal && (
425436
// VERBATIM server refusal, next to the control that
426437
// caused it. `role="alert"` so it is announced.

‎packages/app-shell/src/views/setup/packagedFlows.test.ts‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,37 @@ describe('joinPackagedFlows', () => {
9999
});
100100
});
101101

102+
describe('the unbound reason (objectui#9217)', () => {
103+
it('carries a string `reason` through unchanged, character for character', () => {
104+
// Fixture text, not a contract: what is pinned is that whatever sentence
105+
// the platform sends reaches the row unedited.
106+
const sentence = "trigger 'record_change' is registered but binding failed — see earlier warnings";
107+
const rows = joinPackagedFlows(
108+
[{ name: 'pkg_notify', enabled: true, bound: false, triggerType: 'record_change', reason: sentence }],
109+
[packagedItem('pkg_notify', 'Notify')],
110+
);
111+
expect(rows[0]).toEqual({ name: 'pkg_notify', label: 'Notify', enabled: true, reason: sentence });
112+
});
113+
114+
it('leaves the key ABSENT on a row that sends none — including an older backend', () => {
115+
const rows = joinPackagedFlows(
116+
[{ name: 'pkg_notify', enabled: true, bound: true }, { name: 'pkg_legacy' }],
117+
[packagedItem('pkg_notify', 'Notify'), packagedItem('pkg_legacy', 'Legacy')],
118+
);
119+
for (const row of rows) expect(Object.keys(row)).not.toContain('reason');
120+
});
121+
122+
it('ignores a `reason` that is not a non-empty string', () => {
123+
const odd: unknown[] = [42, true, null, { code: 'policy' }, ['a sentence'], ''];
124+
const rows = joinPackagedFlows(
125+
odd.map((reason, i) => ({ name: `pkg_${i}`, enabled: true, bound: false, reason })),
126+
odd.map((_, i) => packagedItem(`pkg_${i}`, `Flow ${i}`)),
127+
);
128+
expect(rows).toHaveLength(odd.length);
129+
for (const row of rows) expect(Object.keys(row)).not.toContain('reason');
130+
});
131+
});
132+
102133
describe('envelope readers', () => {
103134
it('reads the runtime list wrapped or bare, and nothing else', () => {
104135
expect(readRuntimeStates({ data: { flows: [{ name: 'a' }] } })).toEqual([{ name: 'a' }]);

‎packages/app-shell/src/views/setup/packagedFlows.ts‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,18 @@
1515
*
1616
* A read projection over what the engine's `getFlowRuntimeStates()` returns —
1717
* every field optional because older backends answer with fewer of them, and
18-
* this page must degrade rather than throw. Only `name` and `enabled` are read.
18+
* this page must degrade rather than throw. Only `name`, `enabled` and `reason`
19+
* are read.
1920
*/
2021
export interface FlowRuntimeStateRow {
2122
name?: unknown;
2223
enabled?: unknown;
24+
/**
25+
* `FlowRuntimeState.reason` (`@objectstack/spec` 17.5.0): the platform's one
26+
* sentence saying WHY an enabled flow is not armed, absent on every other
27+
* row. `unknown` here like its siblings — only a string is taken.
28+
*/
29+
reason?: unknown;
2330
[key: string]: unknown;
2431
}
2532

@@ -31,6 +38,18 @@ export interface PackagedFlowRow {
3138
label: string;
3239
/** Activation state as the engine reports it. */
3340
enabled: boolean;
41+
/**
42+
* The platform's sentence for why the engine has not armed this flow —
43+
* present only when the runtime row carried a non-empty string `reason`.
44+
*
45+
* It is RENDERED, never read: the contract's own words on the field are
46+
* "Consumers RENDER it; ⛔ do not parse it". A deployment-policy refusal
47+
* (package-authored scheduled work switched off) and a real binding failure
48+
* both arrive here, each in the platform's own words, and this page tells
49+
* them apart only by showing those words (objectui#9217). No sentence is
50+
* matched, compared or restyled on this side, and none is kept in this repo.
51+
*/
52+
reason?: string;
3453
}
3554

3655
/**
@@ -94,12 +113,17 @@ export function joinPackagedFlows(
94113
const item = packaged.get(name);
95114
if (!item) continue;
96115
const label = item.label;
116+
const reason = state.reason;
97117
rows.push({
98118
name,
99119
label: typeof label === 'string' && label ? label : name,
100120
// `enabled` is TRUE unless the engine says otherwise: an older backend
101121
// that omits the field has no ledger to disable anything with.
102122
enabled: state.enabled !== false,
123+
// Absent, not `undefined`-valued, the way the engine omits it: a row
124+
// with nothing to explain renders exactly as it did before the field
125+
// existed, and so does every older backend that never sends one.
126+
...(typeof reason === 'string' && reason.length > 0 ? { reason } : {}),
103127
});
104128
}
105129
return rows.sort((a, b) => a.label.localeCompare(b.label) || a.name.localeCompare(b.name));

0 commit comments

Comments
 (0)