038 scope unification

[akollegger]

This pull request introduces a unified and extensible scope abstraction for structure-aware folds in the Pattern library, generalizing paramorphism (para) to support both tree and graph contexts under a common interface. The changes add new typeclasses and data types (ScopeQuery, TrivialScope, ScopeDict), provide a new generic fold primitive (paraWithScope), and update documentation throughout the codebase and guides to reflect the new model and its recommended usage in ports to other languages. Backward compatibility is preserved: the classic para API and behavior remain unchanged, but are now implemented in terms of the new primitives.

Key changes:

Core Library API and Implementation

• Introduced the ScopeQuery typeclass, the TrivialScope data type for subtree-only scopes, the ScopeDict value-form for first-class scope providers, and the paraWithScope function for explicit, scope-aware folding. The classic para is now a wrapper over paraWithScope with TrivialScope for backward compatibility. (libs/pattern/src/Pattern/Core.hs, Pattern.hs) [1] [2] [3] [4] [5] [6]

Documentation: Reference and Porting Guides

• Updated the Porting Guide to describe the new scope abstraction, mapping strategies for other languages, and the relationship between ScopeQuery, ScopeDict, and classic paramorphism. Clarified the recommended implementation order and tree/graph fold distinctions. (docs/reference/PORTING-GUIDE.md) [1] [2] [3] [4]
• Overhauled the paramorphism documentation to explain the unified scope model, new API, and usage patterns for both tree and graph folds. (docs/reference/features/paramorphism.md) [1] [2] [3] [4] [5]
• Updated the paraGraph documentation to clarify its role as a graph-scoped fold under the new scope model and to document the new internal helper for deriving a ScopeDict from a GraphView. (docs/reference/features/para-graph.md) [1] [2] [3]

Rules and Feature Plan Updates

• Added feature plan and test rules for the new scope unification feature, documenting its Haskell implementation and in-memory semantics. (.cursor/rules/specify-rules.mdc) [1] [2]

These changes lay the groundwork for more powerful, extensible, and portable structure-aware folds, while keeping the existing API stable for current users.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (19 files)

• .cursor/rules/specify-rules.mdc - Feature rule updates
• docs/reference/PORTING-GUIDE.md - Scope abstraction mapping documentation
• docs/reference/features/para-graph.md - Updated with unified scope model
• docs/reference/features/paramorphism.md - Overhauled with unified scope model
• libs/pattern/src/Pattern.hs - Export documentation updates
• libs/pattern/src/Pattern/Core.hs - Core scope abstractions implementation
• libs/pattern/src/Pattern/Graph/Transform.hs - Graph scope adapter implementation
• libs/pattern/tests/Spec/Pattern/CoreSpec.hs - New scope tests
• libs/pattern/tests/Spec/Pattern/Graph/TransformSpec.hs - Graph scope tests
• proposals/scope-unification-proposal.md - New feature proposal
• specs/038-scope-unification/* - Full specification artifacts

Review Notes

This is a well-designed additive feature that introduces a unified scope abstraction for structure-aware folds:

1. Backward Compatibility Preserved: The existing para and paraGraph APIs remain unchanged - they're now implemented as wrappers over the new paraWithScope primitive with TrivialScope.

2. Clean Implementation: The new ScopeQuery typeclass, TrivialScope, ScopeDict, and paraWithScope are implemented correctly with proper Haskell idioms.

3. Graph Adapter Approach: Using an internal GraphViewScope adapter (rather than modifying GraphQuery) maintains the additive-only change requirement.

4. Comprehensive Tests: New tests cover TrivialScope behavior, paraWithScope compatibility, custom scope providers, ScopeDict equivalence, and graph-backed scope.

5. Documentation: Reference docs are thoroughly updated with the unified scope mental model and cross-language mapping guidance.

No issues requiring inline comments were found.

[Copilot]

Pull request overview

This PR introduces a unified, extensible “scope” abstraction for structure-aware folds in the pattern library, generalizing classic paramorphism (para) into a scope-explicit primitive (paraWithScope) while preserving existing behavior for both tree (para) and graph (paraGraph) folds.

Changes:

• Added new scope APIs in Pattern.Core: ScopeQuery (with ScopeId), TrivialScope, ScopeDict, toScopeDict, and paraWithScope; reimplemented para via paraWithScope.
• Added graph-side generic scope reification via scopeDictFromGraphView and an internal GraphViewScope adapter; updated tests to cover graph-backed scope queries and equivalence.
• Updated reference docs and porting guidance to explain the unified scope model and its cross-language mapping.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
libs/pattern/src/Pattern/Core.hs	Introduces unified scope abstractions (ScopeQuery, TrivialScope, ScopeDict) and paraWithScope; redefines para in terms of the new primitive.
libs/pattern/src/Pattern/Graph/Transform.hs	Adds scopeDictFromGraphView and internal GraphViewScope adapter; wires updated paraGraph/paraGraphFixed plumbing.
libs/pattern/tests/Spec/Pattern/CoreSpec.hs	Adds unit + property tests for TrivialScope, paraWithScope compatibility, custom scope providers, and ScopeDict equivalence.
libs/pattern/tests/Spec/Pattern/Graph/TransformSpec.hs	Adds tests for graph-backed generic scope answers (scopeDictFromGraphView) and wrapper-preservation tests for paraGraph/paraGraphFixed.
libs/pattern/src/Pattern.hs	Updates top-level module documentation to reflect new scope model and the new graph scope reifier.
docs/reference/features/paramorphism.md	Reframes paramorphism docs around the unified scope model and documents paraWithScope as canonical.
docs/reference/features/para-graph.md	Clarifies paraGraph as graph-scoped wrapper and documents scopeDictFromGraphView relationship.
docs/reference/PORTING-GUIDE.md	Adds explicit typeclass/dictionary ↔ trait/object mapping guidance for ports; updates fold implementation guidance.
proposals/scope-unification-proposal.md	Adds/updates the design proposal narrative and example code for the unified scope model.
specs/038-scope-unification/tasks.md	Adds implementation task breakdown for the feature.
specs/038-scope-unification/spec.md	Adds the feature specification (user stories, requirements, success criteria).
specs/038-scope-unification/research.md	Records design decisions and alternatives considered for scope unification.
specs/038-scope-unification/quickstart.md	Adds a quickstart checklist for implementing and verifying the feature.
specs/038-scope-unification/plan.md	Adds implementation plan, constraints, and testing/perf guardrails.
specs/038-scope-unification/data-model.md	Defines the in-memory API “data model” for scope unification concepts.
specs/038-scope-unification/contracts/Pattern.Core.hs	Adds contract stub for intended Pattern.Core API (currently diverges from implementation).
specs/038-scope-unification/contracts/Pattern.Graph.Transform.hs	Adds contract stub for intended graph-side API (currently diverges from implementation).
specs/038-scope-unification/checklists/requirements.md	Adds a spec-quality checklist for the feature artifacts.
.cursor/rules/specify-rules.mdc	Updates generated rules to include the new feature’s tech footprint.