Hyperphp Proposals

This folder contains design proposals (RFC-style) for language, runtime, and host API changes.

Why

Proposals make non-trivial changes reviewable before implementation, reduce rework, and preserve rationale over time.

Lifecycle

Every proposal must have one of these statuses:

  • draft: initial proposal, open questions expected.
  • review: ready for focused technical or product review.
  • accepted: approved for implementation.
  • implemented: shipped (with PR or commit links).
  • rejected: declined (kept for history).

File Naming

Use zero-padded numeric IDs and short slugs:

  • 0001-queryspec-host-dsl.md
  • 0002-handler-label-arguments.md

Rules:

  • one proposal per file
  • IDs are immutable
  • never reuse an ID

Proposal Template

Copy this into new proposal files:

# Proposal NNNN: Title

## Status
draft

## Summary
Short statement of what changes and why.

## Motivation
What problem this solves, with concrete examples.

## Goals
- ...
- ...

## Non-Goals
- ...

## User-Facing Syntax / Behavior
Canonical forms and examples.

## Semantics
Precise rules, precedence, and edge-case behavior.

## Public API / Interface Changes
New or changed interfaces, DTOs, and contracts.

## Parser / AST Changes
Grammar and node changes.

## Runtime Changes
Execution flow and compatibility behavior.

## Error Model
Error cases, codes, and messaging expectations.

## Testing Plan
Parser, runtime, integration, and regression scenarios.

## Backward Compatibility
What remains compatible and what requires migration.

## Open Questions
Unresolved decisions.

## Rollout Plan
Phases and release strategy.

## Acceptance Criteria
Definition of done.

Review Expectations

A proposal should not move to accepted until it is decision-complete on:

  • user-facing behavior
  • API and contract changes
  • failure modes
  • tests
  • compatibility and rollout

Implementation Linkage

When implementation starts:

  • reference proposal ID in PR title or body
  • keep proposal status updated
  • once shipped, set status to implemented and add links:
  • PR(s)
  • commit(s)
  • release note entry (if applicable)

Scope Guidance

Use a proposal when changes are non-trivial, especially:

  • language syntax or semantics
  • parser, AST, or runtime execution behavior
  • host-facing interface changes
  • behavior that can break user expectations

Small localized bug fixes usually do not need a proposal.