writeonce/docs/superpowers/specs/2026-08-20-library-kind-internal-design.md

Iteration 17 — library projects and dependency privacy: design

Status: ⏸ PARKED 2026-08-20 (developer directive: framework v1 work proceeds instead; spec + plan stay ready on branch library-internal). Approved before parking. Decisions were settled in the iteration (four forks + impact analysis); this spec makes them buildable. The plan follows after review. Board: docs/00-status.md.

Per repo convention this spec carries concept, reason, and required behavior in words only — no implementation code.

Goal

A project can say it is a library, and a dependency can keep modules to itself. Concretely: docs/examples/writeonce-framework declares kind = "library" in its wo.toml, woc <dir> on it typechecks the whole project with no entry required (the iteration-16 --emit workaround is deleted), its parser and serve-loop plumbing move under internal/ where the web-app cannot import them, and just web-app proves nothing public broke.

Background (the two gaps, from iterations 15/16)

1. A project without fn main cannot be checked: manifest presence forces build mode, which errors "no main entry point found". The framework is verified today through woc --emit — a wart.
2. pub is module-public with no dep-private tier: parse_request is exactly as importable by the consuming app as Handler. Nothing marks "this module is the library's own business".

Settled decisions (normative, from the iteration)

• Library-ness is manifest-declared: top-level kind key, values "program" (the default when absent) and "library"; any other value is a manifest error.
• Privacy is Go's internal/ directory rule, applied at the [deps] boundary only: a consumer cannot use a dependency module whose path contains an internal segment; inside the dependency the same import stays legal.
• Lib+bin duality is allowed: a library may carry an entry-shaped main; kind = "library" changes only the DEFAULT action of woc <dir>.
• Inherited from Go, explicitly not checked: an internal type may appear in a public signature. The consumer can hold and pass such a value but cannot import the module to name its type. Library author's smell to avoid, not a diagnostic.

Design

1. The manifest kind key

One top-level key in wo.toml, read where the manifest is already parsed (the driver's manifest reader in compiler/bin/main.ml). Absent means program — every existing project keeps its behavior. A value other than "program" or "library" is rejected with the new WO-E109, naming the value and the two legal ones. The key is meaningful only in the project being invoked; a DEPENDENCY's kind is read but not enforced in v1 (iteration 15 already never uses a dep's main, so a program consumed as a dep already behaves as a library — recorded, not policed).

2. Driver modes

• woc <dir> on a program: unchanged — build, requiring main.
• woc <dir> on a library: CHECK mode — the full pipeline runs (parse, typecheck, interface satisfaction, borrow/ownership pass, GC inference) over the whole project including its [deps], and stops before image emission. No entry is required. Exit 0 with no output on success, 1 with diagnostics otherwise — a green check must mean exactly what a green build means, minus the artifact. Deps are fetched/locked the same as build mode (a library must be checkable offline once locked).
• woc build <dir> -o <app> on a library WITH a main: builds the binary — the dual case (demo/self-test). Without a main: the existing no-entry error, extended to name the kind so the message explains itself ("this project is a library; add a main or check it with woc ").
• --emit, dump flags, --update-deps: unchanged; they never required an entry or already carry their own rules.

3. The internal/ rule

Where: the dep-use resolution step in compile_image — the same place iteration 15 prefixes dep module paths — because that is the only spot that knows which file belongs to which project. The rule: a use in a file that does NOT belong to dependency X, naming a module of dependency X whose dep-relative path contains a segment exactly equal to internal, is rejected with WO-E108 at that use, naming the dependency and the module. Files INSIDE dependency X importing the same module are untouched. Modules are directory-shaped (module_of_multi: dep name + relative directory), so "segment" means a path component — framework/internal and anything under it, never a substring match (a module named internals_x is not caught).

Scope notes, normative: the rule fires only across the [deps] boundary (decision 3 — dep-boundary-only; Go's subtree rule is a recorded possible tightening). The root project's own internal/ directories are legal to import from anywhere inside the root project. Transitive deps stay rejected by iteration 15's WO-E106, so dep-to-dep imports cannot occur.

4. Diagnostics (error catalog additions)

• WO-E108 — dep-internal module imported across the [deps] boundary. Points at the offending use, names the dependency and the internal module, and says the module is internal to that dependency.
• WO-E109 — invalid manifest kind value. Names the given value and the two legal ones.
• The no-entry build error gains the library wording described in §2; no new code, better message.

5. Framework reorg (the proof by use)

• wo.toml gains kind = "library".
• http/parse.wo and http/serve.wo move to internal/ (module framework/internal when consumed). They are plumbing the web-app never imports: the request parser, the carry-state record, the serve loop, the Dispatcher seam.
• http/types.wo (Req/Resp + builders), router/router.wo (Handler/Middleware/Route/Mw), and app.wo (App) stay where they are — the public surface does not move.
• Intra-framework imports update to the new module path; the web-app changes NOTHING — it already imports only framework, framework/http, framework/router.
• The framework README's verification note replaces the --emit workaround with the check-mode invocation.

6. Acceptance gate

Extend scripts/web-app-accept.sh (it already builds the framework remote and the consuming app): the standing 14 checks stay, plus (a) check mode — woc on the framework copy exits 0 with no entry present; (b) privacy — a temp copy of the app with one added use framework/internal fails compile and the output names WO-E108; (c) kind validation — a temp manifest with a junk kind fails naming WO-E109. Compiler-side, the corpus grows compile-fail fixtures for WO-E108/E109 and a run fixture is not needed (no runtime behavior exists to pin — the VM is untouched by design). Standing gates (just woc-test, just deps-accept, just oop-e2e, samples) stay green.

Out of scope (recorded, deliberate)

Go's full subtree rule; a [lib] manifest section; pub(lib)-style keyword visibility; manifest export allowlists; multiple named binaries per project (cmd/ convention); enforcing a dep's own kind; internal types in public signatures as a diagnostic; any VM, .wob, or GC change (impact analysis in the iteration: visibility is compile-time name resolution; libraries compile whole-program into the consumer's image; GC inference stays whole-program and app usage may promote dep classes — intended).

Success criteria

1. Given the framework with kind = "library" and no main, when woc <dir> runs, then it exits 0 having run the full pipeline, and woc build on it fails with the message naming the kind.
2. Given the web-app importing framework/internal, when it compiles, then WO-E108 points at the use and names the framework; the framework's own files importing it stay legal.
3. Given the reorganized framework, when just web-app runs, then all standing checks pass unchanged — the public surface did not move.
4. Given any existing project with no kind key, when it builds, then nothing changed — absent means program.