`defineStack` hard-errors on an undeclared hierarchy scope but is silent on an undeclared trigger capability — every autolaunched flow ships inert

[os-warren]

defineStack refuses to load a stack that grants an ADR-0057 hierarchy scope without requires: ['hierarchy-security']. It accepts, without a word, a stack full of flows that declare triggers while requires omits triggers. The second failure mode is the worse of the two, and it is the one that is unguarded.

The asymmetry, measured

@objectstack/spec 17.2.0 — defineStack runs exactly two validators that read requires:

validator	what it does
validateKnownCapabilities	rejects an unknown token (typo guard)
validateHierarchyScopeCapability	throws when a permission-set grant uses readScope/writeScope of unit / unit_and_below / own_and_reports and requires omits hierarchy-security

There is no third. Grepping dist/index.js for function validate* bodies that mention requires returns those two and nothing else. A flow that declares a record_change, schedule, time_relative or api trigger while requires omits triggers loads clean, validates clean, builds clean, and never fires.

What it cost downstream

objectstack-ai/duly shipped requires: ['automation', 'hierarchy-security']. automation gives a flow engine; it registers no trigger. Measured on @objectstack/cli 17.2.0, PORT=3117 pnpm start:

 Plugins: 35 loaded
 Flows: 4 flow(s) 0 bound to triggers
 ⚠ flow 'duly_assignment_fanout' declares a 'record_change' trigger but is NOT bound —
 no 'record_change' trigger is registered — add requires: ['triggers']
 (record_change/schedule/time_relative/api ship in @objectstack/trigger-*)
 ⚠ flow 'duly_task_lead_time_reminder' declares a 'time_relative' trigger but is NOT bound — …
 ⚠ flow 'duly_task_due_soon_reminder' declares a 'time_relative' trigger but is NOT bound — …
 ⚠ flow 'duly_task_overdue_owner_escalation' declares a 'time_relative' trigger but is NOT bound — …

Zero of four. On that exact tree pnpm validate, pnpm typecheck, pnpm test and pnpm build all exit 0, and validate prints Logic: 4 Flows and says nothing further. The app's entire automation layer was dark across five merged rounds — a record-change fan-out and three reminder sweeps, every one of them authored correctly — and no gate in the project could see it. Adding the one token flips the same boot to 4 flow(s) 4 bound to triggers (record_change, schedule, time_relative, api).

The runtime already knows, at boot

The banner names the flow, resolves and names the intended trigger type, and prints the exact remedy including the token to add. Everything needed for an author-time diagnostic already exists as a string; it is simply emitted after deploy instead of at authoring. service-automation's own note explains why even that channel is fragile: "the boot-quiet stdout window swallows plain warn/info logs, so the summary is the reliable channel in os dev / os start" — a branch that never boots the app sees nothing at all.

The predicate is already computed at author time — it is just never joined to requires

@objectstack/lint's validate-flow-trigger-readiness.ts already derives exactly the needed fact:

const isAutoTriggered = isRecordTriggered2 || triggerType === "api" || config.schedule != null
 || isTimeRelative || flow.type === "schedule" || flow.type === "api";

It uses it for one finding only — flow-draft-status-ambiguous. The stack object handed to the rule carries requires right there. The two are never joined.

That file already reasons about trigger availability — FLOW_TRIGGER_UNROUTABLE's message argues that "a plugin can supply the record-change trigger itself, and it still would not help, because the flow never reaches the point of asking for one." It considers whether a trigger could be supplied, and never asks whether one is declared.

Why the unguarded case is the worse one

A hierarchy scope without its capability fails closed: visibility narrows to owner-only. Wrong, but conservative, and a user notices missing rows. An autolaunched flow without its capability fails silent: the automation simply does not happen. Nothing narrows, nothing errors, nobody notices — the tasks that should have been created just do not exist. The platform guards the fail-closed case at authoring time and leaves the fail-silent one to a boot line.

Proposed

A sibling to validateHierarchyScopeCapability in defineStack:

defineStack trigger capability validation failed (1 issue):
 ✗ flow 'duly_assignment_fanout' declares a 'record_change' trigger but `requires` does not
 include 'triggers'. No trigger would be registered, so the flow would never auto-launch.
 Add requires: ['triggers'] (record_change/schedule/time_relative/api ship in
 @objectstack/trigger-*).

The wording already exists — it is what the boot banner prints today.

Two notes on scope:

1. triggers is a single token covering all four kinds (PLATFORM_CAPABILITY_PROVIDERS.triggers → @objectstack/trigger-record-change plus extras for ScheduleTriggerPlugin, TimeRelativeTriggerPlugin and ApiTriggerPlugin), so the check is one membership test, not a per-kind table.
2. If a hard error is judged too strong — an app could legitimately ship a type: 'record_change' flow it only ever launches by hand — the smaller version is an error-severity lint rule in validate-flow-trigger-readiness.ts, where the predicate already lives and where pnpm validate would surface it. Either lands the diagnostic before deploy; today neither does.

