RFC pilot: ephemeral.* namespace + discoverable annotation (apcore#54)

[tercel]

Context

aiperceivable/apcore PR #54 introduces docs/spec/rfc-ephemeral-modules.md — a reserved ephemeral.* namespace for programmatically-registered modules synthesized at runtime by LLM agents (à la ToolMaker, ACL 2025, arXiv 2502.11705).

apcore-python is the recommended pilot SDK because it already has the register_internal() precedent (used for system.* modules) — the closest existing pattern in any of the three SDKs.

Why pilot here first

• Existing programmatic-registration path: Registry.register(module_id, module, ...) already accepts caller-supplied IDs.
• Existing register_internal() for system.* proves the non-filesystem registration model in production.
• Python's runtime introspection makes the discoverable: false filter trivial to implement (hasattr / annotation-driven).

Scope of pilot

1. Reserve ephemeral.* namespace — error if it's used as a filesystem-derived ID; allow only via Registry.register().
2. Add discoverable: false annotation to ModuleAnnotations (default true). When false, exclude from Registry.list() / find() / manifest exports.
3. Audit-event emission — emit apcore.registry.module_registered / apcore.registry.module_unregistered for ephemeral.* IDs (mirroring D-35 contextual-auditing shape).
4. Soft warning when requires_approval is not true on an ephemeral.* registration — guard against unattended execution of agent-synthesized code.
5. Lifecycle: caller-managed (Registry.unregister()) for the v1 pilot. TTL/GC sweeper deferred to v2 if leakage is observed.

Out of scope (host concern)

Sandboxing of agent-synthesized code bodies. Hosts (apcore-mcp, apcore-cli, etc.) provide their own isolation. This pilot is registration + audit + lifecycle only.

Acceptance criteria

• ephemeral.* namespace reserved + tested
• discoverable annotation added + honored by Registry.list() / find()
• Audit events emitted on register/unregister for ephemeral.* IDs
• Soft warning when requires_approval is not true on ephemeral.* registration
• Tests cover all of the above
• Pilot findings documented back to upstream RFC for promotion to normative spec

Cross-refs

• Upstream RFC: docs(spec): draft RFCs — Module.preview() and ephemeral modules apcore#54 (docs/spec/rfc-ephemeral-modules.md)
• Adjacent literature: ToolMaker (ACL 2025, arXiv 2502.11705); LATM (LLM-ToolMaker)
• Existing precedent in this repo: register_internal() for system.* modules

🤖 Generated with Claude Code

[tercel]

Dependency status — blocked on apcore RFC acceptance.

This pilot is gated on aiperceivable/apcore#54 (rfc-ephemeral-modules.md) reaching Accepted status. The RFC is currently in Draft / RFC and explicitly recommends apcore-python as the pilot SDK because of the existing register_internal() precedent for system.* modules.

Once accepted, this issue can move forward independently of apcore-rust and apcore-typescript work.

🤖 (auto-comment from cross-repo dependency review)