feat(config): definePrebuilt and payload runtimeDependencies as AB7014 evidence (#619 step 4)

[ScriptedAlchemy]

Implements the definePrebuilt slice of #619 step 4 (Artifact IR records compile provenance). The manifest half of steps 4–5 — compile / dependencies rows on files[], producer.compiler, validateArtifact re-deriving AB6005 from the manifest — is deferred until #604 lands: it rewrites build/manifest.ts (+1303 lines), and every one of those edits would collide. This PR touches only config, normalization, validation, and the prepack gate, none of which #604 changes.

What changes

• src/core/types.ts: AgentBundlePayloadEntry.runtimeDependencies?: readonly string[] — the bare package names a prebuilt payload's files load at run time. definePrebuilt(entry) is the typed declaration site, exported from agent-bundle and agent-bundle/config beside defineConfig. NormalizedPayload.runtimeDependencies: readonly string[] (sorted, unique; [] for string-form declarations).
• src/config/validate.ts: validatePayload judges the list. Not an array of nonempty strings → AB4740 (the existing malformed-entry code). New AB4751 (error): an entry is not a bare package name as npm reads one (isBarePackageName, npm-package-arg: sharp/lib, sharp@1, paths, schemes fail; legacy-cased names such as JSONStream pass), or package.json does not install it for a consumer — dependencies, optionalDependencies, or a peer not marked optional, the same installed set AB7014 judges. The declaration check is skipped when package.json is absent (silent) or one AB4009–AB4011 already report (unparsable, outside the root); both readers now share readPackageDocument.
• src/core/package-dependencies.ts (new leaf): declaredDependencies, DeclaredDependency, installedDependencyFields, isBarePackageName — moved out of build/pack-dependencies.ts so agent-bundle/config and every validate() call never load the packed-file scanners (acorn, es-module-lexer's eager wasm compile). pack-inventory.ts and the tests import from the leaf.
• src/core/project-context.ts: readPackageDocument(root) — the one package.json reader (absent | document | issue), with the outside-root symlink rule; snapshotPackageIdentity is now a consumer of it, behaviour unchanged.
• src/build/pack-inventory.ts: AB7014 treats a name any payload's runtimeDependencies declares as used — the production consumer of the new field. Message and recovery name the new evidence class.
• Docs: docs/diagnostics.md (AB4740–AB4751 family row and section, AB4751 row, AB7014 row), docs/entry-conventions.md (payload sample uses definePrebuilt; "Declare what the payload loads" bullet), website/docs/{en,zh}/guide/authoring/package-entries.mdx, guide/authoring/index.mdx, guide/distribution/validation.mdx. One minor changeset.

Deviation from the #619 design comment: the design wrote definePrebuilt({ path, … }); the existing payload entry key is source, so definePrebuilt takes and returns AgentBundlePayloadEntry unchanged ({ source, targets?, runtimeDependencies? }) rather than introducing a second name for the same field.

Why this is #619 work: the compiler never opens a payload file (payload trees are opaque by contract), so a package.json dependency the payload loads has no compiler evidence. The author declares it; the validator judges the declaration against package.json and the prepack gate consumes it. No JavaScript is parsed to reach either verdict. PR 3 replaces the remaining token-scanner evidence classes in AB7014 with compiler evidence + these declarations; the "opaque prebuilt remains opaque" bullet from the #619 test list is proven here (prebuilt-payload.test.ts, prepack.test.ts).

Tests

• prebuilt-payload.test.ts: definePrebuilt export/identity from both entry points; declared list validates clean and normalizes sorted+unique; AB4751 for a subpath, an undeclared name, an optional peer; optionalDependencies and a required peer accepted with no AB474x/AB475x at all; AB4740 for a string and for ['']; string-form declaration normalizes to [].
• pack-dependencies.test.ts: isBarePackageName accepts sharp, @scope/name, JSONStream; rejects subpaths, selectors, paths, schemes, aliases, invalid names.
• prepack.test.ts: AB7014 names never-loaded but not sharp when a payload declares runtimeDependencies: ['sharp']; message and recovery carry the new clause.

Verification

Run on the merged tree (origin/main at 02b8972):

• pnpm build && pnpm typecheck && pnpm lint — build ok (publint passed); typecheck ok; lint 1364 files, 88 rules.
• pnpm test:unit — 4149 passed, 0 failed. pnpm test:integration:run — 1164 passed, 0 failed (prebuilt-payload.test.ts 14, prepack.test.ts 59, pack-dependencies.test.ts incl. the new bareness case).
• pnpm docs:site:build — typecheck, build, dead-link (0 broken / 26979 anchors), and language-parity checks pass.
• Reachability: core/package-dependencies.ts ← config/validate.ts, build/pack-inventory.ts; readPackageDocument ← snapshotPackageIdentity, validate.ts; definePrebuilt ← src/index.ts, src/config/index.ts; NormalizedPayload.runtimeDependencies ← pack-inventory.ts (AB7014).
• npm-package-arg probe (packages/agent-bundle, v14.0.0): sharp/JSONStream/@scope/name → range, rawSpec '*', name === text; sharp/lib → git; @scope/name/sub, ./x, @scope/ → directory; sharp@1 → range with name 'sharp'; node:fs, bad name → throw; npm:foo → alias.

Deslop: gpt-5.6-sol-medium, 8 edits (condensed changeset and doc prose that repeated one sentence three ways, removed a comment restating a property name, direct toBe identity assertions, dropped an unused it.each description column; no behaviour change).

Self-review

Pass 1 — claude-fable-5-1-thinking-high on the deslopped diff. Findings and disposition:

1. Should-fix — config/validate.ts importing build/pack-dependencies.ts made agent-bundle/config bundle acorn, es-module-lexer (eager WebAssembly.compile at module evaluation), and npm-package-arg. Fixed: the dependency grammar moved to the leaf core/package-dependencies.ts (the config/conventional-entry.ts pattern); pack-dependencies.ts no longer owns or re-exports it.
2. Should-fix — a second package.json reader with different semantics from snapshotPackageIdentity (the identity path ignores a package.json symlinked outside the root; the new one followed it). Fixed: readPackageDocument in core/project-context.ts is the one reader; both derive from it.
3. Should-fix — isValidPackageName is the new-package grammar (lowercase), so a legacy dependency such as JSONStream could be flagged by AB7014 and its only remedy rejected by AB4751. Fixed: isBarePackageName uses npm-package-arg (the parser AB7015 already uses): bare iff type === 'range', rawSpec === '*', name === text.
4. Nit — peers excluded from AB4751 while AB7014 suppression counted them. Fixed by aligning to the installed set (dependencies, optionalDependencies, non-optional peers); message, docs (en/zh), and tests updated.
5. Nit — docs said a missing package.json is AB4009–AB4011; it is silent. Fixed: "missing (silent) or unparsable (AB4009–AB4011)" in entry-conventions.md, package-entries.mdx en/zh, diagnostics.md.
6. Nit — website validation.mdx evidence paragraph (en/zh) lacked the runtimeDependencies clause docs/diagnostics.md gained. Fixed in both locales.
7. Nit — two accept tests asserted only "no AB4751", which an earlier AB474x would have satisfied vacuously. Fixed: they assert no AB474x/AB475x at all.

Pass 2 — gpt-5.6-sol-medium on the fixed diff: four findings.

1. Should-fix — changeset bump and wording. Wording fixed ("a name npm does not read as a bare package name or one package.json does not install for a consumer (dependencies, optionalDependencies, or a peer not marked optional)"). Bump kept at minor: the owner's plan names one minor changeset per Compiler evidence: prove self-containment from the Rspack module graph and Artifact IR; delete the generated-JS load scanners (replaces #591/#602) #619 PR, and NormalizedPayload (an exported type) gains a required field — pre-1.0 that is the breaking bump AGENTS.md defines; pass 1 reached the same conclusion.
2. Should-fix — docs cited AB4009–AB4011 for the skipped declaration check, but only AB4011 (unparsable, outside the root) describes those states. Fixed in diagnostics.md, entry-conventions.md, package-entries.mdx en/zh, and the validate.ts comment.
3. Should-fix — the primary accept test asserted only "no AB4751". Fixed: asserts no AB474x/AB475x.
4. Nit — AB4751 recovery omitted required peers. Fixed.

Pass 3 — claude-fable-5-1-thinking-high (confirmation of the pass-2 fixes): one should-fix, one nit.

1. Should-fix — the accept tests' "no AB474x/AB475x" filter also matched the AB4750 freshness nudge, which validate emits when a fixture's package.json lands in a later mtime tick than the payload files — an intermittent failure. Fixed: the filter is /^AB474\d$|^AB4751$/u (verdicts only; the nudge is informational).
2. Nit — three doc sentences omitted the outside-the-root case readPackageDocument also skips. Fixed in entry-conventions.md and package-entries.mdx en/zh.

Also in this round: installedDependencyFields un-exported (no importer). Confirmed clean by the pass: no AB4009 tied to AB4751; recovery text matches installedDependencyNames; changeset well-formed; leaf module has no cycle; NormalizedPayload has one production constructor.

[changeset-bot]

🦋 Changeset detected

Latest commit: eb85acd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
agent-bundle	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle@630

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@630

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/rsc-markdown-stream@630

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/@agent-bundle/runtime@630

commit: eb85acd

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.