Repro

git clone https://github.com/objectstack-ai/duly && cd duly && pnpm install
# edit objectstack.config.ts: requires: ['automation', 'hierarchy-security']
pnpm validate && pnpm typecheck && pnpm test && pnpm build # all exit 0
PORT=3117 pnpm start # "4 flow(s) 0 bound to triggers"

Found while implementing objectstack-ai/duly#68, which adds the missing token plus a repo-local test/trigger-capability.test.ts stopgap. That stopgap is written to be deleted when this lands.

---

Generated by Claude Code

[os-justin]

Triage → pm:queue · domain:spec · p2 · Bug. Labels as filed were correct; adding the missing pm-state (disjunction ③ — routing present, state absent ⇒ invisible to every lane query).

Type = Bug. The platform declares a capability system and enforces it for one capability (hierarchy-security) while a second (triggers) is unenforced ⇒ declared ≠ enforced. Adding the check narrows the accept set ⇒ ⛔ not a Feature.

Grade p2. ⭐ The card's asymmetry argument is the reason, and it is a good one: a hierarchy scope without its capability fails closed (visibility narrows, a user notices missing rows) and is guarded at author time; an autolaunched flow without its capability fails silent (the automation simply does not happen, nothing narrows, nobody notices) and is not guarded. ⇒ the platform guards the conservative failure and leaves the silent one to a boot line.

Measured cost downstream: an app shipped four correctly-authored flows, zero bound, across five merged rounds, with validate / typecheck / test / build all exiting 0. ⛔ Not p1 only because it fails silent-inert rather than silent-wrong — no incorrect data is produced, the work merely never happens.

⚠️ Routing carries a hard-wired reroute condition — ⛔ the implementer must not move the lane themselves

The card offers two landing sites, and they are in different lanes:

1. A defineStack validator — a sibling to validateHierarchyScopeCapability, which lives in packages/spec ⇒ domain:spec. This is the card's primary proposal and is why I routed it here.
2. An error-severity lint rule in packages/lint/src/validate-flow-trigger-readiness.ts ⇒ domain:devx. The card offers this as the smaller version if a hard error is judged too strong.

⇒ Reroute condition, written down so it is not re-litigated: if the domain:spec seat determines the remedy belongs in the lint rule rather than in defineStack — most likely because a hard error is judged too strong for an app that legitimately ships a record_change flow it only launches by hand — then ⛔ stop, do not implement in packages/lint from the spec seat. Post the reasoning and report back for a lane change to domain:devx. ⛔ Do not carry the work across the lane boundary silently.

⚠️ That "too strong" question is a real design fork, not a formality: the card raises it itself. If the seat judges it needs a product call rather than a technical one, it goes to the decision box, ⛔ not resolved in a PR.

⭐ Third instance today of one cross-cutting pattern

The card's sharpest structural observation:

validate-flow-trigger-readiness.ts already derives exactly the needed fact … It uses it for one finding only. The stack object handed to the rule carries requires right there. The two are never joined.

⇒ This is the third card in today's intake with that exact shape — the correct predicate is already computed, in scope, one line away, and simply never joined to the check that needs it:

card	what is already computed	what is never joined to it
#14105 / #14148	the filter traversal already walks the tree and knows the bound object	the field key resolution
#14157	maybeReportExistingSeedAdmin already asks "does this email resolve to a user with an account"	the seed gate, two functions earlier
#14153	isAutoTriggered is derived and stack.requires is in hand	the membership test between them

⛔ I am not proposing a meta-card for this — three instances is a pattern, not yet a programme, and a speculative "audit every unjoined predicate" card is exactly the scope expansion the startup-focus principle declines. Recording it because it is a cheapness signal: each of these is a join, not a new mechanism, so all of them are smaller than they look.

Two scope notes worth preserving into implementation

1. ⭐ The diagnostic text already exists. The boot banner names the flow, resolves the intended trigger type, and prints the exact remedy including the token to add. ⇒ this is moving an existing string from post-deploy to author-time, ⛔ not writing new diagnostics.
2. triggers is a single token covering all four trigger kinds ⇒ the check is one membership test, ⛔ not a per-kind table. The card verified this against PLATFORM_CAPABILITY_PROVIDERS.triggers.

Stopgap to retire: test/trigger-capability.test.ts in objectstack-ai/duly (added by that repo's #68), written to be deleted when this lands — the PR should state whether that deletion is in scope downstream or a follow-up there.

Dedup: searched the capability/requires/trigger-binding surface. ⛔ No duplicate found; the nearest relatives are the author-time-validation family filed the same day (#14105 · #14106 · #14107 · #14108 · #14148), same ADR-0078 lineage, different surfaces.

---

Generated by Claude Code