Skip to content

feat(lang): canonicalize pattern reference syntax and documentation (#170) - #177

Open
Adityakk9031 wants to merge 1 commit into
openprose:mainfrom
Adityakk9031:feat/canonicalize-pattern-syntax-170
Open

feat(lang): canonicalize pattern reference syntax and documentation (#170)#177
Adityakk9031 wants to merge 1 commit into
openprose:mainfrom
Adityakk9031:feat/canonicalize-pattern-syntax-170

Conversation

@Adityakk9031

Copy link
Copy Markdown

Summary & Motivation

Resolves #170

OpenProse patterns (kind: pattern) are compile-time coordination abstractions. However, as identified in #170, pattern references and instantiations suffered from documentation inconsistencies:

  • The canonical section ### Patterns was used in smoke tests and referenced in specs, but missing from the canonical section tables.
  • Documentation in prose.md pointed to a nonexistent Forme pattern-expansion section (forme.md, Pattern Expansion).
  • Authors and prose compose lacked a single cross-linked definition showing the relationship among use (import/aliases), pattern: (reference), with: (slot binding), and config: (parameters).

This PR canonicalizes pattern references, adds the missing Forme expansion specification, repairs cross-references, and adds a dedicated conformance test suite.


Key Changes

  1. Canonical Section: ### Patterns (skills/open-prose/contract-markdown.md, spec/01-Language.md)

    • Added ### Patterns to the Canonical Sections tables in Contract Markdown and the Language Specification.
    • Clarified that pattern instances are placed in ### Patterns using fenced yaml declarations (- name:, pattern:, with:, config:).
  2. Unified Definition of use, pattern:, with:, and config: (skills/open-prose/contract-markdown.md)

    • Defined how use "std/patterns/worker-critic" creates a local alias that pattern: worker-critic can reference directly.
    • Documented how name: defines the expanded node name invoked by ProseScript call {name} in ### Execution.
    • Documented slot binding (with:) and configuration overrides (config:).
    • Provided an end-to-end worked example connecting use, ### Patterns, and ### Execution.
  3. Forme Pattern Expansion Specification (skills/open-prose/forme.md)

    • Added the ## Pattern Expansion section detailing the compile-time expansion lifecycle:
      • Resolution: Local contracts, dependency cache (deps/), and std/ shorthand expansion.
      • Slot Validation: Verification that all declared ### Slots are satisfied by responsibilities, functions, or nested pattern instances.
      • Config Validation: Verification and default application against declared ### Config.
      • Instantiation & Delegation Lowering: Lowering ### Delegation into ProseScript execution logic.
      • Inside-Out Nesting & Cycle Prevention: Nested pattern expansion proceeds inside-out; recursive patterns are strictly prohibited.
  4. Repaired Cross-References (skills/open-prose/prose.md)

    • Updated references in the VM execution documentation to cleanly point to contract-markdown.md (Patterns) and forme.md, Pattern Expansion.
  5. Conformance Tests (tests/open-prose/contract-markdown/patterns.test.ts)

    • Added 6 automated tests validating:
      • Inclusion of ### Patterns in the Canonical Sections tables of contract-markdown.md and 01-Language.md.
      • End-to-end explanation of use, pattern:, with:, and config:.
      • Presence and invariants of ## Pattern Expansion in forme.md.
      • Resolution of cross-references in prose.md.
      • Conformance of smoke test 09-local-pattern.prose.md.

Verification

  • Ran pnpm vitest run tests/open-prose/contract-markdown/patterns.test.ts (6/6 tests passed).
  • Ran pnpm vitest run tests/open-prose/forme/forme.test.ts (23/23 tests passed).

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.

Canonicalize pattern reference syntax and documentation

1 participant