Skip to content

Define package visibility for index.prose.md and sibling Contracts #168

Description

@irl-dan

Problem

OpenProse documents directory packages with an index.prose.md root and private sibling sub-units, but the language and resolver do not define package exports or enforce sibling privacy. Today, private is an authoring convention rather than a Contract boundary.

This surfaced while splitting std/ops/compose into an obligation-centered package. Only compose/index.prose.md should be publicly addressable; architecture, dialogue, source, view, and feedback Contracts are implementation details.

Evidence

  • packages/std/ops/prose-author.prose.md recommends a multi-unit folder with index.prose.md plus private sub-units and validates a private sub-unit directory.
  • skills/open-prose/deps.md defines directory-root resolution to index.prose.md, but does not define exports or visibility.
  • Contract Markdown and Forme resolve Contracts by name/path without a package-private rule.

Desired property

A directory package has one self-evident public surface. Importing or running the directory resolves its index.prose.md; sibling Contracts remain package-private unless deliberately exported. Compile/lint should reject cross-package references to private siblings.

Smallest plausible change

Define index.prose.md as the sole public entrypoint by default and sibling *.prose.md Contracts as package-private. Add an explicit export mechanism only when a package needs multiple public Contracts. Document local sibling resolution separately from cross-package resolution and add compiler/lint coverage.

Alternatives

  • Use directory placement such as private/ as the visibility boundary.
  • Add frontmatter visibility to every Contract.
  • Keep convention-only privacy, but stop claiming it is enforced.

This is framework feedback discovered during Compose work; implementation should happen separately from that design session.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions