[research] Describe embeds and snippets

docs/designs/snippets/PR.md

@@ -0,0 +1,87 @@
+# PR Draft: Snippets + Legacy Applications (Entity-Specific Design Pass)
+
+Status: draft  
+Last updated: 2026-02-11
+
+## Title
+
+`chore(docs): define snippet/application compatibility contract for legacy-backed entities`
+
+## Why
+
+This branch already contains snippet-aware behavior in multiple code paths, but the contract is implicit and spread across router/service/UI layers.
+
+This PR documents the implementation reality and proposed compatibility contract before further code changes.
+
+## What Changed in This PR
+
+- Added design docs under `docs/designs/snippets/`.
+- Tightened `RFC.md` to be implementation-specific with concrete file-level behavior.
+- Added explicit snippet format contract in RFC (embed shapes, token grammar, path precedence, resolution flow, guardrails).
+- Kept `PRD.md` intentionally higher-level for later product iteration.
+
+## Files Added/Updated
+
+- `docs/designs/snippets/README.md`
+- `docs/designs/snippets/PRD.md`
+- `docs/designs/snippets/RFC.md`
+- `docs/designs/snippets/PR.md`
+
+## Implementation Evidence Captured in RFC
+
+1. **Type system**
+`AppType.SNIPPET` exists and is tagged as `snippet`.  
+Source: `api/oss/src/models/shared_models.py:68`
+
+2. **API surface**
+`GET /apps` accepts `snippets=exclude|include|only` (default `exclude`).  
+Source: `api/oss/src/routers/app_router.py:352`
+
+3. **DB behavior**
+`exclude` and `only` are implemented as explicit `AppType.SNIPPET` filters.  
+Source: `api/oss/src/services/db_manager.py:1858`
+
+4. **Resolver aliasing**
+Embed references support snippet/application alias pairs across artifact, variant, and revision keys.  
+Source: `api/oss/src/services/embeds_service.py:816`
+
+5. **Legacy fallback**
+Revision references may backfill variant references for compatibility.  
+Source: `api/oss/src/services/embeds_service.py:849`
+
+6. **Boundary detail**
+Internal fetch boundaries still pass `artifact_ref` as `application_ref`.  
+Source: `api/oss/src/services/embeds_service.py:148`
+
+7. **UI behavior**
+Endpoint code snippet generation is functionally compatible but still app-first in route/copy.  
+Source: `web/oss/src/pages/w/[workspace_id]/p/[project_id]/apps/[app_id]/endpoints/index.tsx:11`
+
+8. **Format + resolver contract**
+RFC now documents exact snippet format and embed dereferencing behavior used by `/variants/configs/fetch` and `/variants/configs/resolve`.  
+Source: `api/oss/src/routers/variants_router.py:786`
+
+## Scope of This PR
+
+- Documentation and design alignment only.
+- No runtime logic changes.
+- No API schema changes.
+
+## Suggested Follow-Up Code PRs (Separate)
+
+1. Add contract tests for alias mapping and fallback behavior.
+2. Add telemetry around alias family usage and fallback-path usage.
+3. Harden user-facing naming in UI copy where safe, without breaking routes.
+
+## Reviewer Checklist
+
+- Validate that RFC accurately reflects current branch implementation.
+- Confirm compatibility contract matches intended near-term behavior.
+- Confirm open questions are the right ones before implementation PRs.
+
+## Open Questions
+
+- Should `snippets` default stay `exclude` or eventually move to `include`?
+- Should revision-only alias fallback remain permissive or become strict over time?
+- Which SDK/client versions require explicit compatibility/deprecation communication?
+- What is the minimum telemetry period before deciding on deprecation milestones?

docs/designs/snippets/PRD.md

