<!-- event: create author: hare at: 2026-05-29T22:28:50Z -->

Created as a follow-up to the closed manifest profiles work item after reviewing the original intent and the current built-in Nix profile shape.

---

<!-- event: plan author: planning-pod at: 2026-05-29T22:36:45Z -->

Implementation plan written to `artifacts/implementation-plan.md`. Key recommendation: introduce a typed semantic profile artifact and manifestization step, move/centralize model catalog context-window resolution so compaction can derive from model metadata, and resolve builtin profiles in-process so normal default startup does not require external `nix`.

<!-- event: plan author: hare at: 2026-05-30T00:45:10Z -->

## Plan

## Implementation direction

Use the worktree + sibling coder/reviewer flow. The investigation Pod found the main boundary issue to be concentrated in `crates/manifest/src/profile.rs`: profile artifacts are currently deserialized as `PodManifestConfig`, while built-in Nix files expose a manifest-shaped authoring API.

Decisions for the implementation pass:

- Move data-only model catalog resolution to a cycle-free place owned by `manifest` so profile manifestization can derive context-window-dependent settings. Keep live provider/client construction in `provider`.
- Introduce a semantic profile artifact format such as `insomnia.semantic-profile.v1`; top-level semantic artifacts must use `profile` metadata plus `policy`, not `manifest` / `config`.
- Resolve built-in `default` in-process so the normal default startup path does not require an external `nix` command. User/project/path Nix profiles may still require `nix eval` with clear diagnostics.
- Remove `pod.name` from built-in profiles. Direct no-arg `insomnia-pod` should preserve the current effective default Pod name `insomnia` as runtime input, while `--profile-pod-name` remains the explicit fresh-spawn override.
- Do not preserve manifest-shaped Nix profiles as the normal authoring API. `--manifest` remains the low-level concrete manifest escape hatch.
- Keep the initial semantic policy narrow: explicit model ref, explicit reasoning effort, workspace scope policy, compaction ratios/preset derived from effective context window, memory/session/web policy sufficient to reproduce current builtin behavior.
- Update docs and tests so built-in examples no longer recommend `mkManifest` or raw manifest-shaped profiles.

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.


---

<!-- event: close author: hare at: 2026-05-30T03:52:39Z status: closed -->

## Closed

---
id: 20260529-222850-semantic-nix-profiles
slug: semantic-nix-profiles
title: Make Nix profiles semantic and manifestize them in the resolver
status: closed
kind: task
priority: P2
labels: [manifest, profiles, nix, architecture]
created_at: 2026-05-29T22:28:50Z
updated_at: 2026-05-30T03:52:39Z
assignee: null
legacy_ticket: null
---

## Background

The closed manifest profiles work item (`work-items/closed/20260527-000022-manifest-profiles`) introduced profile discovery/selection, built-in profile files, and Nix evaluation as the profile artifact path. Its original direction described profiles as role/model/policy selections that resolve into a precise runtime manifest. The current built-in Nix shape has drifted from that intent: it effectively asks authors to write a Manifest-shaped object in Nix.

Current examples include:

- `resources/nix/profile-lib.nix` exposes `mkProfile` and a `mkManifest` helper, where `mkManifest` is currently an identity function.
- `resources/nix/profiles/default.nix` uses `insomnia.mkProfile { manifest = insomnia.mkManifest { ... }; }`.
- The built-in profile currently contains low-level or instance-specific Manifest fields such as `pod.name = "insomnia"`.
- Model policy fields such as high reasoning effort and compaction thresholds are represented as low-level manifest settings rather than being derived from a profile's model/context policy.
- Profile evaluation currently shells out to `nix eval` for Nix artifacts, so the boundary between profile language support and a runtime dependency on the `nix` command is unclear.

The issue is not that profile artifacts are eventually serialized as manifests. The issue is that the authoring API currently exposes the output shape as if the profile itself were a manifest. Profiles should be semantic, and the resolver should perform the manifestization step.

## Goal

