Create php-fast-forward/memoize repository for WeakMap memoization implementation planning

[coisa]

Problem

We need a reusable PHP memoization implementation pattern (similar to the WeakMap-based approach shared in
https://gist.github.com/calebporzio/d847abaed2ad491128352db21f3fac9d) to reduce repeated computation while preserving garbage-collection friendliness.

Objective

Create a new repository under php-fast-forward to host a simple, production-oriented memoization package that demonstrates a WeakMap-based cache strategy, with implementation deferred for now and only planning captured here.

Proposed Scope

• Create php-fast-forward/memoize as the target repository.
• Track a concrete implementation plan for:
  • a cache service based on WeakMap for objects and a fallback map strategy for scalar keys,
  • memoization of closures/callables,
  • deterministic cache-key derivation,
  • deterministic eviction behavior,
  • thread-safe-safe call semantics in PHP request lifecycle context.
• Enforce repository-level constraints aligned with existing Fast Forward repos that will use this package with dev-tools:
  • protected default branch with clear bypass rules,
  • security features enabled (Dependabot/Dependabot-style alerts + code scanning where applicable),
  • branch and package settings compatible with php-fast-forward policies,
  • GitHub Pages configuration aligned to repo documentation needs,
  • shared workflow surfaces and dev-tools reuse path prepared from day one.

Current Limitation

There is no central minimal memoization package in Fast Forward, so each repo risks re-implementing ad-hoc caching logic.

Proposed Work

1. Create repo skeleton: php-fast-forward/memoize with README, .editorconfig, .gitattributes, .github baseline.
2. Document the target API and behavior in issue acceptance criteria before coding:
   • memoize(callable $fn): callable
   • optional TTL/invalidator strategy (deferred as follow-up)
   • WeakMap-backed object identity when the first argument (or whole context) is an object.
3. Define repository guardrails to mirror existing Fast Forward conventions:
   • branch protection defaults,
   • security checks and alerting enabled,
   • release workflow compatibility with GitHub Pages.
4. Add implementation tasks in a follow-up issue once repository configuration is validated.

Implementation Notes (for the future)

• Use a dedicated Memoize/Memoizer service, not inline in user code.
• Keep orchestration and storage strategy separated from the caching domain.
• Keep API surface stable and testable with clear contracts:
  • deterministic key normalizer
  • cache backend interface (future pluggable)
  • optional fallback for un-memoizable arguments
• Validate behavior with focused tests before enabling any advanced caching features.

Non-goals

• This issue is not implementing the full package code.
• Do not add framework-specific adapters in this first phase.
• Do not alter existing action workflows in this repository in this issue.

Benefits

• A shared memoization primitive for Fast Forward and downstream packages.
• Standardization of cache semantics and testable behavior.
• Lower duplication and predictable performance characteristics when memoization is needed.

Acceptance Criteria

Delivery Criteria

• New repository php-fast-forward/memoize is created.
• This issue is present with the full implementation plan and constraints.
• Repository bootstrap includes the minimum files needed for dev-tools-driven setup and future package implementation.
• Security/branch constraints to mirror Fast Forward expectations are explicitly documented in repo docs before first implementation PR.

Functional Criteria

• WeakMap strategy and fallback key strategy are agreed before implementation starts.
• API proposal includes examples for object and scalar argument calls.
• README includes reproducible usage examples and a clear section on GC-safe behavior.

Architectural / Isolation Criteria

• MUST: The core logic MUST be isolated into dedicated classes or services instead of living inside command or controller entrypoints.
• MUST: Responsibilities MUST be separated across input resolution, domain logic, processing or transformation, and output rendering when the change is non-trivial.
• MUST: The command or controller layer MUST act only as an orchestrator.
• MUST: The implementation MUST avoid tight coupling between core behavior and CLI or framework-specific I/O.
• MUST: The design MUST allow future extraction or reuse with minimal changes.
• MUST: The solution MUST remain extensible without requiring major refactoring for adjacent use cases.