@@ -0,0 +1,176 @@
+# PRD: Composable Config Embedding + Snippets Profile
+
+Status: draft  
+Owner: TBD  
+Last updated: 2026-02-11
+
+## Product Intent
+
+Enable composable configurations where teams can define reusable building blocks once (instructions, guardrails, model presets, schemas, tool settings, message snippets, subagent configs), commit and test them independently, and compose them by reference into higher-level configurations.
+
+Composition must support both pinned-version references and floating/latest references, with clear UX to inspect and safely change what is being referenced.
+
+## Context and Opportunity
+
+Teams want to:
+
+- centralize shared configuration content instead of copy/pasting across apps,
+- evolve nested pieces independently with their own lifecycle,
+- compose larger behaviors from smaller tested components,
+- choose whether a reference tracks latest or a specific version.
+
+This is not only for snippet-like text content; it applies to any reusable configuration object.
+
+## Problem Statement
+
+Without a productized embedding system, users cannot reliably compose configurations across string and JSON contexts with predictable dereferencing, insertion, and resolution semantics.
+
+Without strong reference UX, users also cannot safely understand or change composition over time:
+
+- they need to see the reference itself and what it resolves to,
+- they need to compare current target vs candidate target before applying a change,
+- they need multiple views for editing/debugging (raw/pretty, resolved/unresolved).
+
+## Scope Split (Design Framing)
+
+## Track A: Embedding System
+
+A product-level contract for reference declaration, selector semantics, dereference, insertion, and resolution for any embeddable configuration object.
+
+## Track B: Snippets Profile
+
+A specific profile on top of Track A: non-runnable, message-oriented reusable content with a default selector behavior optimized for common snippet use.
+
+## Goals
+
+1. Support nested composition in both string and JSON/object contexts.
+2. Provide unique and parseable references with selector semantics.
+3. Support both pinned and floating (latest) reference targeting.
+4. Standardize dereference/resolve behavior with deterministic outcomes.
+5. Provide UX that makes reference edits safe and explainable.
+6. Define snippets as one embeddable profile without limiting the system to snippets.
+
+## Out of Scope (This PRD Phase)
+
+- Branch-specific API/path/entity naming decisions.
+- Full migration and deprecation sequencing across legacy contracts.
+- Final visual design details for every screen state.
+
+Implementation mechanics remain in RFC(s).
+
+## Target Users
+
+- Builders composing runtime configs from reusable components.
+- Teams curating centralized shared resources (instructions, guardrails, snippets, schemas, model presets).
+- Platform teams maintaining config composition across API/SDK/UI.
+
+## Core Use Cases
+
+1. Embed selected content into a string field.
+2. Embed selected content into a JSON key/node.
+3. Compose recursively (A references B, B references C).
+4. Use snippet content as a default message source in larger runnable configs.
+5. Reuse non-snippet artifact types through the same mechanism (subagents, guardrails, models, schemas, tools).
+6. Switch a reference target (version/variant) with a pre-apply diff preview.
+7. Inspect both unresolved and resolved states of the same config.
+
+## Product Requirements
+
+## A) Generic Embedding System Requirements
+
+1. Support both embedding forms:
+- string-embedded reference markers,
+- JSON/object embedding markers.
+
+2. Define a canonical reference shape that is unambiguous and parseable.
+
+3. Define selector behavior for extracting a sub-part of referenced content.
+
+4. Define selector precedence rules consistently across embedding forms.
+
+5. Support recursive resolution with explicit guardrails (depth, cycle, count limits).
+
+6. Preserve type intent:
+- object embeddings inject structured values,
+- string embeddings inject string output with explicit conversion rules.
+
+7. Define policy behavior for missing refs, invalid selectors, cycles, and depth overflow (e.g., placeholder vs strict errors).
+
+8. Support target strategy per reference:
+- pinned target (specific version/revision),
+- floating target (latest/default moving target).
+
+## B) Reference UX Requirements
+
+1. Users can inspect reference metadata and resolved value side by side.
+
+2. Users can preview the resolved output before saving/applying changes.
+
+3. When changing reference target (e.g., version/variant), users can see a before/after diff before apply.
+
+4. Users can view configuration in at least four modes:
+- raw + unresolved,
+- raw + resolved,
+- pretty + unresolved,
+- pretty + resolved.
+
+5. UI clearly indicates when content is resolved from references vs literal local content.
+
+## C) Snippets Profile Requirements
+
+1. A snippet is a non-runnable, reusable message-oriented configuration profile.
+
+2. Snippets can be embedded anywhere Track A supports embedding.
+
+3. Snippets provide a default selector optimized for snippet usage (initially first-message-focused behavior), while allowing explicit override.
+
+4. Snippets are one profile among many embeddable profile types; system capabilities must remain profile-agnostic.
+
+## Non-Functional Requirements
+
+- Deterministic resolution for same inputs and same target versions.
+- Bounded and safe resolver execution.
+- Backward-compatible extension path for additional embeddable profiles.
+- Strong observability for resolution behavior and failures.
+
+## Success Metrics
+
+1. Composition adoption:
+- percentage of saved configs using at least one reference.
+
+2. Multi-context coverage:
+- percentage of surfaces supporting both string and JSON embedding.
+
+3. Reliability:
+- resolution failure rate by class (missing, cycle, depth, selector).
+
+4. Edit safety:
+- percentage of target-change operations that used preview/diff before apply.
+
+5. Profile extensibility:
+- adoption of at least one non-snippet reusable profile type.
+
+## Rollout Plan (Product-Level)
+
+1. Publish generic embedding and reference UX contract.
+2. Publish snippets profile contract on top of generic system.
+3. Expand profile coverage (guardrails, models, schemas, tools, subagents).
+
+## Risks
+
+- Overfitting product semantics to one implementation.
+- Ambiguity between snippet defaults and generic embedding behavior.
+- UX complexity when exposing raw/resolved and multi-mode views.
+
+## Dependencies
+
+- Resolver/parser with deterministic reference extraction and insertion.
+- Versioned storage model for embeddable artifacts.
+- UI components for dual-view rendering and diff preview.
+- API/SDK surfaces exposing consistent resolve and inspect behavior.
+
+## Open Questions
+
+- What is the final canonical reference model for pinned vs floating targets?
+- What is the canonical diff unit for target changes (raw value diff, resolved diff, or both)?
+- Which view mode should be default in editor UX?

docs/designs/snippets/README.md

@@ -0,0 +1,31 @@
+# Snippets Design Docs
+
+Status: draft  
+Last updated: 2026-02-11
+
+## Purpose
+
+This folder contains iterative design docs for the `poc/snippets-using-legacy-apps` work.  
+The branch uses older naming and entities in several places; these docs focus on intent and direction rather than strict legacy naming fidelity.
+
+## Documents
+
+- `PRD.md`: product goals, user problems, requirements, and success criteria.
+- `RFC.md`: technical contract, including snippet embed format, dereferencing, and resolver behavior.
+- `PR.md`: draft pull request narrative/checklist for implementation review.
+
+## Where To Find Snippet Format
+
+- Canonical format and resolver contract: `RFC.md` -> `Snippet Format (Normative for This Branch)`
+
+## Scope
+
+- Define how "snippets" should behave as first-class artifacts.
+- Preserve backward compatibility with legacy "application" terms and flows where needed.
+- Capture unresolved decisions to drive follow-up iterations.
+
+## Open Questions
+
+- Should "snippet" eventually replace "application" in all user-visible surfaces, or remain an alias?
+- Do we want a hard migration timeline away from legacy entities, or long-term dual support?
+- Which compatibility guarantees are required for existing API clients and SDK users?