# src/modules/opunk — Alternative Punk Namespace (voo-based classes)

## Purpose

Modules under the `opunk::*` namespace explore value-based class implementations of punk facilities using the vendored `voo` OO system (`src/vendormodules/voo-1.0.0.tm`). Objects are plain Tcl list values; class namespaces hold the methods.

## Ownership

- Agents may edit modules here when working on voo-based reimplementations; the corresponding `punk::*` modules remain the production implementations until integration is explicitly done.
- `voo` itself is a vendored dependency — change it via the vendormodules workflow, not here.

## Local Contracts

- Class namespaces are capitalized (`::opunk::Str`, `::opunk::Console`); companion lowercase namespaces (`::opunk::str`, `::opunk::console`) hold package-level procs, PUNKARGS docs and shared state.
- Fields use the `o_` prefix (even though voo private accessors already get a `my.` prefix) to distinguish fields from locals in `-update` method bodies and ease code movement to/from tclOO implementations.
- voo makes each field name a class-namespace variable holding the field's list index — avoid `variable o_<field>` in method bodies.
- Classes intended for behavioral subclassing are declared `-virtual` (slot 0 of each value is the concrete class namespace tag); behaviour-differentiating methods are declared `-virtual` so calls through the base class dispatch on the tag.
- Entity-like objects (e.g. consoles) anchor canonical instances at well-known namespace variables (`::opunk::console::instances::<name>`) with lowercase wrapper procs owning mutation; the value semantics serve as snapshots/copies where cheap.
- Cooperative shared state is pluggable rather than hardwired: the probe-byte waiting store is the array named by `::opunk::console::waiting_chunks_arrayvar` (default `::opunk::console::waiting_chunks`); integrating layers redirect it to their established store (punk::console::default_console points it at `punk::console::input_chunks_waiting`) so probe-consumed bytes stay visible to active readers.
- Method-entry validity guards use `[llength $this] < N` (not `!= N`) so field-adding subclasses keep working.
- Module filenames use the `-999999.0a1.0.tm` magic suffix with `<modulename>-buildversion.txt` per parent conventions.
- `opunk::console` (with its dependency `voo`) is included in bootsupport via `src/bootsupport/modules/include_modules.config` for eventual boot/repl-startup console objects; after releasing a new version, rebuild with `make.tcl modules` then refresh the snapshot with `make.tcl bootsupport`.

## Work Guidance

- Use `::opunk::Str` (str module) as the reference for voo idioms: unshare/restore scripts, `-update` copy-on-write avoidance, explicit list-literal construction in constructors.
- Keep `opunk::console` free of `punk::console` dependencies — integration is planned as punk::console delegating to the class, not the reverse.
- Future capability to preserve: a subshell repl attached to a foreign console (e.g ssh channels, or a tk text widget acting as a terminal). Design rules that protect it: behaviour goes through `-virtual` methods so non-channel subclasses can override everything channel-related; `o_in`/`o_out` are uninterpreted strings (a widget subclass may store widget paths); instances are named-multi-anchor (never a singleton); and punk::console integration must keep migrating operations to object-method dispatch rather than entrenching raw channel operations after spec resolution.

## Verification

- `tclsh src/tests/runtests.tcl -report compact -show-passes 0 -include-paths modules/opunk/<module>/**` passes for the touched module.
- `tclsh src/make.tcl modules` completes without errors after module additions.

## Child DOX Index

(None — flat module files)