yoi/work-items/open/20260530-013904-profile-authoring-requirements-sync/item.md

id	slug	title	status	kind	priority	labels	created_at	updated_at	assignee	legacy_ticket
20260530-013904-profile-authoring-requirements-sync	profile-authoring-requirements-sync	Sync profile authoring requirements before choosing the language	open	task	P2	manifest profiles architecture	2026-05-30T01:39:04Z	2026-05-30T01:39:04Z	null	null

Background

The semantic-nix-profiles implementation direction exposed a deeper product/design issue: choosing a profile authoring language before agreeing on the profile boundary risks recreating the same problem in another syntax. The current Nix-shaped implementation drifted toward manifest-shaped authoring, while the desired authoring experience is portable, reusable, and abstracted through system-provided APIs/functions/modules.

Recent discussion ruled out treating the current semantic JSON projection as sufficient. If JSON Profile -> Manifest preserves almost the same information as Manifest, it is an abstraction failure. Likewise, a Nix-like custom subset is risky because users must learn deviations from real Nix and trust a new evaluator. Snix is technically relevant but currently carries licensing/distribution concerns for direct embedding. Lua is under consideration as a pragmatic embeddable language with long-standing implementation experience, but the profile specification is intentionally not decided yet.

This ticket is only for synchronizing requirements and open questions before committing to a language/API. It should not implement the profile language.

Current shared requirements

• Profile authoring must not be a low-level Manifest DSL in another syntax.
• The runtime Manifest remains resolver output, not the normal profile authoring surface.
• --manifest remains the explicit low-level concrete manifest escape hatch.
• Profile identity is minimal: slug/name and description may be the only direct profile metadata, and may also be supplied by registry/file context where appropriate.
• Instance-specific runtime values such as pod.name do not belong in reusable profiles; Pod names come from CLI/TUI/SpawnPod/runtime inputs.
• Scope authority must not move into profiles. SpawnPod.scope / explicit delegation remains authoritative for capability expansion.
• Reasoning, model, context, compaction, memory, web, and tool behavior should be expressed through higher-level profile APIs/policies/presets and manifestized by Rust.
• Model/context-derived numeric settings, especially compaction thresholds, should be derived from model metadata/policy in one place rather than copied as raw constants into user profiles.
• Built-in/default startup should not silently depend on a missing/slow external evaluator unless that dependency is deliberately accepted and documented.
• User-authored profiles should support practical reuse/composition of partial definitions.
• System-provided APIs should be injected or loaded through a stable mechanism, not by asking users to import files from Insomnia's installed resource layout.
• If Lua is chosen, require("insomnia") / require("insomnia.*") as host-provided virtual modules and controlled local require are candidate mechanics, but not yet final.
• A returned plain table may be acceptable as a profile artifact, but arbitrary tables must not be blindly interpreted as Manifest-shaped config. The acceptance boundary is still open.

Open specification questions

• Which authoring language should be supported first: Lua, external Nix wrapper, Starlark/Jsonnet/Nickel/Rhai, or another option?
• If Lua is chosen, which Rust embedding crate/features are acceptable, and how should sandboxing be configured?
• What is the exact module loading model?
  • host-provided require("insomnia") / require("insomnia.*");
  • profile-local reusable modules;
  • denied standard libraries such as os, io, debug, package;
  • module cache scope and path traversal behavior.
• What exact return contract should profile files use?
  • return require("insomnia.profile").coder { ... };
  • return { slug = ..., description = ..., policy = ... };
  • explicit profile constructor vs plain table;
  • how invalid Manifest-shaped returns are diagnosed.
• What is the minimal stable Insomnia profile API surface?
  • profile constructors;
  • presets;
  • model references;
  • context/compaction policies;
  • memory/web/tool policy helpers;
  • extension/merge helpers.
• How are profile metadata and registry metadata reconciled when both exist?
• How should existing Nix profile support be handled: keep as advanced/external evaluator path, deprecate, or replace?
• What compatibility/migration story is acceptable for current built-in Nix profile files and existing user profiles?
• What validation and diagnostics are required before any implementation is merged?

Acceptance criteria

• Capture the agreed requirements above in the work item and keep them synchronized with the design discussion.
• Record the unresolved language/API/sandbox/return-contract questions without prematurely deciding the specification.
• Ensure semantic-nix-profiles implementation work does not proceed as if semantic JSON projection were the accepted design.
• Once the specification is decided, either update this ticket into the implementation ticket or create a follow-up implementation ticket with a clear intent packet.