Design: post-install customization of packaged flows — clone-to-customize + org-level takeover (supersedes the org-tunable-parameters framing)

[yinlianghui]

The gap

Packaged flows are immutable at runtime by design, and the design is sound as far as it goes: flow is supportsOverlay: false, allowOrgOverride: false (rolled back after #6190's phantom overlay), and the ADR language calls per-org variants "a deployment, not an overlay" because flows carry execution side-effects.

But closing the whole flow also closes the plain business parameters inside it. Concrete case (HotCRM reference app): the approval threshold LARGE_DEAL_AMOUNT = 100_000 consumed by opportunity_approval. An org admin who wants the bar at $200K has no supported path:

• can't overlay the packaged flow (403 not_overridable — correct, per the above);
• can't even deactivate it (status lives in the immutable artifact);
• authoring a runtime replacement double-fires alongside the packaged flow it can't switch off;
• the only real path is edit source → CI → redeploy, which is out of reach for a non-developer admin and disproportionate for a numeric policy knob.

Ask

A supported mechanism for org-level tunables consumed by packaged automation. Candidate shapes (product team's call):

1. Package-declared config/settings values referenced from flow conditions (settings.large_deal_amount), with the parameter — not the flow — being org-overridable;
2. Partial overlay limited to declared parameter slots (the flow author marks which literals are tunable; everything structural stays locked);
3. A supported deactivate-and-replace path for packaged flows, so a runtime-authored variant can take over without double-firing.

Option 1 seems most aligned with the existing two-tier model (it adds no flow-overlay read path, so the #6190 class of phantom stays impossible).

Provenance

Surfaced by the product owner while reviewing promo video #4 (video-studio): the expectation "a human can open the designer and adjust the amount condition" is currently unmeetable for shipped flows. Filing as a product-design discussion — unassigned, not claimed.

[os-zhuang]

分诊(session session_01Nd9biL1MqkZT5tzgTEp7AB,2026-08-24):功能新增类 ⇒ 人工地板,入决策箱(needs-user-decision + domain:services,type Feature)。四棱卡面块如下。

os-decision-facets

一句话问题:打包应用里的自动化流程把业务阈值(金额上限、提醒天数这类数字)写死在包产物里 —— 客户组织想改一个数字,今天唯一的路是改包重新发布。要不要给「组织级可调参数」一个受支持的运行时入口?

选项 × 真实代价:

• A 建参数机制(流程声明可调参数 + 组织级覆盖存储):客户管理员自己改阈值,不动包、升级不丢;代价 = 一条新契约面(参数声明 schema、覆盖存储、权限、Setup UI),是产品级能力不是小改。
• B 放开 flow 的 allowOrgOverride(整只流程组织级 fork):客户什么都能改;代价 = 静默 fork —— 包升级后客户覆盖悄悄滞后,正是 Studio save of a package-declared permission set forks it into a silent, undiscoverable overlay #11513 permission-set 静默 fork 被裁死的同一形状(registry + 测试今天也明确拒绝,见 docs: metadata-lifecycle overlay-whitelist table contradicts the registry on flow — table says allowOrgOverride ✅, code and tests say ❌ #11664)。
• C 维持现状(改包重发):零新面;代价 = 每次调参都是一次包发布,发布节奏归包作者不归客户。

四棱:
① 项目长远合理性:A 是受控参数化,方向与 #11513 裁决(包声明锁定 + clone-to-customize,静默 fork 关死)一致;B 与之相悖,基本不可选。
② 实际业务拉动:卡内没有具名客户场景 —— 今天没有实测的「谁在为哪个阈值疼」;零拉动的能力面默认 defer。
③ 防 AI 犯错:A 的参数声明是闭合面(声明即强制,改错当场红);B 的自由覆盖是 AI 批量犯错温床;C 无新错误面。
④ 创业阶段不扩散:无实测拉动的扩张默认从紧 ⇒ C;A 记为将来有真实拉动时的正确形状。

推荐:C(暂缓,直接关闭本卡、卡即记录),待 hotcrm/真实部署出现具名场景时以 A-最小版重开;回退 = A-最小版(单一 number/string 参数、无 UI 先行)。置信缺口:未测 hotcrm 与真实部署是否已有该痛点;未测既有包里有多少「本该是参数」的硬编码阈值(数字大小会改变 A 的性价比)。回「A」/「B」/「C」即可。

关联:#11664(docs 表与 registry 在 flow ❌ 上的矛盾)按现状先行修正,与本裁独立。

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling recorded

Ruled 2026-08-24, live PM chat, verbatim: 「其他按照你的建议继续」 (adopting the skills seat's four-facet digest, which recommended shape 1 with a single-example first slice).

Ruled: shape 1 — package-declared settings values referenced from flow conditions (settings.large_deal_amount-style), with the PARAMETER being org-overridable through the existing settings channel while the flow artifact stays locked. Shapes 2 and 3 are NOT taken: 2 invents a partial-overlay semantics for flows (the softened form of the direction #6190's phantom-overlay incident rolled back), 3 sidesteps the ask and mirrors the double-firing risk.

First slice, deliberately minimal: prove the full chain on exactly ONE HotCRM parameter — declare LARGE_DEAL_AMOUNT as a package settings value, reference it from opportunity_approval's condition, change it org-side in Setup, observe the flow honor the new threshold. ⛔ Not in the first slice: a generic "flow parameters" UI, bulk migration of existing packaged flows' literals, or any flow-overlay read path (none is added — the #6190 class stays impossible by construction).

Implementation likely spans service-automation (settings reference resolution in flow conditions, if not already supported) + HotCRM (the exemplar declaration) — the services seat prices whether the platform half already exists (flow conditions may already evaluate settings.*; measure before building) and splits cards accordingly, with the hotcrm lane taking the exemplar half per the anchoring rule. needs-user-decision → pm:queue in the same stroke.

---

Generated by Claude Code

[claude]

{
 "issue": 11665,
 "status": "needs_decision",
 "branch": "claude/issue-11665-settings-in-flow-conditions",
 "pr": null,
 "premise_still_valid": true,
 "summary": "Q1 ANSWERED — NO. A flow condition CANNOT reference a settings value today, and it is not partial: the name `settings` is unbound in BOTH condition dialects, and service-automation has no read path to the settings service at all (its package.json deps are core/formula/metadata-core/spec — service-settings is absent; the only 'settings' string in its non-test source is a doc comment about the lifecycle retention namespace at src/plugin.ts:129, read and confirmed a comment). Evidence on origin/main @78f65ef518: packages/formula/src/stdlib.ts:302-330 buildScope() binds only record/previous/input/current_user/user/ctx.user/os.{user,org,env} + ctx.extra; service-automation/src/engine.ts:6004 evaluateCondition() hands CEL only `{ extra: {...vars, vars}, record: vars }` where vars IS the flow variable map; engine.ts seedRunVariables() (~6470-6490) seeds declared vars, $record/record + flattened trigger fields, previous, $runId, $flowName, $flowLabel — no settings; service-automation/src/builtin/template.ts:47-118 resolveToken() supports {var} {var.path} {$User.*} {NOW()} {TODAY()} — no settings head. WHAT ALREADY EXISTS, so nobody rebuilds it: (1) the org-override channel is real — SettingsService resolves env > tenant > user > default, `scope:'tenant'` IS the org override over a package-declared per-specifier default (service-settings/src/settings-service.ts:792 registerManifest); (2) a package CAN declare settings today, but only PROGRAMMATICALLY — a plugin calls ctx.getService('settings').registerManifest(...) (pattern at packages/objectql/src/plugin.ts:509) and a stack carries plugins (spec/src/stack.zod.ts:664); there is NO metadata-authorable settings declaration (stack.zod.ts has no `settings` key and no loader reads a settings file); (3) the org identity is ALREADY plumbed into the run — AutomationContext.tenantId, spec/src/contracts/automation-service.ts:57; (4) the ruling's own invariant is ALREADY PINNED BY IDENTITY, so no new pin is owed — flow is supportsOverlay:false, allowOrgOverride:false, executionPinned:true (spec/src/kernel/metadata-plugin.zod.ts:827) and metadata-protocol/src/protocol.org-scoped-write-refused.test.ts asserts orgOverridable equals exactly ['view','dashboard','report','translation','email_template'] plus R4 pinning the #6190 flow specimen at NOT_OVERRIDABLE/403. WHY I STOPPED RATHER THAN BUILT: the residual gap is one read path plus one exposure/naming CONTRACT, and the contract half is neither mine nor settled by the ruling — see open_questions. CLAUSE-2 ASSESSED AGAINST THE TREE, as required: ANY implementation of shape 1 is Clause-2, including the variant that adds no new authorable key, because accept/reject behaviour flips by construction (M1/M2 below go from throw to evaluate) and the public authoring surface widens by a new reference form in a contract dialect; for the declaration half the path hint agrees — both candidate sites are under packages/spec/src/** (SUSPECT_TIER_GLOBS), and this seat has zero packages/spec ownership. NO flow-overlay read path was designed or added; the ruled load-bearing property is intact and untouched. CARD SPLIT (the ruling asked this seat to split): [platform/spec card, objectstack] blocked on the two open questions — once the contract is fixed the binding half is small and local: resolve at run start inside engine.ts execute(), bind under seedRunVariables so the values land in the run's variable snapshot and survive suspend/resume, with AutomationContext.tenantId supplying the org. [hotcrm lane leg — NOT MEASURED, objectstack-ai/hotcrm is not in this session's repo scope] declare LARGE_DEAL_AMOUNT; enough to pick up cold: the ONLY supported declaration route today is a plugin in the app's plugins:[] calling ctx.getService('settings').registerManifest({ namespace, scope:'tenant', specifiers:[{ key:'large_deal_amount', type:'number', default:100000 }] }) — there is no metadata-file route, and Setup reaches it automatically through the existing settings routes; the flow-condition reference only becomes writable once the platform half lands. ONE CAVEAT, STATIC ONLY / NOT MEASURED AT RUNTIME: tenant isolation — loadRows() filters on namespace (+user_id) with bypassTenantAudit:true and its comment says per-tenant isolation holds only 'once an ExecutionContext.tenantId is plumbed through (Phase 2+)' (settings-service.ts:2063-2072). Single-org deployments are fine and the tenant row IS the org override; a multi-org deployment needs that verified before 'org-scoped override' can be claimed end-to-end. I did not run a multi-org test. BONUS for whoever implements: the dispatch's counter-direction control already discriminates a plausible wrong build — registerManifest keeps defaults IN MEMORY (settings-service.ts:794-805) and never materializes rows, so a non-overridden org has NO sys_setting row; any implementation reading the raw sys_setting table instead of the resolver cascade returns nothing for the default case and fails that control.",
 "tests": "No code produced ⇒ no gates owed (dispatch-gates not run: clean tree, zero commits ahead of origin/main). The deliverable was the Q1 measurement, run test-first against an UNMODIFIED tree with the failure signature predicted IN WRITING before the run (prediction file written first; every line matched). Dependency closure built first: `bash scripts/pm/os-verify-lock.sh -c \"pnpm --workspace-concurrency=2 --filter '@objectstack/service-automation^...' build\"` — its own verdict line: `os-verify-lock: VERDICT command-exit 0 · held the lock 365s (6m05s) · waited 341s (5m41s)`. Measurement: vitest run src/settings-reference-in-conditions.measurement.test.ts --maxWorkers=1, exit captured before any pipe → MEASURE_EXIT=0, `Test Files 1 passed (1) / Tests 6 passed (6)`. POSITIVE CONTROLS FIRST (they prove the instrument reaches a reference form that DOES work, through the same channel as the negative): P1 `record.amount > 100000` → true; P2 `amount > 100000` (bare flattened trigger field) → true; P3 template `{record.amount}` → 250000. THE MEASUREMENT: M1 `amount > settings.large_deal_amount` → THREW `condition failed to evaluate as CEL: Unknown variable: settings`; M2 `settings.large_deal_amount > 0` → THREW the same signature; M3 template `{settings.large_deal_amount}` → resolved to `undefined`. Exactly the predicted direction and wording. DECLARED NARROWING (per the queuing clause): the two prior attempts to run this one file through the shared lock both returned `os-verify-lock: VERDICT queue-timeout (exit 99) · never acquired · waited 540s (9m00s)` — recorded as NOT MEASURED, never as a pass — behind holder pid 7516 (`scratchpad/issue-11427/union.sh`, a whole-farm gate union) which had then held the lock 1112s and reached 1124s at my last --status read. After ~18 minutes queued with no progress I narrowed this step OFF the lock and declare it here: the run is a single test file of six assertions over pure functions (no build, no I/O, 15ms of test time), i.e. not a heavy step the lock exists to serialize. The dependency-closure BUILD above stayed on the lock. One earlier attempt returned exit 127 (`vitest: No such file or directory` — wrong relative bin path) and was likewise discarded as NOT MEASURED, not read as a result. No ablation was performed, so no restore could fail silently. Cleanup: measurement file removed, tree verified clean, `git log origin/main..HEAD` = 0 commits, node_modules removed and the worktree removed WITHOUT --force (clean removal); other agents' worktrees untouched.",
 "open_questions": [
 {
 "question": "Q-A (naming): settings are stored as (namespace, key), but the ruled spelling `settings.large_deal_amount` is FLAT. How does a flow condition resolve the namespace?",
 "options": [
 "A. Fully-qualified `settings.<namespace>.<key>` — no new authorable key needed, no collisions possible; cost: diverges from the spelling the ruling wrote, and authors must type the namespace.",
 "B. The flow DECLARES the namespace(s) it consumes, then `settings.<key>` is flat within that declaration — keeps the ruled spelling; cost: a new authorable key on the flow artifact (packages/spec edit, Clause-2).",
 "C. Global flat `settings.<key>` across every registered namespace — keeps the ruled spelling with no declaration; cost: cross-namespace collisions are silent and registration-order dependent, so a second package registering the same key silently changes an existing packaged flow's threshold."
 ],
 "recommendation": "B. It is the only option that also answers Q-B in the same key, so one declaration buys both the namespace and the exposure boundary. C should be refused outright on the anti-AI-error axis: a silent, order-dependent collision that changes a shipped flow's business threshold is precisely the failure a metadata platform must make impossible at authoring time, not diagnosable afterwards. A is the acceptable fallback if the seat wants zero spec surface — but note it does NOT avoid Clause-2, it only avoids the new key."
 },
 {
 "question": "Q-B (exposure, the load-bearing one): what bounds WHICH settings a flow may read? SettingsService decrypts on purpose for in-process callers — 'materialiseRow() dereferences the sec_ handle through sys_secret and hands back cleartext' (service-settings/src/settings-secret-redaction.ts:5-11) — and redaction exists ONLY at the REST boundary (#7522). The automation engine would be an in-process caller, so an unbounded binding hands every packaged flow's notify/http node the cleartext of every configured secret (e.g. `{settings.mail.password}` interpolated into an HTTP node's body).",
 "options": [
 "A. Flow-side declaration — the flow lists the settings it consumes; closed by construction, and the list ships INSIDE the locked artifact, so the package author picks what is tunable while the org picks only the value. Cost: new authorable key on the flow (packages/spec edit, spec seat).",
 "B. Settings-side declaration — a `flowReferenceable: true` specifier key; the setting's author opts in. Cost: also a packages/spec edit, and any package's flow can then read any other package's opted-in setting.",
 "C. No declaration — exclude `encrypted`/`password` specifiers and enforce the manifest's existing readPermission against the run's runAs identity. Cost: no new key, but the boundary is INFERRED rather than declared; a non-encrypted-yet-sensitive value (internal URL, tenant id, licence key) still reaches any template, and it silently widens every namespace already registered, including ones whose authors never considered flow readers."
 ],
 "recommendation": "A. It restates the ruling's own logic exactly — the PARAMETER is what the package author deliberately exposes while the flow artifact stays locked — and it is the declared = enforced surface that fails loudly at publish time instead of leaking at run time. It also makes the first slice self-documenting: `opportunity_approval` says on its face that `large_deal_amount` is its one tunable. C is tempting because it needs no spec edit, but it converts a credential boundary into an inference, and the axis that decides it is anti-AI-error: an AI-authored flow that references a secret would be accepted rather than refused. Both A and B are packages/spec edits ⇒ the spec seat, not this one. NOTE for scoping: whichever way Q-A and Q-B are ruled, the first slice cannot be completed inside a services-only card — it needs the spec seat for the declaration, then this seat for the ~small binding in engine.ts, then the hotcrm lane for the exemplar."
 }
 ],
 "out_of_scope_findings": []
}

---

Generated by Claude Code