ticket: sync profile authoring requirements

work-items/open/20260529-222850-semantic-nix-profiles/thread.md

@@ -29,4 +29,15 @@ Decisions for the implementation pass:
 Implementation should remain narrow: preserve existing profile selection semantics, source-qualified selectors, ambiguity errors, TUI/client profile selection flow, and `SpawnPod.scope` authority.
 
 
+---
+
+<!-- event: decision author: hare at: 2026-05-30T01:39:47Z -->
+
+## Decision
+
+Implementation is paused after design discussion. The attempted direction of introducing a semantic JSON-profile-to-Manifest projection is not accepted as the specification: it risks preserving nearly the same information as Manifest and therefore failing the intended abstraction.
+
+The current design question has been split into `profile-authoring-requirements-sync`, which records the shared requirements and open questions before choosing Lua/external Nix/another authoring language. Do not proceed with the existing child-worktree implementation until that specification is decided.
+
+
 ---

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

@@ -0,0 +1,70 @@
+---
+id: 20260530-013904-profile-authoring-requirements-sync
+slug: profile-authoring-requirements-sync
+title: Sync profile authoring requirements before choosing the language
+status: open
+kind: task
+priority: P2
+labels: [manifest, profiles, architecture]
+created_at: 2026-05-30T01:39:04Z
+updated_at: 2026-05-30T01:39:04Z
+assignee: null
+legacy_ticket: 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.