Skip to content

feature(op): Resource management — Phases 9-11, epic complete - #187

Merged
David-Noble-at-work merged 2 commits into
developfrom
feature/resource-management-phase-5g
Mar 6, 2026
Merged

David-Noble-at-work merged 2 commits into
developfrom
feature/resource-management-phase-5g

Conversation

@David-Noble-at-work

@David-Noble-at-work David-Noble-at-work commented Mar 6, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Complete the resource management epic. This PR delivers Phases 9, 10, 11,
a Phase 5g fix, and design document updates.

Phase Description Status
0 Test harness (star devlore test) ~99% done (#170)
1 ResourceCatalog (append-only ledger + URI→ID namespace) Done
2 Graph integration (Catalog field, FillSlot implicit edges) Done
3 File provider migration (all methods accept Resource) Done
4 Type system (Resource/Tombstone sealed interfaces) Done
5 Executor catalog integration (shadow/resolve, pre-flight) Done
6 Provider context (ProviderBase, git/service/pkg Resource types) Done
7 Remaining provider migration (all providers, coerceSlice) Done
8 Generated bridge tests (actions_gen_test.go via star codegen) Done
9 Resource lifecycle — Decision #10 (infallible constructors) Done
10 Purl package URIs — Decision #11 (ECMA-427 for pkg.Resource) Done
11 Action interface unification (three types, unified Do) Done

Phase 9 — Infallible constructors

  • file.NewResource returns Resource (no error, no I/O)
  • Resolve() method on Resource interface; file.Resource.Resolve() does filepath.Abs + os.Stat
  • Refresh() / RefreshWith() replace RefreshMetadata / RefreshMetadataWith
  • Single constructor registry (planTimeConstructorRegistry eliminated)

Phase 10 — Purl package URIs

  • Type, Version fields on pkg.Resource
  • Purl() method with winget namespace handling (ECMA-427)
  • Type propagated from resolved manager in Install/Remove/Upgrade

Phase 11 — Action interface unification

  • Three types: Action (pure), FallibleAction, CompensableAction
  • Unified Do(ctx, slots) → (Result, Complement, error) replaces per-type signatures
  • DoAction() dispatcher eliminated; each reflected type normalizes internally
  • Pure actions (file.name, file.parent, file.join) registered as graph nodes
  • Codegen includes all action types in generated bridge tests

Phase 5g fix

  • shadowOutputParam now shadows single-Resource compensable methods at plan time

Housekeeping

  • file.Exists/IsDir/IsFile return (bool, error) instead of bool
  • Architecture doc gains Action Type Model section
  • Three superseded draft docs deleted

48 files changed, ~2573 insertions, ~2955 deletions.

Test plan

  • make build — compiles cleanly
  • make test — all tests pass (pre-existing WrapReceiver does not expose WalkTree — callback params unsupported #170 walk_tree failure only)
  • make vet — clean
  • Verify file.NewResource returns single value (no error)
  • Verify pkg.Resource has Type/Version/Purl()
  • Grep for planTimeConstructorRegistry — zero hits
  • Grep for RefreshMetadata[^W] — zero hits in code
  • Grep for NodeAction\|DoAction — zero hits in non-generated Go
  • Grep for Complement in pkg/op/action.go — confirms rename landed
  • Verify pure actions in actions_gen_test.go (file.name, file.parent, file.join)

David Noble added 2 commits March 6, 2026 00:44
Complete the resource management epic: Phases 9, 10, 11, Phase 5g fix,
design document updates, housekeeping.

## Phase Status

| Phase | Description | Status |
|-------|-------------|--------|
| 0 | Test harness (star devlore test) | ~85% done (#164, #170, #171) |
| 1 | ResourceCatalog (append-only ledger + URI→ID namespace) | Done |
| 2 | Graph integration (Catalog field, FillSlot implicit edges) | Done |
| 3 | File provider migration (all methods accept Resource) | Done |
| 4 | Type system (Resource/Tombstone sealed interfaces, ResourceBase) | Done |
| 5 | Executor catalog integration (shadow/resolve, pre-flight) | Done |
| 6 | Provider context (ProviderBase, git/service/pkg Resource types) | Done |
| 7 | Remaining provider migration (all providers, coerceSlice) | Done |
| 8 | Generated bridge tests (actions_gen_test.go via star codegen) | Done |
| 9 | Resource lifecycle — Decision #10 (infallible constructors) | Done |
| 10 | Purl package URIs — Decision #11 (ECMA-427 for pkg.Resource) | Done |
| 11 | Action interface unification (three types, unified Do) | Done |

## Phase 9: Infallible constructors (Decision #10)

- file.NewResource returns Resource (no error, no I/O)
- Resolve() on Resource interface; ResourceBase default is no-op
- file.Resource.Resolve() does filepath.Abs + os.Stat
- git.Resource.Resolve() does filepath.Abs
- Refresh() and RefreshWith() replace RefreshMetadata/RefreshMetadataWith
- Single constructor registry (planTimeConstructorRegistry eliminated)
- Path() returns raw path before Resolve(), absolute path after

## Phase 10: Purl package URIs (Decision #11)

- Type, Version fields on pkg.Resource
- Host() returns Type as URI authority (pkg://brew/jq)
- Purl() method returns canonical purl (pkg:brew/[email protected])
- Winget namespace handling (Microsoft.VSCode → pkg:winget/Microsoft/VSCode)
- NewResource() and NewTypedResource() constructors
- Type propagated from resolved manager in Install/Remove/Upgrade

## Phase 11: Action interface unification

- Three action types: Action (pure), FallibleAction, CompensableAction
- Unified Do(ctx, slots) → (Result, Complement, error) across all types
- Complement type replaces former undo state type throughout
- DoAction() type-switch dispatcher eliminated
- reflectedPureAction/reflectedFallibleAction/reflectedCompensableAction
  with shared actionBase (coerceArgs, dryRunLog, Params)
- classifyActionReturn split into classifyFallibleReturn + classifyCompensableReturn
- validateSlotType for plan-time type checking
- Pure actions (file.name, file.parent, file.join) registered as graph nodes
- Codegen includes all action types in generated bridge tests
- Flow actions (Choose, Gather, Elevate, WaitUntil) gain Params()

## Phase 5g fix

- shadowOutputParam guard: <2 → ==0 Resource params
- Single-Resource compensable methods now shadowed at plan time

## Other changes

- file.Exists/IsDir/IsFile return (bool, error) instead of bool
- Lore builder tests: packages param corrected to []string
- Architecture doc: Action Type Model section, expanded migration table
- Superseded drafts deleted (emergent-system-model, structural-deps, subscriber-model)
- Relocated strategy doc deleted (docs/01-strategy.md)
@David-Noble-at-work
David-Noble-at-work merged commit 78356e0 into develop Mar 6, 2026
2 checks passed
@David-Noble-at-work
David-Noble-at-work deleted the feature/resource-management-phase-5g branch March 6, 2026 09:02
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.

1 participant