packwright 0.1.0__py3-none-any.whl

packwright/core/intake_contract.py

@@ -0,0 +1,105 @@
+from pathlib import Path
+
+
+INTERVIEWER_PROMPT_TEMPLATE = """# Packwright Character Draft Interviewer
+
+You are the LLM intake normalizer for Packwright.
+
+Your job is to interview the user and produce one canonical `CharacterIntake` YAML document. Do not generate adapter files yourself. The deterministic compiler will do that after the user confirms the YAML.
+
+## Interview Rules
+
+- Ask one concise question at a time.
+- Do not use a fixed questionnaire. Ask only what is needed for this user's character.
+- If an answer is unrelated, ambiguous, too broad, or only partially answers the question, ask a targeted follow-up.
+- Normalize casual wording into clean fields. For example, "叫 Alice 吧" should become `name: Alice`, not the full phrase.
+- Preserve the user's intent and flavor, but make the YAML professional and compilable.
+- Keep relationship, durable memory, and runtime state separate.
+- Map the character to an archetype only when clear; otherwise default to `productivity`.
+- Do not ask users to choose implementation terms such as Emotion Engine, light, always, or paused.
+- Ask relationship continuity in plain language: "你希望这个角色的关系连续性到什么程度？A. 只做事，不维护情绪关系；B. 有温度，但只记重要偏好；C. 更像长期陪伴，会持续记住相处细节。"
+- If the user asks what the choice means internally, explain the rough cost: B is lightweight selective continuity, while C is more active continuity and can use more context over time.
+- Do not overfit the character into a generic assistant. The result should feel like a specific working presence.
+- Before finalizing, show a short summary and ask the user to confirm or correct it.
+
+## Minimum Information To Resolve
+
+You need enough information to fill:
+
+- `name`: short character name.
+- `slug`: lowercase ASCII path slug; use a readable transliteration or short English handle when `name` is not Latin script.
+- `user_name`: how the character should refer to the user.
+- `relationship`: compact relationship label, such as work partner, editor, coach, research partner, secretary, companion-style partner.
+- `archetype`: one of `productivity`, `learning-coach`, `companion`, `creator`, or `operations`.
+- `role`: one clear sentence describing what this character is for.
+- `primary_work`: 2-6 concrete work areas.
+- `voice`: compact style description.
+- `avoid`: concrete tones or behaviors to avoid.
+- `traits`: 2-6 stable traits.
+- `relationship_continuity`: one of `task_only`, `warm_selective`, or `close_continuous`.
+
+Default `user_name` to `{user_name}` if the user does not specify another name.
+
+## Field Guidance
+
+- `name` should be just the name. Remove phrases like "叫", "吧", "let's call her", "maybe".
+- `slug` should use lowercase letters, numbers, and hyphens only, such as `system` or `media-editor`.
+- `relationship` should not include "is my" or other sentence fragments.
+- `archetype` should describe the default memory and work pattern, not the personality. Use `creator` for media/content roles, `learning-coach` for teaching/training, `companion` for relationship-oriented continuity, `operations` for recurring maintenance, and `productivity` otherwise.
+- `role` should be grammatical and specific.
+- `primary_work` should be concrete tasks, not vague traits.
+- `voice` should include positive style guidance.
+- `avoid` should include negative style guidance and boundaries.
+- `traits` should be stable character traits, not current tasks.
+- If the user wants only practical task execution, choose `task_only`.
+- If the user wants warmth, reminders, care, or light teasing but only important preferences remembered, choose `warm_selective`.
+- If the user wants stronger long-term companionship and ongoing relationship continuity, choose `close_continuous`.
+- If the user is unsure, choose `warm_selective` as the low-risk default.
+- Do not add runtime mode fields to the YAML. The deterministic compiler maps relationship continuity to the appropriate runtime behavior.
+
+## Output Contract
+
+After confirmation, output only this YAML shape:
+
+```yaml
+version: "0.1"
+kind: CharacterIntake
+character:
+  name: Alice
+  slug: alice
+  user_name: {user_name}
+  relationship: media work partner
+  archetype: creator
+  role: "{user_name}'s media planning and publishing work partner."
+  voice: direct, proactive about risks, occasionally sharp and playful, but not cruel
+  avoid:
+    - bland assistant tone
+    - excessive politeness
+    - mechanical audit-log replies
+    - cruelty or personal attacks
+  primary_work:
+    - plan media topics
+    - polish copy
+    - develop cover and title ideas
+    - prepare content for final publishing
+  relationship_continuity: warm_selective
+  traits:
+    - direct
+    - perceptive
+    - playful
+    - editorially practical
+```
+
+Do not include Markdown around the final YAML unless the user asks.
+"""
+
+
+def render_interviewer_prompt(user_name="the user"):
+    return INTERVIEWER_PROMPT_TEMPLATE.format(user_name=user_name or "the user")
+
+
+def write_interviewer_prompt(path, user_name="the user"):
+    output_path = Path(path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(render_interviewer_prompt(user_name=user_name), encoding="utf-8")
+    return output_path

packwright/core/knowledge_contract.py

@@ -0,0 +1,212 @@
+import json
+from pathlib import Path
+
+
+KNOWLEDGE_ROOT = "knowledge"
+SOURCES_ROOT = "sources"
+KNOWLEDGE_INDEX = "knowledge/index.md"
+KNOWLEDGE_MANIFEST = "knowledge/manifest.json"
+SOURCE_MANIFESTS = (
+    "sources/local/manifest.json",
+    "sources/notion/manifest.json",
+    "sources/repos/manifest.json",
+    "sources/web/manifest.json",
+)
+KNOWLEDGE_SCHEMA = "packwright-knowledge-manifest/v1"
+SOURCE_SCHEMA = "packwright-source-manifest/v1"
+MAX_KNOWLEDGE_INDEX_LINES = 200
+MAX_DOMAIN_INDEX_LINES = 300
+
+
+def knowledge_required_dirs():
+    return (
+        KNOWLEDGE_ROOT,
+        SOURCES_ROOT,
+        "sources/local",
+        "sources/notion",
+        "sources/repos",
+        "sources/web",
+    )
+
+
+def knowledge_artifacts():
+    return (KNOWLEDGE_INDEX, KNOWLEDGE_MANIFEST, *SOURCE_MANIFESTS)
+
+
+def knowledge_files():
+    files = {
+        KNOWLEDGE_INDEX: knowledge_index_text(),
+        KNOWLEDGE_MANIFEST: json.dumps(empty_knowledge_manifest(), indent=2, sort_keys=True) + "\n",
+    }
+    for rel_path in SOURCE_MANIFESTS:
+        provider = Path(rel_path).parent.name
+        files[rel_path] = json.dumps(empty_source_manifest(provider), indent=2, sort_keys=True) + "\n"
+    return files
+
+
+def knowledge_index_text():
+    return (
+        "# Knowledge Recall Index\n\n"
+        "Use this file only when a request needs reusable domain knowledge beyond current project state, todos, or source lookup.\n\n"
+        "Do not load every note by default. Use this file as a short routing block, then read the selected domain index or note.\n\n"
+        "## Loading Rules\n\n"
+        "1. Read `memory/index.md` first for local memory routing.\n"
+        "2. If the request needs reusable models, principles, or domain patterns, read this file.\n"
+        "3. Match the request against domain entries below.\n"
+        "4. Read the smallest useful note set.\n"
+        "5. Follow `source_refs` only when factual evidence, citation, or source verification matters.\n\n"
+        "## Domains\n\n"
+        "No reviewed knowledge notes have been recorded yet.\n"
+    )
+
+
+def empty_knowledge_manifest():
+    return {
+        "schema": KNOWLEDGE_SCHEMA,
+        "generated": False,
+        "updated": None,
+        "notes": [],
+    }
+
+
+def empty_source_manifest(provider):
+    return {
+        "schema": SOURCE_SCHEMA,
+        "provider": provider,
+        "updated": None,
+        "sources": {},
+    }
+
+
+def knowledge_feature():
+    return {
+        "root": KNOWLEDGE_ROOT,
+        "recall_index": KNOWLEDGE_INDEX,
+        "manifest": KNOWLEDGE_MANIFEST,
+        "sources_root": SOURCES_ROOT,
+        "source_manifests": list(SOURCE_MANIFESTS),
+        "loading_policy": "explicit_gate_then_smallest_useful_note_set",
+        "status": "scaffold",
+    }
+
+
+def knowledge_entry_lines(prefix=""):
+    return [
+        f"{prefix}Read `knowledge/index.md` only when the task needs reusable domain knowledge beyond current memory or source lookup.",
+        f"{prefix}Use `knowledge/**/*.md` for reviewed reusable models and patterns; do not put current project status or todos there.",
+        f"{prefix}Use `sources/*/manifest.json` for provenance; source manifests are not runtime knowledge bodies.",
+    ]
+
+
+def knowledge_manifest_diagnostics(root_dir):
+    root_dir = Path(root_dir)
+    issues = []
+    manifest_path = root_dir / KNOWLEDGE_MANIFEST
+    manifest = _read_json(manifest_path, issues, "knowledge_manifest_invalid")
+    source_manifests = {}
+    for rel_path in SOURCE_MANIFESTS:
+        data = _read_json(root_dir / rel_path, issues, "source_manifest_invalid")
+        if isinstance(data, dict):
+            source_manifests[Path(rel_path).parent.name] = data.get("sources", {})
+    if isinstance(manifest, dict):
+        issues.extend(_knowledge_notes_diagnostics(root_dir, manifest, source_manifests))
+    issues.extend(_knowledge_index_diagnostics(root_dir))
+    return issues
+
+
+def _knowledge_notes_diagnostics(root_dir, manifest, source_manifests):
+    issues = []
+    notes = manifest.get("notes", [])
+    if not isinstance(notes, list):
+        return [_issue("knowledge_manifest_notes_invalid", KNOWLEDGE_MANIFEST, "knowledge manifest notes must be a list")]
+    for note in notes:
+        if not isinstance(note, dict):
+            issues.append(_issue("knowledge_manifest_note_invalid", KNOWLEDGE_MANIFEST, "knowledge manifest notes must be objects"))
+            continue
+        path = note.get("path")
+        if not isinstance(path, str) or not path.startswith("knowledge/") or ".." in Path(path).parts:
+            issues.append(_issue("knowledge_note_path_invalid", KNOWLEDGE_MANIFEST, "knowledge note path must stay under knowledge/"))
+            continue
+        note_path = root_dir / path
+        if not note_path.is_file():
+            issues.append(_issue("knowledge_note_missing", path, "knowledge note listed in manifest is missing"))
+            continue
+        frontmatter = _frontmatter(note_path)
+        for field in ("id", "domain", "type", "status", "source_refs"):
+            if field not in frontmatter:
+                issues.append(_issue("knowledge_note_frontmatter_missing", path, f"knowledge note frontmatter missing {field}"))
+        for ref in _note_source_refs(frontmatter):
+            provider, _, key = ref.partition(":")
+            if not provider or not key or key not in source_manifests.get(provider, {}):
+                issues.append(_issue("knowledge_source_ref_unresolved", path, f"source ref is unresolved: {ref}"))
+    return issues
+
+
+def _knowledge_index_diagnostics(root_dir):
+    issues = []
+    index_path = root_dir / KNOWLEDGE_INDEX
+    if not index_path.is_file():
+        return issues
+    lines = index_path.read_text(encoding="utf-8").splitlines()
+    if len(lines) > MAX_KNOWLEDGE_INDEX_LINES:
+        issues.append(_issue("knowledge_recall_index_too_long", KNOWLEDGE_INDEX, "knowledge recall index is too long"))
+    for line in lines:
+        marker = "Note: `"
+        if marker not in line:
+            continue
+        rel_path = line.split(marker, 1)[1].split("`", 1)[0]
+        if rel_path and not (root_dir / rel_path).is_file():
+            issues.append(_issue("knowledge_index_note_missing", KNOWLEDGE_INDEX, f"index points to missing note: {rel_path}"))
+    for domain_index in (root_dir / KNOWLEDGE_ROOT).glob("*/index.md"):
+        count = len(domain_index.read_text(encoding="utf-8").splitlines())
+        if count > MAX_DOMAIN_INDEX_LINES:
+            issues.append(_issue("knowledge_domain_index_too_long", str(domain_index.relative_to(root_dir)), "knowledge domain index is too long"))
+    return issues
+
+
+def _read_json(path, issues, issue_id):
+    if not path.is_file():
+        issues.append(_issue("knowledge_scaffold_missing_file", str(path), "required knowledge scaffold file is missing"))
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        issues.append(_issue(issue_id, str(path), f"invalid JSON: {exc}"))
+        return None
+
+
+def _frontmatter(path):
+    text = path.read_text(encoding="utf-8")
+    if not text.startswith("---\n"):
+        return {}
+    end = text.find("\n---", 4)
+    if end == -1:
+        return {}
+    result = {}
+    current = None
+    for raw_line in text[4:end].splitlines():
+        line = raw_line.rstrip()
+        if not line:
+            continue
+        if line.startswith("  - ") and current:
+            result.setdefault(current, []).append(line[4:].strip())
+            continue
+        if ":" in line:
+            key, value = line.split(":", 1)
+            current = key.strip()
+            value = value.strip()
+            result[current] = value if value else []
+    return result
+
+
+def _note_source_refs(frontmatter):
+    refs = frontmatter.get("source_refs", [])
+    if isinstance(refs, list):
+        return refs
+    if isinstance(refs, str) and refs:
+        return [refs]
+    return []
+
+
+def _issue(issue_id, path, message):
+    return {"id": issue_id, "path": path, "message": message}

packwright/core/loader.py

@@ -0,0 +1,35 @@
+from pathlib import Path
+
+import yaml
+
+from .errors import PackwrightValidationError
+
+
+def load_mechanism(path):
+    """Load a character mechanism YAML document from disk.
+
+    A directory input resolves to `<directory>/mechanism.yaml`.
+    """
+    input_path = Path(path)
+    mechanism_path = input_path / "mechanism.yaml" if input_path.is_dir() else input_path
+    try:
+        raw = mechanism_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise PackwrightValidationError([f"cannot read mechanism file {mechanism_path}: {exc}"])
+
+    try:
+        data = yaml.safe_load(raw)
+    except yaml.YAMLError as exc:
+        raise PackwrightValidationError([f"invalid YAML in {mechanism_path}: {exc}"])
+
+    if data is None:
+        data = {}
+    if not isinstance(data, dict):
+        raise PackwrightValidationError([f"mechanism root must be a mapping in {mechanism_path}"])
+
+    data = dict(data)
+    data["source"] = {
+        "path": str(mechanism_path),
+        "base_dir": str(mechanism_path.parent),
+    }
+    return data

packwright/core/memory_projection.py

@@ -0,0 +1,126 @@
+import re
+
+from .naming import character_slug, reference_prefix, save_context_skill_path
+
+
+def project_memory_file(mechanism, adapter, rel_path, text):
+    """Project portable memory text into adapter-specific runtime wording."""
+    if rel_path == "memory/index.md":
+        return _project_memory_index(mechanism, adapter, text)
+    if rel_path == "memory/pinned.md":
+        return _project_pinned_memory(mechanism, adapter, text)
+    if rel_path == "memory/source-map.md":
+        return _project_source_map(mechanism, adapter, text)
+    return text
+
+
+def adapter_entry_path(mechanism, adapter):
+    if adapter == "codex":
+        return "AGENTS.md"
+    if adapter == "claude-code":
+        return "CLAUDE.md"
+    if adapter == "cursor":
+        return f".cursor/rules/{character_slug(mechanism)}.mdc"
+    return "platform entry file"
+
+
+def _project_memory_index(mechanism, adapter, text):
+    entry = adapter_entry_path(mechanism, adapter)
+    text = re.sub(
+        r"- Stable identity, voice, and default work rules -> `[^`]+`(?: or equivalent platform entry file)?",
+        f"- Stable identity, voice, and default work rules -> `{entry}`",
+        text,
+    )
+    emotion_owner = (
+        "- Dynamic emotion state and compact emotion history -> `.emotion-engine/codex-state.json` when enabled"
+        if adapter == "codex"
+        else "- Dynamic emotion state and compact emotion history -> adapter-specific runtime state when installed; "
+        "`memory/emotion-state.json.example` is the portable reference shape"
+    )
+    text = re.sub(
+        r"- Dynamic emotion state and compact emotion history -> .+",
+        emotion_owner,
+        text,
+    )
+    return text
+
+
+def _project_pinned_memory(mechanism, adapter, text):
+    entry = adapter_entry_path(mechanism, adapter)
+    text = re.sub(
+        r"Use `memory/index\.md` for routing, `[^`]+` for stable behavior,",
+        f"Use `memory/index.md` for routing, `{entry}` for stable behavior,",
+        text,
+    )
+    return re.sub(
+        r"Use `memory/index\.md` for routing, the platform entry file for stable behavior,",
+        f"Use `memory/index.md` for routing, `{entry}` for stable behavior,",
+        text,
+    )
+
+
+def _project_source_map(mechanism, adapter, text):
+    label = _adapter_label(adapter)
+    entry = adapter_entry_path(mechanism, adapter)
+    save_context = save_context_skill_path(mechanism, adapter)
+    save_context_name = "save-context rule" if adapter == "cursor" else "save-context skill"
+    update_policy = f"{reference_prefix(mechanism, adapter)}/emotion/update-policy.yaml"
+
+    text = re.sub(
+        r"- Current (Codex|Claude Code|Cursor) entry -> `[^`]+`",
+        f"- Current {label} entry -> `{entry}`",
+        text,
+    )
+    text = re.sub(
+        r"- Current save-context (skill|rule) -> `[^`]+`",
+        f"- Current {save_context_name} -> `{save_context}`",
+        text,
+    )
+    text = re.sub(
+        r"- Emotion update policy reference -> `[^`]+/emotion/update-policy\.yaml`",
+        f"- Emotion update policy reference -> `{update_policy}`",
+        text,
+    )
+    if adapter == "codex":
+        text = re.sub(
+            r"- Codex sidecar skill -> not installed in this [^\n]+ target",
+            "- Current Codex sidecar skill -> `.agents/skills/emotion-engine-codex/SKILL.md`",
+            text,
+        )
+        text = re.sub(
+            r"- Codex sidecar helper -> not installed in this [^\n]+ target",
+            "- Current Codex sidecar helper -> `.agents/skills/emotion-engine-codex/scripts/emotion_engine_utils.py`",
+            text,
+        )
+        text = re.sub(
+            r"- Project-local Emotion Engine state snapshot -> `\.emotion-engine/codex-state\.json` "
+            r"\(not active without an adapter sidecar\)",
+            "- Project-local Emotion Engine runtime state -> `.emotion-engine/codex-state.json`",
+            text,
+        )
+    else:
+        text = re.sub(
+            r"- Current Codex sidecar skill -> `\.agents/skills/emotion-engine-codex/SKILL\.md`",
+            f"- Codex sidecar skill -> not installed in this {label} target",
+            text,
+        )
+        text = re.sub(
+            r"- Current Codex sidecar helper -> `\.agents/skills/emotion-engine-codex/scripts/emotion_engine_utils\.py`",
+            f"- Codex sidecar helper -> not installed in this {label} target",
+            text,
+        )
+        text = re.sub(
+            r"- Project-local Emotion Engine runtime state -> `\.emotion-engine/codex-state\.json`",
+            "- Project-local Emotion Engine state snapshot -> `.emotion-engine/codex-state.json` "
+            "(not active without an adapter sidecar)",
+            text,
+        )
+    return text
+
+
+def _adapter_label(adapter):
+    return {
+        "codex": "Codex",
+        "claude-code": "Claude Code",
+        "cursor": "Cursor",
+    }.get(adapter, adapter)

packwright/core/naming.py

@@ -0,0 +1,98 @@
+import re
+import warnings
+
+
+SLUG_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+
+
+def slugify(value, default="character"):
+    text = str(value or "").strip().lower()
+    slug = re.sub(r"[^a-z0-9]+", "-", text).strip("-")
+    if text and not slug:
+        warnings.warn(
+            f"{value!r} cannot produce an ASCII slug; using {default!r}. "
+            "Provide an explicit --slug to avoid collisions.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+    return slug or default
+
+
+def normalize_slug(value, default="character"):
+    return slugify(value, default=default)
+
+
+def is_valid_slug(value):
+    return isinstance(value, str) and bool(SLUG_PATTERN.fullmatch(value))
+
+
+def character_name(mechanism):
+    identity = mechanism.get("identity", {}) if isinstance(mechanism, dict) else {}
+    metadata = mechanism.get("metadata", {}) if isinstance(mechanism, dict) else {}
+    return identity.get("name") or metadata.get("name") or "Character"
+
+
+def character_slug(mechanism):
+    identity = mechanism.get("identity", {}) if isinstance(mechanism, dict) else {}
+    if identity.get("slug"):
+        return normalize_slug(identity["slug"])
+    metadata = mechanism.get("metadata", {}) if isinstance(mechanism, dict) else {}
+    if metadata.get("slug"):
+        return normalize_slug(metadata["slug"])
+    name = identity.get("name")
+    if name:
+        return slugify(name)
+    return slugify(metadata.get("name"))
+
+
+def character_user_name(mechanism):
+    identity = mechanism.get("identity", {}) if isinstance(mechanism, dict) else {}
+    if identity.get("user_name"):
+        return identity["user_name"]
+
+    role = identity.get("role", "")
+    match = re.match(r"^([^\s'’]+)(?:'s|’s)\b", role)
+    if match:
+        return match.group(1)
+    match = re.match(r"^([^\s的]{1,64})的", role)
+    if match:
+        return match.group(1)
+    return "the user"
+
+
+def character_voice_summary(mechanism):
+    identity = mechanism.get("identity", {}) if isinstance(mechanism, dict) else {}
+    return identity.get("voice_summary") or "Calm, direct, perceptive, and lightly warm."
+
+
+def character_mission(mechanism):
+    identity = mechanism.get("identity", {}) if isinstance(mechanism, dict) else {}
+    if identity.get("mission"):
+        return identity["mission"]
+    name = character_name(mechanism)
+    user_name = character_user_name(mechanism)
+    return f"{name} helps {user_name} preserve intent, notice stale assumptions, and turn messy work into concrete next steps."
+
+
+def save_context_skill_path(mechanism, adapter):
+    from .adapter_layout import save_context_artifact
+
+    slug = character_slug(mechanism)
+    if adapter in {"codex", "claude-code", "cursor"}:
+        return save_context_artifact(adapter, slug)
+    return f"skills/{slug}-save-context/SKILL.md"
+
+
+def reference_prefix(mechanism, adapter):
+    slug = character_slug(mechanism)
+    if adapter == "codex":
+        return f".codex/{slug}/references"
+    if adapter == "claude-code":
+        return f".claude/{slug}/references"
+    if adapter == "cursor":
+        return f".cursor/{slug}/references"
+    return f"{slug}/references"
+
+
+def durable_memory_source(mechanism):
+    return f"{character_slug(mechanism)}_local_files"

packwright/core/pack_metadata.py

@@ -0,0 +1,100 @@
+import hashlib
+import json
+import copy
+from pathlib import Path
+
+from .errors import PackwrightValidationError
+from .path_safety import resolve_source_path, validate_relative_path
+
+
+METADATA_ROOT = ".packwright"
+SPEC_PATH = f"{METADATA_ROOT}/spec.json"
+LOCK_PATH = f"{METADATA_ROOT}/lock.json"
+RECEIPT_PATH = f"{METADATA_ROOT}/checker-receipt.json"
+METADATA_ARTIFACTS = (SPEC_PATH, LOCK_PATH, RECEIPT_PATH)
+
+
+def embed_pack_metadata(pack, resolved, checker_receipt):
+    """Return a pack with a portable canonical snapshot and build receipts."""
+    enriched = dict(pack)
+    manifest = json.loads(enriched["manifest.json"])
+    manifest["source_mechanism"] = SPEC_PATH
+    manifest["packwright"] = {
+        "schema": "packwright-pack-metadata/v1",
+        "spec": SPEC_PATH,
+        "lock": LOCK_PATH,
+        "checker_receipt": RECEIPT_PATH,
+    }
+    snapshot, source_files = _portable_snapshot(resolved)
+    artifacts = set(manifest.get("artifacts", []))
+    artifacts.update(METADATA_ARTIFACTS)
+    artifacts.update(source_files)
+    manifest["artifacts"] = sorted(artifacts)
+    enriched.update(source_files)
+    enriched[SPEC_PATH] = _json_text(snapshot)
+    enriched[RECEIPT_PATH] = _json_text(checker_receipt)
+    manifest_text = _json_text(manifest)
+    enriched["manifest.json"] = manifest_text
+    locked = {
+        path: hashlib.sha256(content.encode("utf-8")).hexdigest()
+        for path, content in sorted(enriched.items())
+        if path != LOCK_PATH
+    }
+    enriched[LOCK_PATH] = _json_text({
+        "schema": "packwright-lock/v1",
+        "artifacts": locked,
+    })
+    return enriched
+
+
+def load_embedded_spec(root):
+    """Load the resolved snapshot with target-root-relative validation context."""
+    root = Path(root)
+    path = resolve_source_path(root, SPEC_PATH, "embedded mechanism spec")
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise PackwrightValidationError([f"invalid embedded mechanism spec {path}: {exc}"])
+    if not isinstance(data, dict):
+        raise PackwrightValidationError([f"embedded mechanism spec must be a mapping: {path}"])
+    data["source"] = {
+        "path": str(path),
+        "base_dir": str(root / METADATA_ROOT / "source"),
+        "fallback_roots": [str(root)],
+    }
+    return data
+
+
+def _json_text(value):
+    return json.dumps(value, indent=2, sort_keys=True) + "\n"
+
+
+def _portable_snapshot(resolved):
+    snapshot = copy.deepcopy(resolved)
+    base = Path(resolved.get("source", {}).get("base_dir", "."))
+    files = {}
+
+    def visit(value):
+        if isinstance(value, dict):
+            for key, item in list(value.items()):
+                if key == "source":
+                    continue
+                if key == "path" or key.endswith("_path"):
+                    if isinstance(item, str):
+                        relative = validate_relative_path(item, f"mechanism source path {key}")
+                        candidate = base.resolve() / relative
+                        if candidate.exists():
+                            candidate = resolve_source_path(base, item, f"mechanism source path {key}")
+                            # Keep spec paths stable because adapters also use them
+                            # as destination names, while storing their source bytes
+                            # under a private metadata root.
+                            files[f"{METADATA_ROOT}/source/{relative.as_posix()}"] = candidate.read_text(encoding="utf-8")
+                else:
+                    visit(item)
+        elif isinstance(value, list):
+            for item in value:
+                visit(item)
+
+    visit(snapshot)
+    snapshot["source"] = {"path": SPEC_PATH, "base_dir": "."}
+    return snapshot, files