Skip to content

Commit cc10e74

Browse files
feat(spec,lint): resolve action → flow and widget → dataset references against the release artifact (#25617)
Fixes #25514 Clause-②: yes (widening) Metadata-protocol: added Ruling-ref: 6377677280 ## What One release artifact carries several packages (ADR-0130 D4). Two per-package checks judged a reference against one package, so they refused a target that a sibling package of the same artifact provides: 1. **`packages/spec`, defect 1.** `validateCrossReferences` built its flow scope from the stack's own `flows` alone. A `type: 'flow'` action whose `target` names a sibling package's flow was refused with "which is not defined in flows." This applied in all three positions: top-level `actions[]`, `objects[].actions[]`, and inline page actions. 2. **`packages/lint`, defect 2.** `widget-dataset-unknown` (`validateWidgetBindings`) built its `datasets` map from `stack.datasets` alone. It ignored the `packages[]` resolution context that the CLI's per-package pass already supplies. Following ruling 6377677280 (option A), both reference classes now resolve against the **artifact**. A flow or dataset that **no** package of the artifact defines stays refused, exactly as before. Scope is same-artifact only. Cross-artifact resolution is #25403's ADR and is not touched here. ## Contract (public-surface widening) - **New `DefineStackOptions.artifactFlows?: readonly string[]`** (`packages/spec/src/stack.zod.ts`). It lists the flow names the other packages of the artifact provide. A flow action's target resolves against own `flows` ∪ these names. It mirrors `artifactObjects`. - It **widens** a check that already runs and never switches one on. A stack with no flows of its own keeps the plugin leniency (`flowNames.size === 0`), unchanged. - **Declared means enforced.** Every target that resolved *only* through the list is recorded on the stack `defineStack` returns. The record is a non-enumerable `Symbol.for('objectstack.stack.artifact-flow-claims')` property beside the provenance mark, so it is not a schema key and not in `dist/objectstack.json`. `composeStacks` step 3b (`collectArtifactFlowClaimErrors`) refuses the composition when no input defines a recorded target. The refusal uses the same `STACK_CROSS_REFERENCE_INVALID`/422 envelope and the byte-identical per-finding message. A flow is "defined by an input" when it is in that input's top-level `flows` or, for a nested multi-package artifact, in a `packages[].manifest.flows` body. - **Why a record and not the `artifactObjects` re-run.** Re-running the flow rule over every input at composition would also newly refuse a dangling target in an input built with `strict: false`. That is a narrowing this card does not declare. The record checks exactly the promise the option made. An input that did not opt in cannot newly fail at composition, strict or not. That case is pinned. - Boundary, the same as `artifactObjects`: a one-package composition, or a stack that is never composed, leaves the claim unverified. - **`widget-dataset-unknown`** reads `packagesOf(stack)` (the existing `packages/lint` reader) and adds each body's `datasets` to the map, the way `validate-object-references.ts` widens rung ① with `artifactProvidedObjectNames`. This is resolution context only. Dataset-level checks (`measure-aggregate-incoherent`) still walk `stack.datasets` alone, and the stack's own declaration wins a shared name. **`packages/cli` is untouched**: `packageBodyAsStack` already passes `packages[]`. - **Runtime publish gate (`packages/metadata-protocol/src/runtime-authoring-gate.ts`): neither widened nor broken.** Its judged stack never carries `packages` (no `packages` key in `runtime-gate.ts` / `runtime-authoring-gate.ts`), so `packagesOf` answers `[]` and the rule behaves exactly as before. Its tests are green (below). ## Booted measurement (ruling note 2) I boot-tested a temporary (uncommitted) extension of `examples/app-multi-package`: - **`orders`** (`type: module`) ships the flow `crm_order_stamp` (start → `create_record` on `crm_order` → end) and the dataset `crm_order_metrics`. - **`core`** (`type: app`) has its own flow `crm_core_noop`, so the flow check runs at all. It has `crm_account.actions[stamp_orders] → type 'flow', target 'crm_order_stamp'`, a dashboard widget `order_totals` bound to `crm_order_metrics`, and `defineStack(..., { artifactFlows: ['crm_order_stamp'] })`. Its `requires` is `['automation']`. ```text $ PROBE_NO_CLAIM=1 objectstack validate # option omitted: today's behaviour ✗ Action 'stamp_orders' on object 'crm_account' references flow 'crm_order_stamp' which is not defined in flows. exit 1 $ objectstack validate # with artifactFlows → Running author-time rules per package (2)... ✓ Validation passed exit 0 $ objectstack build → dist/objectstack.json packages[]: com.example.multi.orders {"flows":["crm_order_stamp"],"datasets":["crm_order_metrics"],"dashboards":[],"actions":[]} com.example.multi.core {"flows":["crm_core_noop"],"datasets":[],"dashboards":["crm_overview→crm_order_metrics"],"actions":["crm_account.stamp_orders→crm_order_stamp"]} $ objectstack dev --fresh -p 38517 # AutomationServicePlugin + AnalyticsServicePlugin up GET /api/v1/data/crm_order → {"records":[],"total":0} POST /api/v1/actions/crm_account/stamp_orders/W79i9VpR-IiyJjlz → HTTP 200 {"success":true,"data":{"success":true,"flowLabel":"Stamp Order","summary":{"acted":1,"nodes":[{"nodeId":"start","status":"success"},{"nodeId":"create_probe_order","nodeType":"create_record","status":"success","acted":1}]}}} GET /api/v1/data/crm_order → 1 record: {"name":"flow-started-from-core-action","amount":42} GET /api/v1/meta/dashboard/crm_overview → widget {"id":"order_totals","dataset":"crm_order_metrics"}, packageId com.example.multi.core POST /api/v1/analytics/dataset/query {"datasetName":"crm_order_metrics","selection":{"measures":["order_count","order_amount"],"dimensions":["name"]}} → HTTP 200 {"rows":[{"name":"flow-started-from-core-action","order_count":1,"order_amount":42},{"name":"manual-order","order_count":1,"order_amount":8}],"object":"crm_order", "sql":"SELECT name AS \"name\", COUNT(*) …, SUM(amount) … FROM \"crm_order\" GROUP BY name"} ``` So the app package's action starts the module package's flow, and the app package's widget's dataset (owned by the module) returns its rows. The server was stopped by its recorded PID, and the probe edits were restored (`git status` clean). ## Tests - New `packages/spec/src/stack-artifact-flow-crossref.test.ts` (9): both directions per class across all three positions. A sibling flow is accepted at `defineStack` and at `composeStacks`. An unlisted flow is refused at `defineStack`. A claimed flow that no input defines is refused at `composeStacks` with the per-stack message, envelope and header. A nested multi-package input resolves. Fences: no own flows means no check, a non-opted `strict: false` input cannot newly fail, and no new enumerable key is added. - New `packages/lint/src/validate-widget-bindings.artifact-datasets.test.ts` (6): a sibling dataset is accepted, a dataset no package declares is refused, the single-package answer is unchanged, a resolved sibling dataset's measures are judged, a sibling's dataset-level findings are not judged on this package's pass, and the rule table reaches the per-package pass. - **Ablations** (fix committed first; restored by `ablation-replace.mjs`, blob == HEAD, `git diff HEAD` empty): - spec `artifactFlows?.has(target)` → never matches: **5/9 red**. - spec `...collectArtifactFlowClaimErrors(stacks),` deleted: **1/9 red** (the compose-time refusal). - lint packages loop reads a non-key, then rebuilt (`ablation-dist-preflight` marker present in 4 dist files): **3/6 red**. The real door `objectstack validate` on the probe exits **1** with HotCRM's exact defect-2 line, `package 'com.example.multi.core' — dashboard "crm_overview" › widget "order_totals": dataset "crm_order_metrics" does not resolve to a declared dataset.` (rule `widget-dataset-unknown`). After the restore and rebuild (marker absent from all 20 dist files), the door exits 0 and 6/6 pass. - Package suites at `5cf84d58` (pre-merge): spec `pnpm test` 715 files / 21696 passed, `pnpm typecheck` 0; lint `pnpm test` 159 files / 7243 passed, `pnpm typecheck` 0. The CLI unit tier (`vitest run --project unit`) ran 327/327 files: 325 on the first run, plus `published-subpath-console` / `published-subpath-hook-body`, which needed `packages/cli` itself built and then passed, 29/29. metadata-protocol `protocol.dashboard-dataset-publish-gate`, `protocol.runtime-gate-stored-universe` and `protocol-publish-drafts-closure` ran 3 files / 24 passed. The CLI integration tier is left to CI; the diff touches no integration-tier file. - After merging `origin/main` (`e649c2d91e`, the Version Packages commit) at head `45b786764e`: spec build plus `check:generated` show all 14 generated artifacts up to date. Spec flow and artifact cross-ref tests: 39 passed. Lint build plus both widget-binding test files: 184 passed. ## Gates `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` derived 113 commands, with an identical derivation on `45b786764e`. All 113 exit 0. Four first returned PREREQUISITE NOT MET (exit 3) or hit my own runner timeout, and passed once the prerequisite was met: - `check-plugin-teardown-shape --self-test`: shallow clone, fixed with `git fetch --unshallow`. - `spec check:skill-examples` and `check:dual-build-cjs-loads`: unbuilt sibling `dist/`, fixed by building those packages. - `check:type-check-debt`: my 420 s cap; rerun uncapped, it exits 0. `--ran` reconciliation: 113 derived, 113 run, 0 NOT-MEASURED (a derived zero: every line carries its exit code). Re-run on `45b786764e`: the `--base origin/main` changeset gates, `check:type-check-coverage`, `check:nul-bytes`, `check:doc-authoring`, `check:issue-citations` and spec `check:api-surface` all exit 0. Local-only families also exit 0: `check:dev-prereqs` and `check:skill-frame-freshness`. Dogfood battery: n/a (no `!` in the title, no `(narrowing)` arm). ## Acceptance notes - The card's HotCRM acceptance rows (hotcrm#2270's patch validating unchanged, and `top_products` returning 4 rows) need a **released** `@objectstack/*` carrying this. They are measured downstream, not here. HotCRM must add `artifactFlows` to its app package's `defineStack` call. The dataset half needs no HotCRM change. - The release is in progress: this PR stays **draft**. It is not to be readied, queued or merged until the maintainer lifts that. - `content/docs/getting-started/examples.mdx` gains one bullet beside the existing `artifactObjects` paragraph. --- _Generated by [Claude Code](https://claude.ai/code/session_011SU6BLnw3XLU8nKfnWMYVG)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 481ac62 commit cc10e74

6 files changed

Lines changed: 523 additions & 16 deletions

File tree

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
'@objectstack/spec': minor
3+
'@objectstack/lint': minor
4+
---
5+
6+
feat: a package's action can launch a flow, and its dashboard widget can bind a dataset, that another package of the same release artifact ships
7+
8+
Clause-②: yes (widening)
9+
Metadata-protocol: added
10+
11+
One release artifact carries several packages (ADR-0130 D4). Two per-package checks judged a reference against one package and refused a target a sibling package provides. The artifact carries the target, and the runtime serves it.
12+
13+
- **`@objectstack/spec`: `defineStack(config, { artifactFlows })`.** This new `DefineStackOptions` key lists flow names that the other packages of the artifact provide. A `type: 'flow'` action's `target` resolves against the stack's own `flows` plus these names. That covers a top-level action, an action authored on an object, and an inline page action. It works the way `artifactObjects` already does for permission grants and seed rows.
14+
- The option widens a check that already runs. A stack that declares no flows of its own still leaves its flow targets unresolved (a plugin may serve them).
15+
- `defineStack` records every target that resolved only through the list, as a non-enumerable mark on the stack it returns. `composeStacks` refuses the composition when no input defines that flow. The refusal uses the same `STACK_CROSS_REFERENCE_INVALID` envelope and the same per-finding message as the per-stack pass. An input that did not opt in cannot newly fail at composition.
16+
- A flow that no package of the artifact defines is refused, as before.
17+
- **`@objectstack/lint`: `widget-dataset-unknown`.** The rule resolves a widget's `dataset` against the datasets that every `packages[]` body declares, as well as the stack's own. This is the resolution context that `os build`, `os validate` and `os lint` already pass to each package's run. Dataset-level checks still judge only the package's own datasets. A dataset that no package declares is refused, as before. The runtime publish gate passes no `packages[]`, so its behaviour is unchanged.
18+
19+
Fix for a module split such as HotCRM's: in the app package, write `defineStack(appConfig, { artifactFlows: revenue.flows?.map((f) => f.name) })` and compose both packages with `composeStacks([...], { manifest: 'preserve' })`. A cross-package dataset binding needs no change.

‎content/docs/getting-started/examples.mdx‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -446,6 +446,15 @@ The rules worth knowing before you split a product this way:
446446
stack untouched, so composing one package on its own does not check the claim.
447447
Hooks are the deliberate exception: a hook still belongs to the package that
448448
owns its object.
449+
- **Actions may launch a sibling package's flow; dashboards may bind its dataset.**
450+
A `type: 'flow'` action resolves its `target` against the artifact once you
451+
hand `defineStack` the sibling flow names:
452+
`defineStack(appConfig, { artifactFlows: ordersStack.flows?.map((f) => f.name) })`.
453+
The claim is checked the same way: in a composition of two or more packages,
454+
`composeStacks` refuses a claimed flow that no package defines. A dashboard
455+
widget's `dataset` needs no option. `os build`, `os validate` and `os lint`
456+
resolve it against every package of the artifact, and still refuse a dataset
457+
that no package declares.
449458
- **One artifact, one version.** Everything inside ships, installs and upgrades
450459
together; you cannot hot-fix one module on its own. A module that needs its
451460
own release cadence belongs in its own artifact.
Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* #25514 — `widget-dataset-unknown` resolves a widget's `dataset` against the
5+
* ARTIFACT's `packages[]`, not the one package body it judges.
6+
*
7+
* The CLI's per-package pass (`runPerPackageAuthoringRules`) hands each rule
8+
* one package body re-read as a stack, with the artifact's `packages[]` as
9+
* resolution context (`packageBodyAsStack`). An app-package dashboard binding a
10+
* dataset a module package owns was refused there — measured on HotCRM's
11+
* module split as `dataset "product_metrics" does not resolve to a declared
12+
* dataset.` while the composed artifact carried the dataset.
13+
*
14+
* Both directions are pinned: a sibling-provided dataset is accepted (and its
15+
* dimensions / measures are then judged like a local one), and a name no
16+
* package provides is refused exactly as before.
17+
*/
18+
import { describe, it, expect } from 'vitest';
19+
import { runAuthoringRules } from './authoring-rules.js';
20+
import { validateWidgetBindings, WIDGET_DATASET_UNKNOWN, WIDGET_MEASURE_UNKNOWN } from './validate-widget-bindings.js';
21+
22+
const revenueBody = {
23+
id: 'app.objectstack.hotcrm.revenue',
24+
name: 'revenue',
25+
objects: [{ name: 'crm_product', fields: { name: { type: 'text' }, price: { type: 'currency' } } }],
26+
datasets: [{
27+
name: 'product_metrics',
28+
label: 'Product metrics',
29+
object: 'crm_product',
30+
measures: [{ name: 'product_count', label: 'Products', aggregate: 'count' }],
31+
dimensions: [{ name: 'name', field: 'name' }],
32+
}],
33+
};
34+
35+
const appBody = (dataset: string, values: string[] = ['product_count']) => ({
36+
id: 'app.objectstack.hotcrm',
37+
name: 'hotcrm',
38+
dashboards: [{
39+
name: 'crm_overview_dashboard',
40+
label: 'CRM Overview',
41+
widgets: [{
42+
id: 'top_products',
43+
type: 'table',
44+
dataset,
45+
dimensions: ['name'],
46+
values,
47+
layout: { x: 0, y: 0, w: 6, h: 4 },
48+
}],
49+
}],
50+
});
51+
52+
/** `packageBodyAsStack`'s shape: the body, its own manifest, the artifact's entries. */
53+
const asPackageStack = (body: Record<string, unknown>, siblings: Record<string, unknown>[]) => ({
54+
...body,
55+
manifest: body,
56+
packages: [body, ...siblings].map((manifest) => ({ manifest })),
57+
});
58+
59+
const datasetUnknown = (stack: Record<string, unknown>) =>
60+
validateWidgetBindings(stack).filter((f) => f.rule === WIDGET_DATASET_UNKNOWN);
61+
62+
describe('widget-dataset-unknown — the artifact resolves a sibling package’s dataset', () => {
63+
it('ACCEPTS an app widget bound to a dataset the module package owns', () => {
64+
expect(datasetUnknown(asPackageStack(appBody('product_metrics'), [revenueBody]))).toEqual([]);
65+
});
66+
67+
it('still REFUSES a dataset NO package of the artifact declares', () => {
68+
const findings = datasetUnknown(asPackageStack(appBody('product_nowhere'), [revenueBody]));
69+
expect(findings).toHaveLength(1);
70+
expect(findings[0]).toMatchObject({
71+
severity: 'error',
72+
where: 'dashboard "crm_overview_dashboard" › widget "top_products"',
73+
});
74+
});
75+
76+
it('REFUSES the sibling dataset when judged WITHOUT the artifact — the unchanged single-package answer', () => {
77+
expect(datasetUnknown(appBody('product_metrics'))).toHaveLength(1);
78+
});
79+
80+
it('judges the resolved sibling dataset’s measures like a local one', () => {
81+
const findings = validateWidgetBindings(asPackageStack(appBody('product_metrics', ['revenue_sum']), [revenueBody]));
82+
expect(findings.map((f) => f.rule)).toContain(WIDGET_MEASURE_UNKNOWN);
83+
});
84+
85+
it('does not judge a sibling’s dataset-level conditions on this package’s pass', () => {
86+
const incoherent = {
87+
...revenueBody,
88+
datasets: [{
89+
...revenueBody.datasets[0],
90+
measures: [{ name: 'price_total', label: 'Total', aggregate: 'sum', field: 'price' }],
91+
}],
92+
};
93+
const findings = validateWidgetBindings(asPackageStack(appBody('product_metrics', ['price_total']), [incoherent]));
94+
expect(findings.filter((f) => f.path.startsWith('datasets['))).toEqual([]);
95+
});
96+
97+
it('reaches the rule table the per-package pass runs', () => {
98+
const stack = asPackageStack(appBody('product_metrics'), [revenueBody]);
99+
const findings = runAuthoringRules('validate', { normalized: stack, parsed: stack });
100+
expect(findings.filter((f) => f.rule === WIDGET_DATASET_UNKNOWN)).toEqual([]);
101+
const dangling = asPackageStack(appBody('product_nowhere'), [revenueBody]);
102+
expect(
103+
runAuthoringRules('validate', { normalized: dangling, parsed: dangling }).filter((f) => f.rule === WIDGET_DATASET_UNKNOWN),
104+
).toHaveLength(1);
105+
});
106+
});

‎packages/lint/src/validate-widget-bindings.ts‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import {
99
indexObjectGraph,
1010
isUnjudgeable,
1111
joinablePrefixes,
12+
packagesOf,
1213
recordsOf,
1314
resolveFieldPath,
1415
suggestName,
@@ -691,6 +692,23 @@ export function validateWidgetBindings(stack: AnyRec): WidgetBindingFinding[] {
691692
for (const ds of recordsOf(stack.datasets)) {
692693
if (typeof ds.name === 'string') datasets.set(ds.name, ds);
693694
}
695+
// [#25514] A widget's `dataset` resolves against the ARTIFACT: the datasets
696+
// every `packages[]` body declares join the map as RESOLUTION CONTEXT, the way
697+
// `validate-object-references.ts` widens rung ① with the artifact's objects.
698+
// A cross-domain dashboard in the app package reads a module's dataset (the
699+
// ADR-0130 plan rule "multi-module dashboards move to the app package"), and
700+
// the runtime serves every package's datasets from one analytics service.
701+
// ⛔ It changes what a widget can RESOLVE, never what is JUDGED: the
702+
// dataset-level checks below still walk `stack.datasets` alone, and a name no
703+
// package declares still resolves nowhere. The stack's own declaration wins a
704+
// name it shares with a body — on the per-package pass that body IS this one.
705+
for (const entry of packagesOf(stack)) {
706+
const body = entry.manifest;
707+
if (!body || typeof body !== 'object' || Array.isArray(body)) continue;
708+
for (const ds of recordsOf((body as AnyRec).datasets)) {
709+
if (typeof ds.name === 'string' && !datasets.has(ds.name)) datasets.set(ds.name, ds);
710+
}
711+
}
694712

695713
// ── (0) dataset measures aggregate their field coherently ──
696714
// A measure that SUMs a percentage/rate field produces a meaningless total
Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* #25514 — a `type: 'flow'` action's target resolves against the ARTIFACT once
5+
* the stack declares its siblings' flows (`DefineStackOptions.artifactFlows`),
6+
* and a flow NO package of the artifact defines stays refused.
7+
*
8+
* ## The defect
9+
*
10+
* `validateCrossReferences` built its flow scope from the stack's own `flows`
11+
* alone, so a sales action on an app-owned object launching a flow that a
12+
* module package of the SAME artifact ships was refused at `defineStack` —
13+
* measured downstream on HotCRM's module split as three "which is not defined
14+
* in flows." refusals, while the composed artifact carried all three flows.
15+
*
16+
* ## The two directions this file pins, per position
17+
*
18+
* - a sibling-provided flow is ACCEPTED at `defineStack` and at `composeStacks`;
19+
* - a flow no package provides is REFUSED — at `defineStack` when it is not
20+
* claimed, and at `composeStacks` (the artifact pass) when it is claimed but
21+
* no input defines it, with the per-stack pass's own message.
22+
*
23+
* Plus the fences: the option never switches the check on for a stack with no
24+
* flows of its own, and an input that did not opt in cannot newly fail at
25+
* composition even when it bypassed the strict parse.
26+
*/
27+
import { describe, it, expect } from 'vitest';
28+
import { composeStacks, defineStack } from './stack.zod';
29+
30+
const appManifest = {
31+
id: 'app.objectstack.hotcrm',
32+
name: 'HotCRM',
33+
version: '3.1.0',
34+
type: 'app' as const,
35+
namespace: 'crm',
36+
};
37+
38+
const moduleManifest = {
39+
id: 'app.objectstack.hotcrm.revenue',
40+
name: 'HotCRM Revenue',
41+
version: '3.1.0',
42+
type: 'module' as const,
43+
namespace: 'crm',
44+
dependencies: { 'app.objectstack.hotcrm': '^3.1.0' },
45+
};
46+
47+
const flow = (name: string) => ({ name, label: name, type: 'autolaunched' as const, nodes: [], edges: [] });
48+
49+
/** Owned by the module package — the flow every cross-package action launches. */
50+
const SIBLING = 'quote_generation';
51+
/** The flow NO package in the artifact defines. */
52+
const NOWHERE = 'quote_nowhere';
53+
54+
const account = { name: 'crm_account', label: 'Account', fields: { title: { type: 'text' as const } } };
55+
const quote = { name: 'crm_quote', label: 'Quote', fields: { title: { type: 'text' as const } } };
56+
57+
type Envelope = Error & { code?: string; status?: number; issues?: readonly string[] };
58+
59+
function refusalOf(run: () => unknown): Envelope | null {
60+
try {
61+
run();
62+
return null;
63+
} catch (e) {
64+
return e as Envelope;
65+
}
66+
}
67+
68+
const anyStack = (config: Record<string, unknown>) => config as unknown as Parameters<typeof defineStack>[0];
69+
70+
/** The module package: owns `crm_quote` and the flow. */
71+
const revenueStack = () =>
72+
defineStack(anyStack({ manifest: moduleManifest, objects: [quote], flows: [flow(SIBLING)] }));
73+
74+
/**
75+
* The app package: owns `crm_account` and a flow of its own (so the per-stack
76+
* flow check runs at all), and launches `target` from all three positions.
77+
*/
78+
const appConfig = (target: string, ownFlows = [flow('crm_local_flow')]) => anyStack({
79+
manifest: appManifest,
80+
objects: [
81+
{
82+
...account,
83+
actions: [{ name: 'quote_from_account', label: 'Quote', type: 'flow', target }],
84+
},
85+
],
86+
flows: ownFlows,
87+
actions: [{ name: 'generate_quote', label: 'Generate Quote', type: 'flow', target }],
88+
pages: [
89+
{
90+
name: 'crm_home',
91+
label: 'Home',
92+
type: 'home',
93+
regions: [
94+
{
95+
name: 'main',
96+
components: [
97+
{
98+
type: 'element:button',
99+
properties: { label: 'Go', action: { name: 'inline_quote', type: 'flow', target } },
100+
},
101+
],
102+
},
103+
],
104+
},
105+
],
106+
});
107+
108+
const messages = (target: string) => [
109+
`Action 'generate_quote' references flow '${target}' which is not defined in flows.`,
110+
`Action 'quote_from_account' on object 'crm_account' references flow '${target}' which is not defined in flows.`,
111+
`Inline action 'inline_quote' on page 'crm_home' (regions.0.components.0) references flow '${target}' which is not defined in flows.`,
112+
];
113+
114+
describe('the per-stack pass, without the opt-in — unchanged', () => {
115+
it('REFUSES the sibling-provided flow from all three positions — the reported defect', () => {
116+
const refused = refusalOf(() => defineStack(appConfig(SIBLING)));
117+
expect(refused?.code).toBe('STACK_CROSS_REFERENCE_INVALID');
118+
expect(refused?.status).toBe(422);
119+
expect(refused?.issues).toEqual(messages(SIBLING));
120+
});
121+
});
122+
123+
describe('`artifactFlows` resolves a sibling package’s flow', () => {
124+
it('ACCEPTS all three positions at `defineStack`', () => {
125+
const revenue = revenueStack();
126+
expect(
127+
refusalOf(() => defineStack(appConfig(SIBLING), { artifactFlows: (revenue.flows ?? []).map((f) => f.name) })),
128+
).toBeNull();
129+
});
130+
131+
it('ACCEPTS the composed artifact — the claim is redeemed by the sibling', () => {
132+
const app = defineStack(appConfig(SIBLING), { artifactFlows: [SIBLING] });
133+
expect(refusalOf(() => composeStacks([revenueStack(), app], { manifest: 'preserve' }))).toBeNull();
134+
});
135+
136+
it('keeps refusing a name it does NOT list, beside one it does', () => {
137+
const refused = refusalOf(() => defineStack(appConfig(NOWHERE), { artifactFlows: [SIBLING] }));
138+
expect(refused?.code).toBe('STACK_CROSS_REFERENCE_INVALID');
139+
expect(refused?.issues).toEqual(messages(NOWHERE));
140+
});
141+
});
142+
143+
describe('the ARTIFACT pass: a claimed flow NO package defines is refused', () => {
144+
const composeClaiming = (name: string) => {
145+
const app = defineStack(appConfig(name), { artifactFlows: [name] });
146+
return refusalOf(() => composeStacks([revenueStack(), app], { manifest: 'preserve' }));
147+
};
148+
149+
it('REFUSES every position with the per-stack pass’s own message and envelope', () => {
150+
const refused = composeClaiming(NOWHERE);
151+
expect(refused?.code).toBe('STACK_CROSS_REFERENCE_INVALID');
152+
expect(refused?.status).toBe(422);
153+
expect(refused?.issues).toEqual(messages(NOWHERE));
154+
expect(refused?.message).toContain('composeStacks artifact cross-reference validation failed');
155+
});
156+
157+
it('resolves against a nested multi-package input, whose flows live only in its package bodies', () => {
158+
const inner = composeStacks(
159+
[revenueStack(), defineStack(anyStack({ manifest: { ...moduleManifest, id: 'x.other' }, objects: [] }))],
160+
{ manifest: 'preserve' },
161+
);
162+
const app = defineStack(appConfig(SIBLING), { artifactFlows: [SIBLING] });
163+
expect(refusalOf(() => composeStacks([inner, app], { manifest: 'preserve' }))).toBeNull();
164+
});
165+
});
166+
167+
describe('fences', () => {
168+
it('a stack with NO flows of its own keeps the plugin leniency — the option switches nothing on', () => {
169+
const app = defineStack(appConfig(NOWHERE, []), { artifactFlows: [SIBLING] });
170+
// No claim was relied on, so the composition has nothing to redeem.
171+
expect(refusalOf(() => composeStacks([revenueStack(), app], { manifest: 'preserve' }))).toBeNull();
172+
});
173+
174+
it('an input that did not opt in cannot newly fail at composition, even past `strict: false`', () => {
175+
const loose = defineStack(appConfig(NOWHERE), { strict: false });
176+
expect(refusalOf(() => composeStacks([revenueStack(), loose], { manifest: 'preserve' }))).toBeNull();
177+
});
178+
179+
it('the claim record is not data — the built stack carries no new enumerable key', () => {
180+
const app = defineStack(appConfig(SIBLING), { artifactFlows: [SIBLING] });
181+
expect(Object.keys(app)).toEqual(Object.keys(defineStack(appConfig('crm_local_flow'))));
182+
expect(JSON.stringify(app)).not.toContain('artifact-flow-claims');
183+
});
184+
});

0 commit comments

Comments
 (0)