Skip to content

feat: adopt bomly-sdk v0.16.0 -- transactional component calls and a shared component lifetime (#415, #416) - #532

Merged
bomly-guy merged 2 commits into
mainfrom
claude/component-runtime-adoption
Oct 25, 2026
Merged

bomly-guy merged 2 commits into
mainfrom
claude/component-runtime-adoption

Conversation

@bomly-guy

Copy link
Copy Markdown
Collaborator

Adopts bomly-sdk v0.16.0 and closes the runtime-correctness half of bomly-dev/bomly-planning#51.

Closes #415, closes #416. The prerequisite and disclosure half is #531, which is built on this branch's first commit and should merge after this one.

Transactional component calls (#416)

  • Snapshots: every matcher and analyzer Ready, Applicable and action call receives its own MatchRequest.Clone / AnalyzeRequest.Clone (SDK v0.15.0). No component holds the host's graph, registry or target.
  • Commit on success only: a returned Registry wins; otherwise PackageUpdates merge through model.ApplyPackageUpdates. A failed call commits nothing, and neither does a call that returns success after the command was cancelled (committable). Rollback is per call, so earlier successes stand.
  • Graph and target: changes a component makes to them are never committed, which matches what managed plugins already got.
  • Tests: TestEngineMatchCommitsOnlySuccessfulCalls and TestEngineAnalyzeCommitsOnlySuccessfulCalls run the same pipeline embedded and through a simulated wire that JSON round-trips each request and result, and require identical registries. Together with TestEngineMatchDiscardsWorkFinishedAfterCancellation they cover the acceptance list:
    • a matcher that mutates a package, its nested advisories and metadata, the graph and the target, then fails, leaves no trace;
    • earlier successes are kept;
    • a full registry wins over its own deltas;
    • updates are never applied twice;
    • cancellation commits nothing.
  • Verified the tests can fail: with the clones removed from engine.go, the tests report every class of leak.
  • Changed test: TestEngineMatchFiltersOccurrencesButPreservesGraphAndRegistry asserted that the matcher received the host's own registry pointer, which is the behavior engine: isolate component inputs and commit enrichment only on success #416 removes. It now asserts that matchers see the complete registry as a snapshot.

Component lifetime (#415)

  • Construction: embedded components are built under the command's context. Registry.BuildContext(ctx) is new; Build() stays for registries built only to read descriptors.
  • Scopes: each embedded component gets a plugin.ComponentScope, recorded before its constructor runs.
  • Teardown: Registry.Close ends every scope, newest first, with joined errors that name the component. It joins the command cleanup chain ahead of temp-dir cleanup on every exit path from PrepareForExecutionTarget.
  • Managed plugins: no RPC was needed. go-plugin's Kill closes the connection and gives the plugin a grace period before forcing it down, and SDK v0.15.0's ServeModule runs the component's cleanups in that window. ClientPool.Shutdown now shuts plugins down concurrently, so the command waits one grace period, not one per plugin. The one-restart limit is unchanged.
  • Tests: TestRegistryComponentLifetimeIsTheCommands covers the command context reaching constructors, cancellation not running cleanups, LIFO order, cleanup after a failed constructor, a named cleanup error, and an idempotent Close. TestClientPoolShutdownIsBoundedByOneGracePeriod covers four slow plugins including a dead one. TestJoinCleanupsRunsBothInOrder covers the cleanup chain. The real-transport managed cleanup is proven by bomly-sdk's conformance probe.

Also

Checks

make test, make build-lite, make lint (both tag sets, 0 issues) and make generate pass, plus -race on the registry and plugin packages.

🤖 Generated with Claude Code

bomly-guy and others added 2 commits October 25, 2026 00:37
…fetime scope

v0.15.0 added HostContext.OnCleanup. Each embedded component now gets a
plugin.ComponentScope that RegisterModule records before the
constructor runs, and Registry.Close ends them newest first with joined
errors. Threading the command context and closing the registry at
command end follow in this pull request.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… the command's lifetime (ADR-0050)

Every matcher and analyzer Ready, Applicable and action call receives
its own request clone, and only a successful action is committed: a
returned registry, otherwise its package updates. A failed call, or one
that returns after the command was cancelled, commits nothing, and
graph or target changes are never kept -- the semantics a managed
plugin already had because its request crosses the wire as a copy.

Embedded components are built under the command's context through
Registry.BuildContext, and Registry.Close joins the command cleanup
chain ahead of the temp-dir cleanup. The plugin pool shuts plugins down
concurrently, so go-plugin's graceful Kill costs one grace period, not
one per plugin.

Closes #415. Closes #416.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 25, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-25T08:19:33.610057Z 641eebc PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@coderabbitai

coderabbitai Bot commented Oct 25, 2026

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 48 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration
Commits

Reviewing files that changed from the base of the PR and between c4d72db and 641eebc.

Files ignored due to path filters: 1
  • go.sum is excluded by !**/*.sum
Files selected for processing: 15
  • dev-docs/adr/0050-a-component-call-is-a-transaction-over-a-snapshot.md
  • dev-docs/adr/README.md
  • docs/PLUGINS.md
  • go.mod
  • internal/cli/opts/options.go
  • internal/cli/opts/options_test.go
  • internal/composition/composition_test.go
  • internal/engine/engine.go
  • internal/engine/engine_test.go
  • internal/engine/match_eligibility_test.go
  • internal/plugin/pool.go
  • internal/plugin/pool_test.go
  • internal/registry/builder.go
  • internal/registry/module.go
  • internal/registry/module_test.go
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@github-actions

Copy link
Copy Markdown
Contributor

Bomly Diff Summary

Compared c4d72dbe110d82fc2bb6f3b2384ff1de9baf4b10 to 641eebc76d44959a5884ecb6b209526b60faa2c2.

Overview

Status Manifests Dependencies Findings Duration
✅ Pass +0 / ~1 / -0 0 added / 1 version changed / 0 detail changes / 0 removed 0 introduced / 0 persisted / 0 resolved 1m 26s

Dependency Changes

Summary: 0 added, 1 version changed, 0 detail changes, 0 removed.

Changed Dependencies

Change Package Version Direct? Scope Licenses
changed github.com/bomly-dev/bomly-sdk v0.14.10 → v0.16.0 Yes runtime Apache-2.0

Vulnerabilities

✅ No vulnerability changes.

License Changes

✅ No license changes.

Project Posture

✅ No project posture changes (--matchers +scorecard was not selected).

Policy Findings

✅ No policy differences were identified.

@bomly-guy
bomly-guy merged commit 67be1d0 into main Oct 25, 2026
17 checks passed
@bomly-guy
bomly-guy deleted the claude/component-runtime-adoption branch October 25, 2026 19:34
bomly-guy added a commit that referenced this pull request Oct 25, 2026
Neither record met the ADR bar: ADR-0050's reason already lives in
Engine.Match's doc comment and the SDK Clone docs, and ADR-0051 mostly
described the code and restated ADR-0040's ownership split. Both are
deleted. ADR-0050 landed with #532 and nothing relied on it, so it has no
retired stub.

The two points that pass the bar move to existing homes. ADR-0020, the live
trust record, is revised in place: a manifest access block is the
publisher's unverified claim, shown before enabling and never enforced.
dev-docs/ARCHITECTURE.md (Scan Pipeline) now records why only a plan that
can never be satisfied fails the command, and why each matcher and analyzer
call works on its own snapshot. Code references point there; the ADR index
is back to 21 live records.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
bomly-guy added a commit that referenced this pull request Oct 25, 2026
…ccess (#531)

* build(deps): adopt bomly-sdk v0.16.0, giving embedded components a lifetime scope

v0.15.0 added HostContext.OnCleanup. Each embedded component now gets a
plugin.ComponentScope that RegisterModule records before the
constructor runs, and Registry.Close ends them newest first with joined
errors. Threading the command context and closing the registry at
command end follow in this pull request.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(engine): preflight declared component requirements before a stage runs

Each stage now compares the requirements a component's descriptor declares
(bomly-sdk v0.16.0 plugin.Requirements) with what the host can vouch for:
source-tree-v1 for a filesystem or Git target not planned as an SBOM
document, dependency-graph-v1 once detection found a dependency node, and
vulnerability-records-v1 at analyze and audit once the registry carries a
record. A token this host cannot evaluate is never satisfied.

Before any stage, an explicitly selected component the plan can never run
fails the command with a PreflightError (exit 4) naming the component, the
requirement and the remedy. Inside a stage, a component whose requirement
the actual data misses is held back through a registry view before Ready is
called, with a warning on the stage's channel. Components that declare
nothing are untouched, and Ready/Applicable stay authoritative for the rest.

engine.go is not touched: the hook lives in pipeline.go around the existing
engine calls.

Refs #417

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(plugins): disclose declared access and requirements in plugin views

A package manifest may now carry the SDK's access block (bomly-sdk
v0.16.0 plugin.Access), validated only through plugin.ValidateAccess. A
malformed block fails the install; an absent one keeps installing and reads
as unknown, never as "no access". Install, enable (before the plugin is
enabled), info, verify and doctor show it as the publisher's unverified
claim through one renderer, and the JSON views carry it with
accessDisclosure set to declared or unknown. Nothing is enforced.

Declared requirements appear in `plugins info` (unknown tokens marked) and
in generated matcher, auditor and detector-chain pages when a component
declares any; no built-in does yet, so the generated docs are unchanged.

The installed-snapshot comparison now includes requirements, so a binary
whose declared requirements changed since install fails verify, and the
descriptor clone helpers delegate to the SDK's Clone, which copies them.

Refs #417
Refs #418

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: ADR-0051 and plugin docs for component prerequisites and declared access

ADR-0051 records the requirement vocabulary the host evaluates, unknown
tokens, explicit-versus-default failure, why provider names are not a
requirement, and disclosure without enforcement. docs/PLUGINS.md gains
"Component prerequisites" and "Declared access"; the authoring guide lists
the access keys and the descriptor's requires list.

Closes #417
Closes #418

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(engine): preflight ecosystem-scoped auditors in a component audit

explain's component audit selects auditors by the queried package's
ecosystem, but preflight listed them with no ecosystem, so an npm-only
auditor was neither checked at planning nor held back before Ready. The
plan now sees every auditor the filter selects, and the component-audit
stage evaluates the same selection the engine makes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: address CodeRabbit round 1 on preflight and access disclosure

- explain reports a preflight skip once, not once per matching manifest.
- LoadRuntimePlugins sets accessDisclosure like the other installed loaders.
- An absent access block reads "has no access declaration", which cannot be
  mistaken for an empty declaration.
- PLUGINS.md and the authoring guide state when Ready and Applicable run,
  and what a refused install says; ADR index count and ADR-0051 trimmed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(adr): fold ADR-0050 and ADR-0051 into existing records

Neither record met the ADR bar: ADR-0050's reason already lives in
Engine.Match's doc comment and the SDK Clone docs, and ADR-0051 mostly
described the code and restated ADR-0040's ownership split. Both are
deleted. ADR-0050 landed with #532 and nothing relied on it, so it has no
retired stub.

The two points that pass the bar move to existing homes. ADR-0020, the live
trust record, is revised in place: a manifest access block is the
publisher's unverified claim, shown before enabling and never enforced.
dev-docs/ARCHITECTURE.md (Scan Pipeline) now records why only a plan that
can never be satisfied fails the command, and why each matcher and analyzer
call works on its own snapshot. Code references point there; the ADR index
is back to 21 live records.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(plugins): state the outcome for an unknown requirement

A component selected by name with a requirement this Bomly does not know
stops the command with exit code 4; a default one is skipped with a warning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: apply the docs-criteria review to prerequisites and access disclosure

- ADR-0050 returns as a retired stub: it was live on main, and numbers and
  filenames are kept. The index lists it under Retired (29 stubs).
- ADR-0020 has one Revised line, a Context sentence on plugin trust, and an
  accurate account of when the access block is shown: at install and in
  plugins info; plugins enable shows it but asks for no confirmation.
- PLUGINS.md lists every case that stops a run with exit 4 (as preflight's
  available() decides it), links the exit code and the SBOM glossary entry,
  says an omitted access list equals an empty one, and drops the circular
  "compare with what the plugin says".
- EXIT_CODES.md gains the preflight case under exit 4.
- The authoring guide links the prerequisites section inline and shows how
  a Go descriptor declares Requires.

Refs #535

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(engine): an SBOM beside source manifests leaves a source tree

Discovery plans an SBOM found in a directory as its own subproject next to
the directory's lockfiles, and any such subproject made preflight treat the
whole target as an SBOM document, skipping or rejecting components that
need source-tree-v1. A target is now an SBOM document only when every
planned subproject is one, as with --sbom.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

engine: isolate component inputs and commit enrichment only on success runtime: apply component lifetime scopes to embedded and managed modules

1 participant