Redesign the Nix profile authoring surface so profiles express role/model/tool/context policy at the appropriate level of abstraction, and the manifest resolver turns that semantic profile into the concrete runtime manifest/config used to start a Pod.

This should restore the intended boundary:

- Profile: selectable role/policy/model/context/tool behavior.
- Resolver/manifestization: derives concrete defaults and token thresholds from model metadata and profile policy.
- Runtime manifest/config: low-level concrete values consumed by Pod startup.

## Desired direction

- Remove `mkManifest` from the public/built-in authoring style. A profile should not look like `mkProfile { manifest = mkManifest { ... }; }`.
- Built-in profiles should be written as semantic profiles, not Manifest-shaped blobs.
- Instance-specific values such as `pod.name` must not live in built-in profiles. Pod names come from CLI/TUI/SpawnPod creation, not profile identity.
- Model behavior such as reasoning effort belongs to the profile's model/quality policy and should be manifestized into provider-specific request config by the resolver.
- Compaction and context budgeting should be derived from the selected model's context window and profile policy, e.g. ratios/multipliers/strategy names, rather than hard-coded token thresholds copied into the profile.
- Nix evaluation should be treated as a profile authoring/evaluation mechanism, not as a requirement that the runtime default path always depends on an external `nix` command.

## Acceptance criteria

- Audit the original manifest profiles work item and current implementation to identify where the implementation became Manifest-shaped instead of semantic-profile-shaped.
- Replace the built-in Nix profile shape with a semantic profile API. The exact field names may be redesigned, but they must clearly distinguish profile policy from runtime manifest output.
- Remove `pod.name` and any other instance-specific Pod identity/configuration from built-in profiles.
- Remove `mkManifest` from built-in examples and docs. If a compatibility helper remains internally, it must not be the recommended authoring API and must be justified.
- Implement or adjust the resolver so semantic profile data is manifestized into the concrete runtime manifest/config.
- Ensure model-derived settings are resolved in one place. In particular, reasoning effort and context/compaction policy should be interpreted as profile/model policy and converted into concrete request/compaction settings by the resolver.
- Add or update model catalog/context-window plumbing as needed so compaction thresholds can be derived from the selected model rather than duplicated as raw profile constants.
- Decide and document the Nix evaluator boundary:
  - built-in/default profiles must not require the external `nix` command at normal runtime unless that dependency is deliberately accepted and documented;
  - user/project Nix profiles may use `nix eval` if no lightweight in-process evaluator is chosen, but diagnostics must clearly state that Nix is required for Nix-authored profiles;
  - do not silently make all profile selection depend on a missing or slow `nix` binary.
- Investigate whether a lightweight embedded evaluator is practical enough for the supported Nix subset. If it is not, document why and keep the external-command dependency isolated to Nix-authored profile evaluation.
- Preserve previous profile selection semantics where still relevant: built-in/user/project profile discovery, default profile selection, source-qualified selectors, ambiguity errors, and manifest cascade removal.
- Update docs/tests so the examples present profiles as semantic policy, not manifests written in Nix syntax.
- Add tests covering:
  - built-in profile manifestization without `pod.name`;
  - semantic compaction policy derived from model context window;
  - reasoning/model policy manifestization;
  - missing `nix` command behavior for user/project Nix profiles, if external evaluation remains;
  - no regression in profile discovery/default/source-qualified selection.
- Run focused validation for the manifest crate and any affected pod/tui/client paths, plus `./tickets.sh doctor` and `git diff --check`.

## Non-goals

- Do not reintroduce manifest cascade or manifest overlay selection as a replacement for profiles.
- Do not turn Nix profiles into a general low-level manifest DSL.
- Do not add profile alias registry complexity back unless a separate ticket re-justifies it.
- Do not implement encrypted secret storage here; keep it in the existing encrypted secrets work item.
- Do not require solving every possible provider-specific model option in this ticket; implement the minimum necessary semantic-to-runtime mapping and leave explicit follow-ups for broader model policy coverage.


---
