From a14ee205669b9b2629e8ade373fac27069327c6f Mon Sep 17 00:00:00 2001
From: tmathern <60901087+tmathern@users.noreply.github.com>
Date: Tue, 2 Jun 2026 18:12:57 -0700
Subject: [PATCH] fix: Add bindings

---
 docs/selective-manifests.md | 379 ++++++++++++++++++++++++++++++
 docs/working-stores.md      | 444 ++++++++++++++++++++++++++++++++++++
 pyproject.toml              |   5 +-
 src/c2pa/c2pa.py            |  59 +++++
 tests/test_unit_tests.py    | 353 ++++++++++++++++++++++++++++
 5 files changed, 1238 insertions(+), 2 deletions(-)

diff --git a/docs/selective-manifests.md b/docs/selective-manifests.md
index 37bb0eb7..940f8ca8 100644
--- a/docs/selective-manifests.md
+++ b/docs/selective-manifests.md
@@ -494,6 +494,17 @@ An **ingredient archive** contains the manifest store from an asset that was add
 
 The key difference: a builder archive is a work-in-progress (unsigned). An ingredient archive carries the provenance history of a source asset for reuse as an ingredient in other working stores.
 
+### Producing an ingredient archive
+
+The SDK supports two approaches for producing an ingredient archive. They share the same `.c2pa` binary format and are interchangeable from the consumer side.
+
+| Approach | Entry point | Status |
+| --- | --- | --- |
+| Dedicated ingredient archive APIs | `add_ingredient` then `write_ingredient_archive(id, stream)` | **Recommended** |
+| Read-filter-rebuild pattern | `Builder` + `add_ingredient` + `to_archive`, then `Reader` + manual JSON | **Older pattern** |
+
+For the full contract, see [Single-ingredient archive APIs](./working-stores.md#single-ingredient-archive-apis) in the working stores guide.
+
 ### The ingredients catalog pattern
 
 An **ingredients catalog** is a collection of archived ingredients that can be selected when constructing a final manifest. Each archive holds ingredients; at build time the caller selects only the ones needed.
@@ -557,6 +568,132 @@ with Reader("application/c2pa", archive_stream, context=ctx) as reader:
             new_builder.sign("image/jpeg", source, dest)
 ```
 
+### Dedicated archives API: one ingredient per archive
+
+The producer registers each ingredient on a builder and writes one archive per ingredient, keyed by `instance_id` as unique identifier. The consumer assembles a final Builder instance by loading only the archives it needs via `add_ingredient_from_archive`.
+
+The first argument to `write_ingredient_archive` is the *archive key*: it locates the ingredient on the producer (matched against either `label` or `instance_id`) and becomes the `ingredientIds` value to use on the signing builder. See [Lookup keys and action linking](working-stores.md#lookup-keys-and-action-linking) for the full rules.
+
+> [!NOTE]
+> `"relationship": "componentOf"` is shown explicitly below, but `componentOf` is the default the SDK applies when `relationship` is omitted.
+
+Producer side, build the catalog:
+
+```py
+import io
+from c2pa import Builder
+
+catalog_builder = Builder.from_json(manifest_json)
+with open("photo-A.jpg", "rb") as f:
+    catalog_builder.add_ingredient(
+        {"title": "photo-A.jpg", "relationship": "componentOf", "instance_id": "catalog:ingredient-A"},
+        "image/jpeg", f
+    )
+with open("photo-B.jpg", "rb") as f:
+    catalog_builder.add_ingredient(
+        {"title": "photo-B.jpg", "relationship": "componentOf", "instance_id": "catalog:ingredient-B"},
+        "image/jpeg", f
+    )
+with open("photo-C.jpg", "rb") as f:
+    catalog_builder.add_ingredient(
+        {"title": "photo-C.jpg", "relationship": "componentOf", "instance_id": "catalog:ingredient-C"},
+        "image/jpeg", f
+    )
+
+# One archive per ingredient, keyed by the instance_id used at registration.
+archive_a, archive_b, archive_c = io.BytesIO(), io.BytesIO(), io.BytesIO()
+catalog_builder.write_ingredient_archive("catalog:ingredient-A", archive_a)
+catalog_builder.write_ingredient_archive("catalog:ingredient-B", archive_b)
+catalog_builder.write_ingredient_archive("catalog:ingredient-C", archive_c)
+```
+
+Consumer side, pick one archive and load it:
+
+```py
+final_builder = Builder.from_json(manifest_json)
+archive_b.seek(0)
+final_builder.add_ingredient_from_archive(archive_b)
+
+with open("source.jpg", "rb") as src, open("output.jpg", "w+b") as dst:
+    final_builder.sign(signer, "image/jpeg", src, dst)
+```
+
+The signed output contains exactly the picked ingredient (`photo-B.jpg` here). `archive_a` stays unused.
+
+A single action can link several ingredients loaded this way. With the three archives from the producer above, a `c2pa.placed` action that lists all three ids in `ingredientIds` resolves to three distinct ingredient URLs after signing:
+
+```py
+signing_manifest = {
+    "claim_generator_info": [{"name": "an-application", "version": "0.1.0"}],
+    "assertions": [{
+        "label": "c2pa.actions.v2",
+        "data": {
+            "actions": [{
+                "action": "c2pa.placed",
+                "parameters": {
+                    "ingredientIds": ["catalog:ingredient-A", "catalog:ingredient-B", "catalog:ingredient-C"]
+                }
+            }]
+        }
+    }]
+}
+
+signing_builder = Builder.from_json(signing_manifest)
+for archive in (archive_a, archive_b, archive_c):
+    archive.seek(0)
+    signing_builder.add_ingredient_from_archive(archive)
+
+with open("source.jpg", "rb") as src, open("output.jpg", "w+b") as dst:
+    signing_builder.sign(signer, "image/jpeg", src, dst)
+```
+
+### Legacy catalog: read-filter-rebuild APIs
+
+> [!NOTE]
+> **Legacy approach.** This pattern requires manual JSON parsing and `add_resource` loops to transfer binary data related to ingredients. See [Migration guide](#migration-guide-catalog-pattern) to use the [dedicated ingredient archive APIs](#dedicated-archives-api-one-ingredient-per-archive) instead.
+
+Use this approach when the catalog already exists as a single `.c2pa` builder archive containing many ingredients and you need to pick a subset by reading, filtering, and rebuilding.
+
+#### Migration guide: catalog pattern
+
+Switch to the dedicated ingredient archive APIs: set `instance_id` per ingredient, call `write_ingredient_archive` once per ingredient on the producer, and `add_ingredient_from_archive` on the consumer. No JSON parsing or `add_resource` loops required.
+
+Producer side:
+
+```py
+catalog_builder = Builder.from_json(manifest_json)
+with open("photo-A.jpg", "rb") as f:
+    catalog_builder.add_ingredient(
+        {"title": "photo-A.jpg", "relationship": "componentOf", "instance_id": "catalog:ingredient-A"},
+        "image/jpeg", f
+    )
+with open("photo-B.jpg", "rb") as f:
+    catalog_builder.add_ingredient(
+        {"title": "photo-B.jpg", "relationship": "componentOf", "instance_id": "catalog:ingredient-B"},
+        "image/jpeg", f
+    )
+
+archive_a, archive_b = io.BytesIO(), io.BytesIO()
+catalog_builder.write_ingredient_archive("catalog:ingredient-A", archive_a)
+catalog_builder.write_ingredient_archive("catalog:ingredient-B", archive_b)
+```
+
+Consumer side:
+
+```py
+final_builder = Builder.from_json(manifest_json)
+archive_b.seek(0)
+final_builder.add_ingredient_from_archive(archive_b)
+with open("source.jpg", "rb") as src, open("output.jpg", "w+b") as dst:
+    final_builder.sign(signer, "image/jpeg", src, dst)
+```
+
+Action linking also changes between the two approaches. Legacy catalog code linked ingredients via `label` set on the signing builder's `add_ingredient` JSON; `instance_id` was not accepted. The dedicated archive API accepts the archive key passed to `write_ingredient_archive`, which can be either `label` or `instance_id`. See [Lookup keys and action linking](working-stores.md#lookup-keys-and-action-linking).
+
+#### Choosing between approaches
+
+The legacy read-filter-rebuild APIs fit when the catalog already exists as one multi-ingredient builder archive and the consumer wants a subset of it. The dedicated ingredient archive APIs fit when ingredients are produced and consumed independently: each archive holds exactly one ingredient, and the call sites stay short. Both produce the same signed output.
+
 ### Identifying ingredients in archives
 
 When building an ingredient archive, you can set `instance_id` on the ingredient to give it a stable, caller-controlled identifier. This field survives archiving and signing unchanged, so it can be used to look up a specific ingredient from a catalog archive. The `description` and `informational_URI` fields also survive and can carry additional metadata about the ingredient's origin.
@@ -875,6 +1012,26 @@ with open("ingredient_archive.c2pa", "rb") as archive_file:
     reader.close()
 ```
 
+#### Troubleshooting ingredients to actions linking errors
+
+A signing-time error when linking ingredients to actions failed is:
+
+```text
+Builder.sign failure: Other: assertion-specific error:
+Action ingredientId not found: <some id>
+```
+
+Causes and potential fixes to investigate:
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `Action ingredientId not found: xmp:iid:...` (or any `instance_id` value) | `instance_id` was used as the linking key for an ingredient archive loaded via the legacy path. | Assign a `label` on the signing builder's `add_ingredient` JSON and use that label in `ingredientIds`. |
+| `Action ingredientId not found: <label>` where the label was set only when building the archive | Labels baked into an archive ingredient do not carry through as linking keys for the legacy load path. | Re-assert the same `label` in the signing builder's `add_ingredient` JSON. |
+| `Action ingredientId not found: <label>` where the label is on `add_ingredient` but the action references a different string | Typo or mismatch between `ingredientIds[i]` and the `label` field on the ingredient. | Make the two strings identical. |
+| Sign succeeds but the action's `parameters.ingredients` array is empty in the signed output | The action was kept during a filter/rebuild but the corresponding ingredient was not, or was not linked. | Keep the ingredient and its binary resources alongside the action. Verify that the linking of ingredients and actions uses the correct JSON attributes. |
+
+For the linking rules, see [Linking an archived ingredient to an action](#linking-an-archived-ingredient-to-an-action) above.
+
 ### Merging multiple working stores
 
 > [!NOTE]
@@ -947,6 +1104,228 @@ with Builder({
         builder.sign("image/jpeg", source, dest)
 ```
 
+## Retrieving actions from a working store
+
+Actions are stored in the `c2pa.actions.v2` assertion. Use `Reader` to extract them from a signed asset or an archived `Builder`.
+
+### Reading actions
+
+```py
+import json
+from c2pa import Context, Reader
+
+ctx = Context()
+with open("source.jpg", "rb") as f:
+    reader = Reader("image/jpeg", f, context=ctx)
+    parsed = json.loads(reader.json())
+
+active = parsed["active_manifest"]
+assertions = parsed["manifests"][active].get("assertions", [])
+
+for assertion in assertions:
+    if assertion["label"] == "c2pa.actions.v2":
+        for action in assertion["data"]["actions"]:
+            print("Action:", action["action"])
+            if "description" in action:
+                print("  Description:", action["description"])
+```
+
+### Reading actions from an archive
+
+Use the same approach with format `"application/c2pa"` and an archive stream:
+
+```py
+with open("builder_archive.c2pa", "rb") as archive_file:
+    reader = Reader("application/c2pa", archive_file)
+    # Then parse and iterate assertions as in the example above
+```
+
+### Understanding the manifest tree
+
+`reader.json()` returns a manifest store, a dictionary of manifests keyed by label (a URN like `contentauth:urn:uuid:...`). Conceptually it forms a tree: each manifest has assertions and ingredients; ingredients with `manifest_data` carry their own manifest store, which can have its own ingredients and assertions recursively. The `active_manifest` key indicates the root.
+
+```mermaid
+flowchart TD
+    subgraph Store["Manifest Store"]
+        M1["Active Manifest\n- assertions (including c2pa.actions.v2)\n- ingredients"]
+        M2["Ingredient A's manifest\n- its own c2pa.actions.v2\n- its own ingredients"]
+        M3["Ingredient B's manifest\n- its own c2pa.actions.v2"]
+    end
+    M1 -->|"ingredient A has manifest_data"| M2
+    M1 -->|"ingredient B has manifest_data"| M3
+    M1 -.-|"ingredient C has no manifest_data"| M5["Ingredient C\n(unsigned asset, no provenance)"]
+    M2 -->|"may have its own ingredients..."| M4["...deeper in the tree"]
+
+    style M5 fill:#eee,stroke:#999,stroke-dasharray: 5 5
+```
+
+Not every ingredient has provenance. An unsigned asset added as an ingredient has `title`, `format`, and `relationship`, but no `manifest_data` and no entry in the `"manifests"` dictionary. Walking the tree reveals the full provenance chain: what each actor did at each step, including actions performed and ingredients used.
+
+To walk the tree and find actions at each level:
+
+```py
+import json
+from c2pa import Reader
+
+parsed = json.loads(reader.json())
+active = parsed["active_manifest"]
+active_manifest = parsed["manifests"][active]
+
+# Read the active manifest's actions
+for assertion in active_manifest.get("assertions", []):
+    if assertion["label"] == "c2pa.actions.v2":
+        print("Active manifest actions:")
+        for action in assertion["data"]["actions"]:
+            print(" ", action["action"])
+
+# Walk into each ingredient's manifest
+for ingredient in active_manifest.get("ingredients", []):
+    print("Ingredient:", ingredient["title"])
+
+    if "active_manifest" in ingredient:
+        ing_manifest_label = ingredient["active_manifest"]
+        ing_manifest = parsed["manifests"].get(ing_manifest_label)
+        if ing_manifest:
+            for assertion in ing_manifest.get("assertions", []):
+                if assertion["label"] == "c2pa.actions.v2":
+                    print("  Ingredient's actions:")
+                    for action in assertion["data"]["actions"]:
+                        print("   ", action["action"])
+    else:
+        # This ingredient has no manifest of its own (unsigned asset).
+        print("  (no content credentials)")
+```
+
+## Filtering actions
+
+To remove actions, use the same read-filter-rebuild pattern: **read, pick the ones to keep, create a new Builder**.
+
+```mermaid
+flowchart TD
+    SA["Signed Asset with 3 actions: opened, placed, filtered"] -->|Reader| JSON[Parse JSON]
+    JSON -->|"Keep only opened + placed"| FILT[Filtered actions]
+    FILT -->|"New Builder with 2 actions"| NB[New Builder]
+    NB -->|sign| OUT["New asset with 2 actions only: opened, placed"]
+```
+
+### Basic action filtering
+
+When filtering, remember that the first action must remain `c2pa.created` or `c2pa.opened` for the manifest to be valid. If the first action is removed, a new one must be added.
+
+```py
+import json
+from c2pa import Builder, Context, Reader
+
+ctx = Context()
+with open("source.jpg", "rb") as f:
+    reader = Reader("image/jpeg", f, context=ctx)
+    parsed = json.loads(reader.json())
+
+active = parsed["active_manifest"]
+manifest = parsed["manifests"][active]
+
+# Filter actions: keep c2pa.created/c2pa.opened (mandatory) and c2pa.placed, drop the rest
+kept_actions = []
+for assertion in manifest.get("assertions", []):
+    if assertion["label"] == "c2pa.actions.v2":
+        for action in assertion["data"]["actions"]:
+            action_type = action["action"]
+            if action_type in ("c2pa.created", "c2pa.opened", "c2pa.placed"):
+                kept_actions.append(action)
+            # Skip c2pa.filtered, c2pa.color_adjustments, etc.
+
+# Build a new manifest with only the kept actions
+new_manifest = {"claim_generator_info": [{"name": "an-application", "version": "1.0"}]}
+if kept_actions:
+    new_manifest["assertions"] = [{"label": "c2pa.actions", "data": {"actions": kept_actions}}]
+
+builder = Builder.from_json(new_manifest)
+with open("source.jpg", "rb") as src, open("output.jpg", "w+b") as dst:
+    builder.sign(signer, "image/jpeg", src, dst)
+```
+
+### Filtering actions that reference ingredients
+
+Some actions reference ingredients (via `parameters.ingredients[].url` after signing). If keeping an action that references an ingredient, **the corresponding ingredient and its binary resources must also be kept**. If an ingredient is dropped, any actions that reference it must also be dropped (or updated).
+
+#### `c2pa.opened` action
+
+The `c2pa.opened` action is special because it must be the first action and it references the asset that was opened (the `parentOf` ingredient). When filtering:
+
+- **Always keep `c2pa.opened` or `c2pa.created`**: it is required for a valid manifest.
+- **Keep the ingredient it references**: the `parentOf` ingredient linked via its `parameters.ingredients[].url`.
+- Removing the ingredient that `c2pa.opened` points to will make the manifest invalid.
+
+#### `c2pa.placed` action
+
+The `c2pa.placed` action references a `componentOf` ingredient that was composited into the asset. When filtering:
+
+- If keeping `c2pa.placed`, keep the ingredient it references.
+- If the ingredient is dropped, also drop the `c2pa.placed` action.
+- If `c2pa.placed` is not required, it can safely be removed (along with the ingredient it references, if it is the only reference).
+
+#### Example
+
+```py
+import io
+import json
+from c2pa import Builder, Context, Reader
+
+ctx = Context()
+with open("source.jpg", "rb") as f:
+    reader = Reader("image/jpeg", f, context=ctx)
+    parsed = json.loads(reader.json())
+    active = parsed["active_manifest"]
+    manifest = parsed["manifests"][active]
+
+    # Filter actions and track which ingredients are needed
+    kept_actions = []
+    needed_ingredient_labels = set()
+
+    for assertion in manifest.get("assertions", []):
+        if assertion["label"] == "c2pa.actions.v2":
+            for action in assertion["data"]["actions"]:
+                action_type = action["action"]
+                keep = action_type in ("c2pa.opened", "c2pa.created", "c2pa.placed")
+                if keep:
+                    kept_actions.append(action)
+                    # Track which ingredients this action needs
+                    for ing_ref in action.get("parameters", {}).get("ingredients", []):
+                        url = ing_ref["url"]
+                        label = url.rsplit("/", 1)[-1]
+                        needed_ingredient_labels.add(label)
+
+    # Keep only the ingredients that are referenced by kept actions
+    kept_ingredients = [
+        ing for ing in manifest.get("ingredients", [])
+        if ing.get("label") in needed_ingredient_labels
+    ]
+
+    # Build the new manifest with filtered actions and matching ingredients
+    new_manifest = {"claim_generator_info": [{"name": "an-application", "version": "1.0"}]}
+    new_manifest["ingredients"] = kept_ingredients
+    if kept_actions:
+        new_manifest["assertions"] = [{"label": "c2pa.actions", "data": {"actions": kept_actions}}]
+
+    builder = Builder.from_json(new_manifest)
+
+    # Transfer binary resources for kept ingredients
+    for ingredient in kept_ingredients:
+        for key in ("thumbnail", "manifest_data"):
+            if key in ingredient:
+                resource_id = ingredient[key]["identifier"]
+                resource_buf = io.BytesIO()
+                reader.resource_to_stream(resource_id, resource_buf)
+                resource_buf.seek(0)
+                builder.add_resource(resource_id, resource_buf)
+
+with open("source.jpg", "rb") as src, open("output.jpg", "w+b") as dst:
+    builder.sign(signer, "image/jpeg", src, dst)
+```
+
+> [!NOTE]
+> When copying ingredient JSON objects from a reader, they keep their `label` field. Since the action URLs reference ingredients by label, the links resolve correctly as long as ingredients are not renamed or reindexed. If ingredients are re-added via `add_ingredient()` (which generates new labels), the action URLs will also need to be updated.
+
 ## Controlling manifest embedding
 
 By default, `sign()` embeds the manifest directly inside the output asset file.
diff --git a/docs/working-stores.md b/docs/working-stores.md
index 39e56c85..ec69b146 100644
--- a/docs/working-stores.md
+++ b/docs/working-stores.md
@@ -101,6 +101,22 @@ with open("signed_image.jpg", "rb") as stream:
 
 For full details on `Context` and `Settings`, see [Context and settings](context-settings.md).
 
+### Checking if the manifest store is embedded
+
+```py
+reader = Reader("signed_image.jpg")
+
+if reader.is_embedded():
+    print("Manifest store is embedded in the asset")
+else:
+    print("Manifest store is external")
+
+    # Get remote URL if available
+    remote_url = reader.get_remote_url()
+    if remote_url is not None:
+        print(f"Remote URL: {remote_url}")
+```
+
 ### Understanding Reader output
 
 `Reader.json()` returns a JSON string representing the manifest store. The top-level structure looks like this:
@@ -387,6 +403,23 @@ if "thumbnail" in manifest:
     print("Thumbnail extracted")
 ```
 
+### Extracting to a stream
+
+Use `resource_to_stream()` to extract a resource to any writable stream, including in-memory buffers:
+
+```py
+import io
+
+# Extract a thumbnail to an in-memory stream
+thumbnail_buf = io.BytesIO()
+reader.resource_to_stream(thumbnail_uri, thumbnail_buf)
+thumbnail_bytes = thumbnail_buf.getvalue()
+
+# Or extract to a file
+with open("thumbnail.jpg", "wb") as f:
+    reader.resource_to_stream(thumbnail_uri, f)
+```
+
 ### Adding resources to a working store
 
 When building a manifest, you add resources using identifiers. The SDK will reference these in your manifest JSON and convert them to JUMBF URIs during signing.
@@ -412,6 +445,41 @@ The `relationship` field describes how the source (ingredient) was used: `"paren
 
 Ingredients themselves can be turned into ingredient archives (`.c2pa`). An ingredient archive is a `Builder` archive containing _exactly one_ ingredient. Ingredient archives can be added directly as an ingredient to another working store using the `application/c2pa` MIME type — no un-archiving step is needed.
 
+### Ingredient vs. ingredient archive
+
+A **(plain) ingredient** is a source asset that the builder reads at `add_ingredient` time. The builder sees the asset's bytes and stores the required ingredient data (including any caller-set `instance_id`) inside the new manifest.
+
+An **ingredient archive** (in c2pa archive format) is a `.c2pa` file that already contains a fully-formed ingredient. It can be produced with `write_ingredient_archive` (dedicated ingredient archive APIs) or with `to_archive()` on a builder holding one ingredient (legacy). When passed to `add_ingredient`, the builder treats the archive's contents as opaque provenance: the archive's internal fields are not exposed as live JSON the signing builder can introspect or use for linking to actions. Only the JSON the caller supplies in the current `add_ingredient` call is visible to the builder in that round.
+
+Once an ingredient is archived, the original ingredient asset is no longer needed: the `.c2pa` ingredient archive stands in for it and carries the ingredient's provenance.
+
+> [!NOTE]
+> The relationship is one-directional. For legacy support you can _read_ an ingredient out of a builder archive, but you should not try to restore a `Builder` from an ingredient archive — consume it as an ingredient with `add_ingredient_from_archive` (or the legacy `add_ingredient(json, "application/c2pa", archive)` path) instead.
+
+For the dedicated ingredient archive APIs, see [Single-ingredient archive APIs](#single-ingredient-archive-apis).
+
+This difference governs how each can be linked to an action via `ingredientIds`. The table below covers all three cases: plain ingredients, ingredient archives loaded via the dedicated APIs (recommended), and ingredient archives loaded via the legacy `add_ingredient` path:
+
+| Aspect | Ingredient | Ingredient archive (dedicated APIs: `write_ingredient_archive` + `add_ingredient_from_archive`) | Ingredient archive (legacy load via `add_ingredient(json, "application/c2pa", archive)`) |
+| --- | --- | --- | --- |
+| Source format passed to `add_ingredient` | Asset MIME type (`image/jpeg`, `video/mp4`, ...) | N/A — loaded via `add_ingredient_from_archive(stream)` | `"application/c2pa"` |
+| What it is | "Live" asset | A serialized single-ingredient archive (opaque provenance) | A serialized manifest store (opaque provenance) |
+| Linking via `label` | Primary linking key, set on the signing builder's `add_ingredient` JSON | Pass `label` value as archive key to `write_ingredient_archive`; flows through as `ingredientIds` value | Only linking key that works, set on the signing builder's `add_ingredient` JSON |
+| Linking via `instance_id` | Alternative to using `label` | Pass `instance_id` value as archive key to `write_ingredient_archive`; flows through as `ingredientIds` value | Does not link, signing-time error |
+| Linking via a `label` baked in at archive-creation time | N/A (not an archive) | N/A — archive key is set explicitly at `write_ingredient_archive` call time | Does not carry through, must be re-asserted on the signing builder's `add_ingredient` JSON |
+
+#### When to use `label` vs `instance_id`
+
+| Property | `label` | `instance_id` |
+| --- | --- | --- |
+| Who controls it | Caller (any string) | Caller (any string, or from XMP metadata) |
+| Priority for linking | Primary: checked first | Fallback: used when `label` is absent/empty |
+| When to use | JSON-defined manifests where the caller controls the ingredient definition | Programmatic workflows where a stable identifier persisting unchanged across rebuilds is needed |
+| Survives signing | SDK may reassign the actual assertion label in the signed manifest | Unchanged |
+| Stable across rebuilds | The caller controls the build-time value; the post-signing label may change | Yes, always the same set value |
+
+Use `label` when defining manifests in JSON. Use `instance_id` when a stable identifier that persists unchanged across rebuilds is needed. The `label` used at build time may be reassigned by the SDK during signing and will not appear unchanged in `reader.json()` output.
+
 ### Adding ingredients to a working store
 
 When creating a manifest, add ingredients to preserve the provenance chain:
@@ -600,6 +668,21 @@ Using archives provides these advantages:
 
 The default binary format of an archive is the **C2PA JUMBF binary format** (`application/c2pa`), which is the standard way to save and restore working stores.
 
+### Which archive API to use
+
+Two archive API families share the same binary format but serve different purposes:
+
+| | Full-builder APIs | Single-ingredient APIs |
+| --- | --- | --- |
+| APIs | `to_archive`, `with_archive`, `Builder.from_archive` | `write_ingredient_archive`, `add_ingredient_from_archive` |
+| What is archived | Entire builder: manifest definition + all ingredients + all resources | One ingredient only (other builder state is omitted) |
+| Typical use | Checkpoint or transfer a manifest-in-progress between sessions or machines | Ingredient catalog; selectively load individual ingredients at sign time |
+| Linking key | N/A (full builder is restored as-is) | Archive key (`label` or `instance_id`) flows through automatically as `ingredientIds` value |
+
+Use `to_archive` / `with_archive` to pause and resume a signing workflow, or to hand off a complete manifest-in-progress to another process or machine. Use `write_ingredient_archive` / `add_ingredient_from_archive` to distribute or cache individual ingredients independently, or to assemble a manifest from a catalog of pre-archived ingredients at sign time.
+
+The subsections below cover the full-builder APIs. For single-ingredient archive workflows, see [Single-ingredient archive APIs](#single-ingredient-archive-apis).
+
 ### Saving a working store to archive
 
 ```py
@@ -654,6 +737,29 @@ with open("asset.jpg", "rb") as src, open("signed.jpg", "w+b") as dst:
 > [!IMPORTANT]
 > Calling `with_archive()` replaces the `Builder`'s manifest definition with the one from the archive, discarding any definition passed to `Builder()` when it was created. An empty dict `{}` is idiomatic for the initial definition when you plan to load an archive immediately after.
 
+### Restoring with context preservation
+
+Create a `Builder` with a custom `Context` first, then load the archive into it. The context settings (thumbnails, claim generator, signer) are preserved, and only the manifest definition is replaced by the archive.
+
+```py
+from c2pa import Builder, Context
+
+ctx = Context.from_dict({
+    "builder": {
+        "thumbnail": {"enabled": False}
+    }
+})
+
+# Load archive into this working store
+with open("manifest.c2pa", "rb") as archive_stream:
+    builder = Builder({}, context=ctx)
+    builder.with_archive(archive_stream)
+
+# The builder has the archived manifest but keeps the custom context
+```
+
+> [!NOTE]
+> Calling `with_archive()` replaces the builder's current manifest state. You cannot merge multiple archives.
 
 ### Two-phase workflow example
 
@@ -705,6 +811,328 @@ with open("artwork.jpg", "rb") as src, open("signed_artwork.jpg", "w+b") as dst:
     builder.sign("image/jpeg", src, dst)
 ```
 
+### Single-ingredient archive APIs
+
+> [!NOTE]
+> These are the recommended dedicated ingredient archive APIs for ingredient archive workflows. Use `write_ingredient_archive` and `add_ingredient_from_archive` in preference to the legacy `to_archive` / `with_archive` pattern for ingredient use cases.
+
+The `Builder` class exposes two dedicated APIs for moving a single ingredient between builders without manual JSON manipulation:
+
+- `builder.write_ingredient_archive(ingredient_id, stream)` writes one already-registered ingredient out as a single-ingredient JUMBF archive.
+- `builder.add_ingredient_from_archive(stream)` loads one such archive into a builder.
+
+#### How `add_ingredient` and `write_ingredient_archive` interact
+
+`add_ingredient(json, format, stream)` is the registration step. It hashes the source asset, builds the ingredient assertion, and stores the ingredient in the builder under an id read from the JSON. The id is the `label` field if present, otherwise `instance_id`.
+
+`write_ingredient_archive(ingredient_id, stream)` is a lookup step rather than a factory. It finds an ingredient that was already registered under `ingredient_id` and serializes that one ingredient as a JUMBF archive. Calling it without a prior `add_ingredient` for that id raises `C2paError`.
+
+The exported archive is not a lossless slice of the parent. It contains one cloned ingredient and a fresh claim instance id. Any other ingredients on the parent builder are omitted.
+
+`add_ingredient_from_archive(stream)` adds the ingredient back to a consuming builder, keyed by the same id the producer used.
+
+#### Example 1: Write a single-ingredient archive
+
+```py
+import io
+from c2pa import Builder
+
+manifest = {
+    "claim_generator_info": [{"name": "c2pa-test", "version": "0.1.0"}],
+    "assertions": [],
+}
+builder = Builder.from_json(manifest)
+
+# Register three ingredients. The `label` becomes each ingredient's id.
+with open("first.jpg", "rb") as f:
+    builder.add_ingredient({"title": "first.jpg", "relationship": "componentOf", "label": "first"}, "image/jpeg", f)
+with open("second.jpg", "rb") as f:
+    builder.add_ingredient({"title": "second.jpg", "relationship": "componentOf", "label": "second"}, "image/jpeg", f)
+with open("third.jpg", "rb") as f:
+    builder.add_ingredient({"title": "third.jpg", "relationship": "componentOf", "label": "third"}, "image/jpeg", f)
+
+# Look up "second" and write only that one to the archive stream.
+archive = io.BytesIO()
+builder.write_ingredient_archive("second", archive)
+```
+
+The archive contains exactly one ingredient.
+
+#### Example 2: Load an ingredient archive into a fresh builder
+
+```py
+import io
+from c2pa import Builder
+
+consumer = Builder.from_json(manifest)
+
+# `archive` is a stream produced by write_ingredient_archive on another builder.
+archive.seek(0)
+consumer.add_ingredient_from_archive(archive)
+
+# The ingredient is now registered on `consumer`. Sign as usual.
+with open("source.jpg", "rb") as src, open("output.jpg", "w+b") as dst:
+    consumer.sign(signer, "image/jpeg", src, dst)
+```
+
+#### Id resolution
+
+The id passed to `write_ingredient_archive` is matched against each registered ingredient's `label` and its `instance_id`. The first ingredient whose `label` or `instance_id` equals the id is selected (OR-match, no precedence). If both are set on the same ingredient, pass whichever value is to be used as the linking key. See [Lookup keys and action linking](#lookup-keys-and-action-linking) for the full table of linking outcomes.
+
+#### Errors when handling ingredient archives with write_ingredient_archive
+
+`write_ingredient_archive` raises `C2paError` when:
+
+- The producing `Builder` has no prior `add_ingredient` registration. The lookup table is empty, so no id can resolve.
+- The id does not match any registered ingredient's `label` or `instance_id`.
+
+```py
+builder = Builder.from_json(manifest)
+with open("photo.jpg", "rb") as f:
+    builder.add_ingredient({"title": "photo.jpg", "relationship": "componentOf", "label": "real-id"}, "image/jpeg", f)
+
+archive = io.BytesIO()
+# Raises C2paError: "wrong-id" was never registered.
+builder.write_ingredient_archive("wrong-id", archive)
+```
+
+To correct, pass the same string used in the ingredient's `label` or `instance_id` field:
+
+```py
+builder = Builder.from_json(manifest)
+with open("photo.jpg", "rb") as f:
+    builder.add_ingredient({"title": "photo.jpg", "relationship": "componentOf", "label": "ingredient-id"}, "image/jpeg", f)
+
+archive = io.BytesIO()
+# Correct: "real-id" matches the registered label.
+builder.write_ingredient_archive("ingredient-id", archive)
+```
+
+For a multi-archive use case (one catalog, many ingredients picked at build time), see [The ingredients catalog pattern](./selective-manifests.md#the-ingredients-catalog-pattern).
+
+#### Migration guide: from `to_archive` / `with_archive` to single-ingredient APIs
+
+The legacy approach wrapped one ingredient in a full builder archive, then restored it with `with_archive`:
+
+```py
+# Legacy: one ingredient archived as a full builder, restored with with_archive
+builder = Builder.from_json(manifest)
+with open("photo.jpg", "rb") as f:
+    builder.add_ingredient({"title": "photo.jpg", "relationship": "componentOf"}, "image/jpeg", f)
+archive = io.BytesIO()
+builder.to_archive(archive)
+
+# Consumer:
+archive.seek(0)
+restored = Builder({})
+restored.with_archive(archive)
+with open("source.jpg", "rb") as src, open("output.jpg", "w+b") as dst:
+    restored.sign(signer, "image/jpeg", src, dst)
+```
+
+With the dedicated ingredient archive APIs, the producer writes a single-ingredient archive directly, and the consumer loads it with `add_ingredient_from_archive`:
+
+```py
+# Current API: one archive per ingredient via write_ingredient_archive
+builder = Builder.from_json(manifest)
+with open("photo.jpg", "rb") as f:
+    builder.add_ingredient({"title": "photo.jpg", "relationship": "componentOf", "instance_id": "my-photo"}, "image/jpeg", f)
+
+archive = io.BytesIO()
+builder.write_ingredient_archive("my-photo", archive)
+
+# Consumer:
+consumer = Builder.from_json(manifest)
+archive.seek(0)
+consumer.add_ingredient_from_archive(archive)
+with open("source.jpg", "rb") as src, open("output.jpg", "w+b") as dst:
+    consumer.sign(signer, "image/jpeg", src, dst)
+```
+
+Key differences: no JSON parsing, no `add_resource` loops, each archive holds exactly one ingredient, and the consumer loads selectively without deserializing anything else.
+
+Action linking also changes between the two APIs. The legacy load path (`add_ingredient(json, "application/c2pa", archive)`) accepts only `label` as the linking key on the signing builder's `add_ingredient` JSON. See [Linking an ingredient archive to an action](#linking-an-ingredient-archive-to-an-action). The dedicated ingredient archive APIs (`write_ingredient_archive` + `add_ingredient_from_archive`) accept the archive key, which can be either `label` or `instance_id`. See [Lookup keys and action linking](#lookup-keys-and-action-linking). When migrating code that linked by label, pass that same label as the archive key to keep `ingredientIds` unchanged.
+
+## How `instance_id` survives archiving and signing
+
+### What is an instance_id?
+
+`instance_id` is a string field on an ingredient. It is optional in C2PA ingredient assertion starting versions 2, which the SDK currently writes by default. Version 1 required it.
+
+In priority order, this value comes from:
+
+1. The caller: if you set `instance_id` in the JSON passed to `add_ingredient`, that value is stored as-is. No normalization or transformation is applied.
+2. XMP fallback: if no `instance_id` was provided and the source asset has `xmpMM:InstanceID` in its XMP metadata, the library reads that value and sets it on the ingredient.
+3. Auto-generated default: if neither caller nor XMP provided a value, the library generates `xmp.iid:<uuid>` automatically (required for V1 assertion compatibility).
+
+### Instance_id across operations
+
+`instance_id` is kept through every archiving and signing operation this library performs. The table below covers the common paths:
+
+| Operation | `instance_id` kept? |
+| --- | --- |
+| `add_ingredient`, `write_ingredient_archive`, `add_ingredient_from_archive`, then sign | Yes |
+| `add_ingredient`, `to_archive`, then `reader.json()` | Yes |
+| `add_ingredient`, sign, then `reader.json()` (no archive) | Yes |
+| `add_ingredient_from_archive` (loaded from prior archive), sign, then `reader.json()` | Yes |
+
+### Lookup keys and action linking
+
+The first argument to `write_ingredient_archive`, called the _archive key_, has two roles. It locates the ingredient on the producer builder by matching against either `label` or `instance_id`. It also becomes the `ingredientIds` value on the signing builder: `add_ingredient_from_archive` stores the archive key in the archive metadata and restores it as the ingredient's linking label.
+
+Whatever string you pass as the archive key is the string you must use in `ingredientIds`.
+
+| Producer sets | Archive key to pass | `ingredientIds` value |
+| --- | --- | --- |
+| `label` only | `label` value | same `label` value |
+| `instance_id` only | `instance_id` value | same `instance_id` value |
+| both `label` and `instance_id` | either value | same string you passed |
+
+The linking label is a builder-only concept. It does not appear in `reader.json()` output after signing. Only `instance_id` is observable in the signed manifest.
+
+If the archive key matches neither `label` nor `instance_id` of any ingredient on the producer builder, `write_ingredient_archive` raises immediately with `C2paError`.
+
+#### Linking with `instance_id` only
+
+When no `label` is set, pass the `instance_id` value to `write_ingredient_archive`. Use that same string in `ingredientIds` on the signing builder.
+
+Producer:
+
+```py
+import io
+from c2pa import Builder
+
+producer = Builder.from_json(manifest_str)
+with open(source_path, "rb") as f:
+    producer.add_ingredient(
+        {"title": "photo.jpg", "relationship": "componentOf", "instance_id": "catalog:photo-A"},
+        "image/jpeg", f
+    )
+
+archive = io.BytesIO()
+producer.write_ingredient_archive("catalog:photo-A", archive)
+```
+
+Signing builder:
+
+```py
+signing_manifest = {
+    "claim_generator_info": [{"name": "app", "version": "1.0"}],
+    "assertions": [{
+        "label": "c2pa.actions.v2",
+        "data": {"actions": [{"action": "c2pa.placed",
+            "parameters": {"ingredientIds": ["catalog:photo-A"]}}]}
+    }]
+}
+
+consumer = Builder.from_json(signing_manifest)
+archive.seek(0)
+consumer.add_ingredient_from_archive(archive)
+with open(source_path, "rb") as src, open(output_path, "w+b") as dst:
+    consumer.sign(signer, "image/jpeg", src, dst)
+```
+
+#### Linking with `label` only
+
+When only `label` is set, pass the `label` value to `write_ingredient_archive`. Use that same string in `ingredientIds`.
+
+This works even though `label` is not preserved as an ingredient field after signing. `add_ingredient_from_archive` carries the archive key in the archive's metadata and restores it as a builder-only linking key, so the action resolves to the ingredient at signing time.
+
+Producer:
+
+```py
+producer = Builder.from_json(manifest_str)
+with open(source_path, "rb") as f:
+    producer.add_ingredient(
+        {"title": "photo.jpg", "relationship": "componentOf", "label": "my-photo"},
+        "image/jpeg", f
+    )
+
+archive = io.BytesIO()
+producer.write_ingredient_archive("my-photo", archive)
+```
+
+Signing builder:
+
+```py
+signing_manifest = {
+    "claim_generator_info": [{"name": "app", "version": "1.0"}],
+    "assertions": [{
+        "label": "c2pa.actions.v2",
+        "data": {"actions": [{"action": "c2pa.placed",
+            "parameters": {"ingredientIds": ["my-photo"]}}]}
+    }]
+}
+
+consumer = Builder.from_json(signing_manifest)
+archive.seek(0)
+consumer.add_ingredient_from_archive(archive)
+with open(source_path, "rb") as src, open(output_path, "w+b") as dst:
+    consumer.sign(signer, "image/jpeg", src, dst)
+```
+
+#### Linking when both `label` and `instance_id` are set
+
+If both `label` and `instance_id` are set on an ingredient, pass whichever value is to be used as the linking key to `write_ingredient_archive`. That string, and only that string, is what `ingredientIds` must reference on the signing builder.
+
+Producer (passing `label` as the key):
+
+```py
+producer = Builder.from_json(manifest_str)
+with open(source_path, "rb") as f:
+    producer.add_ingredient(
+        {"title": "photo.jpg", "relationship": "componentOf", "label": "my-photo", "instance_id": "iid:abc123"},
+        "image/jpeg", f
+    )
+
+archive = io.BytesIO()
+# Pass "my-photo": this becomes the ingredientIds key.
+# Passing "iid:abc123" instead would also work, but then ingredientIds
+# must use "iid:abc123", not "my-photo".
+producer.write_ingredient_archive("my-photo", archive)
+```
+
+Signing builder:
+
+```py
+# ingredientIds uses "my-photo": the value passed to write_ingredient_archive.
+signing_manifest = {
+    "claim_generator_info": [{"name": "app", "version": "1.0"}],
+    "assertions": [{
+        "label": "c2pa.actions.v2",
+        "data": {"actions": [{"action": "c2pa.placed",
+            "parameters": {"ingredientIds": ["my-photo"]}}]}
+    }]
+}
+
+consumer = Builder.from_json(signing_manifest)
+archive.seek(0)
+consumer.add_ingredient_from_archive(archive)
+with open(source_path, "rb") as src, open(output_path, "w+b") as dst:
+    consumer.sign(signer, "image/jpeg", src, dst)
+```
+
+### Catalog lookups with the read-filter-rebuild APIs
+
+With the legacy `to_archive` + `Reader` pattern, `instance_id` survives into the Reader output and can be used to find a specific ingredient by scanning `reader.json()`:
+
+```py
+import json
+from c2pa import Reader
+
+reader = Reader("archive.c2pa")
+parsed = json.loads(reader.json())
+active = parsed["active_manifest"]
+ingredients = parsed["manifests"][active].get("ingredients", [])
+
+for ing in ingredients:
+    if ing.get("instance_id") == "catalog:photo-A":
+        # Found the ingredient
+        pass
+```
+
+Using the dedicated archive API, this loop is unnecessary: each archive holds exactly and explicitly one ingredient, so `add_ingredient_from_archive` loads precisely what was written.
+
 ## Embedded versus external manifests
 
 By default, manifest stores are **embedded** directly into the asset file. You can also use **external** or **remote** manifest stores.
@@ -762,6 +1190,22 @@ with open("source.jpg", "rb") as src, open("output.jpg", "w+b") as dst:
     builder.sign("image/jpeg", src, dst)
 ```
 
+### Checking manifest store location
+
+```py
+reader = Reader("asset.jpg")
+
+if reader.is_embedded():
+    print("Manifest store is embedded in the asset")
+else:
+    # External or remote
+    remote_url = reader.get_remote_url()
+    if remote_url is not None:
+        print(f"Manifest store is remote: {remote_url}")
+    else:
+        print("Manifest store is external (sidecar)")
+```
+
 ## Best practices
 
 - **Use `Context` for all configuration.** Pass a `Context` to `Builder` and `Reader` rather than using global state. See [Context and settings](context-settings.md).
diff --git a/pyproject.toml b/pyproject.toml
index 15882b3f..6cb2874c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "c2pa-python"
-version = "0.32.10"
+version = "0.32.11"
 requires-python = ">=3.10"
 description = "Python bindings for the C2PA Content Authenticity Initiative (CAI) library"
 readme = { file = "README.md", content-type = "text/markdown" }
@@ -17,7 +17,8 @@ classifiers = [
     "Operating System :: Microsoft :: Windows"
 ]
 maintainers = [
-  {name = "Gavin Peacock", email = "gpeacock@adobe.com"}
+  {name = "Gavin Peacock", email = "gpeacock@adobe.com"},
+  {name = "Tania Mathern", email = "mathern@adobe.com"}
 ]
 urls = {homepage = "https://contentauthenticity.org", repository = "https://github.com/contentauth/c2pa-python"}
 dependencies = [
diff --git a/src/c2pa/c2pa.py b/src/c2pa/c2pa.py
index bfec4a62..edef50c0 100644
--- a/src/c2pa/c2pa.py
+++ b/src/c2pa/c2pa.py
@@ -66,6 +66,8 @@
     'c2pa_builder_add_ingredient_from_stream',
     'c2pa_builder_add_action',
     'c2pa_builder_to_archive',
+    'c2pa_builder_write_ingredient_archive',
+    'c2pa_builder_add_ingredient_from_archive',
     'c2pa_builder_sign',
     'c2pa_builder_sign_context',
     'c2pa_builder_from_context',
@@ -612,6 +614,15 @@ def _setup_function(func, argtypes, restype=None):
 _setup_function(_lib.c2pa_builder_to_archive,
                 [ctypes.POINTER(C2paBuilder), ctypes.POINTER(C2paStream)],
                 ctypes.c_int)
+_setup_function(_lib.c2pa_builder_write_ingredient_archive,
+                [ctypes.POINTER(C2paBuilder),
+                 ctypes.c_char_p,
+                 ctypes.POINTER(C2paStream)],
+                ctypes.c_int)
+_setup_function(_lib.c2pa_builder_add_ingredient_from_archive,
+                [ctypes.POINTER(C2paBuilder),
+                 ctypes.POINTER(C2paStream)],
+                ctypes.c_int)
 _setup_function(_lib.c2pa_builder_sign,
                 [ctypes.POINTER(C2paBuilder),
                  ctypes.c_char_p,
@@ -3445,6 +3456,54 @@ def to_archive(self, stream: Any) -> None:
                 ),
                 check=lambda r: r != 0)
 
+    def write_ingredient_archive(self, ingredient_id: str, stream: Any) -> None:
+        """Write a single-ingredient archive for the named ingredient.
+        The archive is in C2PA format.
+
+        Args:
+            ingredient_id: The instance_id of the ingredient within this builder
+            stream: Writable stream to receive the archive
+
+        Raises:
+            C2paError: If there was an error writing the archive
+        """
+        self._ensure_valid_state()
+
+        ingredient_id_str = _to_utf8_bytes(ingredient_id, "ingredient_id")
+
+        with Stream(stream) as stream_obj:
+            result = _lib.c2pa_builder_write_ingredient_archive(
+                self._handle, ingredient_id_str, stream_obj._stream)
+
+            _check_ffi_operation_result(result,
+                Builder._ERROR_MESSAGES["archive_error"].format(
+                    "Unknown error"
+                ),
+                check=lambda r: r != 0)
+
+    def add_ingredient_from_archive(self, stream: Any) -> None:
+        """Add an ingredient from a per-ingredient archive stream.
+        The archive must be in C2PA format, as written by
+        write_ingredient_archive.
+
+        Args:
+            stream: Readable, seekable stream containing the ingredient archive
+
+        Raises:
+            C2paError: If there was an error reading the archive
+        """
+        self._ensure_valid_state()
+
+        with Stream(stream) as stream_obj:
+            result = _lib.c2pa_builder_add_ingredient_from_archive(
+                self._handle, stream_obj._stream)
+
+            _check_ffi_operation_result(result,
+                Builder._ERROR_MESSAGES["ingredient_error"].format(
+                    "Unknown error"
+                ),
+                check=lambda r: r != 0)
+
     def with_archive(self, stream: Any) -> 'Builder':
         """Load an archive into this Builder instance, replacing its
         manifest definition. The archive carries only the
diff --git a/tests/test_unit_tests.py b/tests/test_unit_tests.py
index ada82d78..053dca67 100644
--- a/tests/test_unit_tests.py
+++ b/tests/test_unit_tests.py
@@ -1917,6 +1917,359 @@ def sign_and_validate_with_trust_config():
         self.assertIsNotNone(result.get('validation_state'))
         self.assertEqual(result.get('validation_state'), "Trusted")
 
+    def test_write_ingredient_archive_produces_readable_archive(self):
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "0.1.0"}],
+            "assertions": [],
+        }
+        builder = Builder.from_json(manifest)
+        ingredient_json = {
+            "title": "A.jpg",
+            "relationship": "componentOf",
+            "instance_id": "ingredient-A",
+        }
+        with open(self.testPath, "rb") as f:
+            builder.add_ingredient(ingredient_json, "image/jpeg", f)
+        archive = io.BytesIO()
+        builder.write_ingredient_archive("ingredient-A", archive)
+        builder.close()
+        self.assertGreater(archive.tell(), 0)
+        archive.close()
+
+    def test_add_ingredient_from_archive_roundtrip(self):
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "0.1.0"}],
+            "assertions": [],
+        }
+        builder = Builder.from_json(manifest)
+        ingredient_json = {
+            "title": "A.jpg",
+            "relationship": "componentOf",
+            "instance_id": "catalog:ingredient-A",
+        }
+        with open(self.testPath, "rb") as f:
+            builder.add_ingredient(ingredient_json, "image/jpeg", f)
+        archive = io.BytesIO()
+        builder.write_ingredient_archive("catalog:ingredient-A", archive)
+        builder.close()
+
+        archive.seek(0)
+        builder2 = Builder.from_json(manifest)
+        builder2.add_ingredient_from_archive(archive)
+        archive.close()
+
+        output = io.BytesIO()
+        with open(self.testPath, "rb") as f:
+            builder2.sign(self.signer, "image/jpeg", f, output)
+        builder2.close()
+
+        output.seek(0)
+        reader = Reader("image/jpeg", output)
+        json_data = reader.json()
+        self.assertIn("A.jpg", json_data)
+        output.close()
+
+    def test_add_ingredient_from_archive_preserves_instance_id(self):
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "0.1.0"}],
+            "assertions": [],
+        }
+        archive_builder = Builder.from_json(manifest)
+        ingredient_json = {
+            "title": "photo.jpg",
+            "relationship": "parentOf",
+            "instance_id": "my-ingredient",
+        }
+        with open(self.testPath, "rb") as f:
+            archive_builder.add_ingredient(ingredient_json, "image/jpeg", f)
+        archive = io.BytesIO()
+        archive_builder.write_ingredient_archive("my-ingredient", archive)
+        archive_builder.close()
+
+        archive.seek(0)
+        signing_builder = Builder.from_json(manifest)
+        signing_builder.add_ingredient_from_archive(archive)
+        archive.close()
+
+        output = io.BytesIO()
+        with open(self.testPath, "rb") as f:
+            signing_builder.sign(self.signer, "image/jpeg", f, output)
+        signing_builder.close()
+
+        output.seek(0)
+        reader = Reader("image/jpeg", output)
+        json_data = reader.json()
+        self.assertIn("photo.jpg", json_data)
+        output.close()
+
+    def test_add_ingredient_from_archive_preserves_instance_id_component_of(self):
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [],
+        }
+        archive_builder = Builder.from_json(manifest)
+        ingredient_json = {
+            "title": "photo.jpg",
+            "relationship": "componentOf",
+            "instance_id": "my-ingredient",
+        }
+        with open(self.testPath, "rb") as f:
+            archive_builder.add_ingredient(ingredient_json, "image/jpeg", f)
+        archive = io.BytesIO()
+        archive_builder.write_ingredient_archive("my-ingredient", archive)
+        archive_builder.close()
+
+        archive.seek(0)
+        signing_builder = Builder.from_json(manifest)
+        signing_builder.add_ingredient_from_archive(archive)
+        archive.close()
+
+        output = io.BytesIO()
+        with open(self.testPath, "rb") as f:
+            signing_builder.sign(self.signer, "image/jpeg", f, output)
+        signing_builder.close()
+
+        output.seek(0)
+        reader = Reader("image/jpeg", output)
+        json_data = reader.json()
+        self.assertIn("photo.jpg", json_data)
+        self.assertIn("componentOf", json_data)
+        output.close()
+
+    def test_add_ingredient_from_archive_preserves_instance_id_input_to(self):
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [],
+        }
+        archive_builder = Builder.from_json(manifest)
+        ingredient_json = {
+            "title": "photo.jpg",
+            "relationship": "inputTo",
+            "instance_id": "my-ingredient",
+        }
+        with open(self.testPath, "rb") as f:
+            archive_builder.add_ingredient(ingredient_json, "image/jpeg", f)
+        archive = io.BytesIO()
+        archive_builder.write_ingredient_archive("my-ingredient", archive)
+        archive_builder.close()
+
+        archive.seek(0)
+        signing_builder = Builder.from_json(manifest)
+        signing_builder.add_ingredient_from_archive(archive)
+        archive.close()
+
+        output = io.BytesIO()
+        with open(self.testPath, "rb") as f:
+            signing_builder.sign(self.signer, "image/jpeg", f, output)
+        signing_builder.close()
+
+        output.seek(0)
+        reader = Reader("image/jpeg", output)
+        json_data = reader.json()
+        self.assertIn("photo.jpg", json_data)
+        self.assertIn("inputTo", json_data)
+        output.close()
+
+    def test_add_ingredient_from_archive_roundtrip_parent_of(self):
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [],
+        }
+        builder = Builder.from_json(manifest)
+        ingredient_json = {
+            "title": "A.jpg",
+            "relationship": "parentOf",
+            "instance_id": "catalog:ingredient-A",
+        }
+        with open(self.testPath, "rb") as f:
+            builder.add_ingredient(ingredient_json, "image/jpeg", f)
+        archive = io.BytesIO()
+        builder.write_ingredient_archive("catalog:ingredient-A", archive)
+        builder.close()
+
+        archive.seek(0)
+        builder2 = Builder.from_json(manifest)
+        builder2.add_ingredient_from_archive(archive)
+        archive.close()
+
+        output = io.BytesIO()
+        with open(self.testPath, "rb") as f:
+            builder2.sign(self.signer, "image/jpeg", f, output)
+        builder2.close()
+
+        output.seek(0)
+        reader = Reader("image/jpeg", output)
+        json_data = reader.json()
+        self.assertIn("A.jpg", json_data)
+        self.assertIn("parentOf", json_data)
+        output.close()
+
+    def test_add_ingredient_from_archive_roundtrip_input_to(self):
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [],
+        }
+        builder = Builder.from_json(manifest)
+        ingredient_json = {
+            "title": "A.jpg",
+            "relationship": "inputTo",
+            "instance_id": "catalog:ingredient-A",
+        }
+        with open(self.testPath, "rb") as f:
+            builder.add_ingredient(ingredient_json, "image/jpeg", f)
+        archive = io.BytesIO()
+        builder.write_ingredient_archive("catalog:ingredient-A", archive)
+        builder.close()
+
+        archive.seek(0)
+        builder2 = Builder.from_json(manifest)
+        builder2.add_ingredient_from_archive(archive)
+        archive.close()
+
+        output = io.BytesIO()
+        with open(self.testPath, "rb") as f:
+            builder2.sign(self.signer, "image/jpeg", f, output)
+        builder2.close()
+
+        output.seek(0)
+        reader = Reader("image/jpeg", output)
+        json_data = reader.json()
+        self.assertIn("A.jpg", json_data)
+        self.assertIn("inputTo", json_data)
+        output.close()
+
+    def test_ingredient_from_archive_linked_to_opened_action(self):
+        ingredient_id = "xmp:iid:archive-parent-001"
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [
+                {
+                    "label": "c2pa.actions.v2",
+                    "data": {
+                        "actions": [
+                            {
+                                "action": "c2pa.opened",
+                                "parameters": {"ingredientIds": [ingredient_id]},
+                            }
+                        ]
+                    },
+                }
+            ],
+        }
+        archive_builder = Builder.from_json(manifest)
+        with open(self.testPath, "rb") as f:
+            archive_builder.add_ingredient(
+                {"title": "photo.jpg", "relationship": "parentOf", "instance_id": ingredient_id},
+                "image/jpeg", f)
+        archive = io.BytesIO()
+        archive_builder.write_ingredient_archive(ingredient_id, archive)
+        archive_builder.close()
+
+        archive.seek(0)
+        signing_builder = Builder.from_json(manifest)
+        signing_builder.add_ingredient_from_archive(archive)
+        archive.close()
+
+        output = io.BytesIO()
+        with open(self.testPath, "rb") as f:
+            signing_builder.sign(self.signer, "image/jpeg", f, output)
+        signing_builder.close()
+
+        output.seek(0)
+        reader = Reader("image/jpeg", output)
+        json_data = reader.json()
+        self.assertIn("c2pa.opened", json_data)
+        self.assertIn(ingredient_id, json_data)
+        output.close()
+
+    def test_ingredient_from_archive_linked_to_placed_action(self):
+        ingredient_id = "xmp:iid:archive-component-001"
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [
+                {
+                    "label": "c2pa.actions.v2",
+                    "data": {
+                        "actions": [
+                            {
+                                "action": "c2pa.placed",
+                                "parameters": {"ingredientIds": [ingredient_id]},
+                            }
+                        ]
+                    },
+                }
+            ],
+        }
+        archive_builder = Builder.from_json(manifest)
+        with open(self.testPath, "rb") as f:
+            archive_builder.add_ingredient(
+                {"title": "photo.jpg", "relationship": "componentOf", "instance_id": ingredient_id},
+                "image/jpeg", f)
+        archive = io.BytesIO()
+        archive_builder.write_ingredient_archive(ingredient_id, archive)
+        archive_builder.close()
+
+        archive.seek(0)
+        signing_builder = Builder.from_json(manifest)
+        signing_builder.add_ingredient_from_archive(archive)
+        archive.close()
+
+        output = io.BytesIO()
+        with open(self.testPath, "rb") as f:
+            signing_builder.sign(self.signer, "image/jpeg", f, output)
+        signing_builder.close()
+
+        output.seek(0)
+        reader = Reader("image/jpeg", output)
+        json_data = reader.json()
+        self.assertIn("c2pa.placed", json_data)
+        self.assertIn(ingredient_id, json_data)
+        output.close()
+
+    def test_ingredient_from_archive_linked_to_edited_action(self):
+        ingredient_id = "xmp:iid:archive-input-001"
+        manifest = {
+            "claim_generator_info": [{"name": "c2pa-test", "version": "1.0"}],
+            "assertions": [
+                {
+                    "label": "c2pa.actions.v2",
+                    "data": {
+                        "actions": [
+                            {
+                                "action": "c2pa.edited",
+                                "parameters": {"ingredientIds": [ingredient_id]},
+                            }
+                        ]
+                    },
+                }
+            ],
+        }
+        archive_builder = Builder.from_json(manifest)
+        with open(self.testPath, "rb") as f:
+            archive_builder.add_ingredient(
+                {"title": "photo.jpg", "relationship": "inputTo", "instance_id": ingredient_id},
+                "image/jpeg", f)
+        archive = io.BytesIO()
+        archive_builder.write_ingredient_archive(ingredient_id, archive)
+        archive_builder.close()
+
+        archive.seek(0)
+        signing_builder = Builder.from_json(manifest)
+        signing_builder.add_ingredient_from_archive(archive)
+        archive.close()
+
+        output = io.BytesIO()
+        with open(self.testPath, "rb") as f:
+            signing_builder.sign(self.signer, "image/jpeg", f, output)
+        signing_builder.close()
+
+        output.seek(0)
+        reader = Reader("image/jpeg", output)
+        json_data = reader.json()
+        self.assertIn("c2pa.edited", json_data)
+        self.assertIn(ingredient_id, json_data)
+        output.close()
+
     def test_remote_sign(self):
         with open(self.testPath, "rb") as file:
             builder = Builder(self.manifestDefinition)