From eab7a9b6cbfc43200e2c9d5f5e44066aab117986 Mon Sep 17 00:00:00 2001
From: tmathern <60901087+tmathern@users.noreply.github.com>
Date: Mon, 4 May 2026 09:39:27 -0700
Subject: [PATCH 1/7] fix: Clarify docs

---
 docs/selective-manifests.md |  96 ++++++++++++++++++++++----
 tests/builder.test.cpp      | 130 ++++++++++++++++++++++++++++++++++++
 2 files changed, 213 insertions(+), 13 deletions(-)

diff --git a/docs/selective-manifests.md b/docs/selective-manifests.md
index b4c301b..9cfe760 100644
--- a/docs/selective-manifests.md
+++ b/docs/selective-manifests.md
@@ -722,6 +722,8 @@ new_builder.sign(source_path, output_path, signer);
 
 An ingredient archive is a serialized `Builder` containing exactly one and only one ingredient (see [Builder archives vs. ingredient archives](#builder-archives-vs-ingredient-archives)). Reading it with `Reader` allows the caller to inspect the ingredient before deciding whether to use it: its thumbnail, whether it carries provenance (e.g. an active manifest), validation status, relationship, etc.
 
+Reading is independent of linking — see [Linking an archived ingredient to an action](#linking-an-archived-ingredient-to-an-action) for how to attach the ingredient to an action without reading it first.
+
 ```mermaid
 flowchart LR
     IA["ingredient_archive.c2pa"] -->|"Reader(application/c2pa)"| JSON["JSON + resources"]
@@ -783,23 +785,24 @@ if (ingredient.contains("thumbnail")) {
 
 #### Linking an archived ingredient to an action
 
-After reading the ingredient details from an ingredient archive, the ingredient can be added to a new `Builder` and linked to an action. You must assign a `label` in the `add_ingredient` call on the signing builder and use that label as the linking key in `ingredientIds`. Labels baked into the archive ingredient are not carried through, and `instance_id` does not work as a linking key for ingredient archives.
+Linking an archived ingredient to an action is **label-driven**. Set a `label` on the ingredient JSON passed to `add_ingredient` on the signing builder, and use that same string in the action's `ingredientIds`. Reading the archive first is *not* required to link it — `Reader` is only useful when the caller wants to preview the ingredient (thumbnail, provenance, validation status) before deciding whether to use it (see [Reading ingredient details from an ingredient archive](#reading-ingredient-details-from-an-ingredient-archive)).
+
+> [!IMPORTANT]
+> **`instance_id` does not work as a linking key for ingredient archives.** Use `label` instead.
+>
+> **Labels baked into the archive ingredient at archive-creation time do not carry through as linking keys.** The label must be re-asserted on the signing builder's `add_ingredient` call.
+>
+> Both rules apply whether the archive is added by file path or by stream. Attempting to link via `instance_id`, or relying on a baked-in label alone, produces a sign-time error: `Action ingredientId not found: <id>`. See [Troubleshooting linking errors](#troubleshooting-linking-errors).
+
+Labels are build-time linking keys only. The SDK may reassign the actual label in the signed manifest.
 
-Note that labels are only used as build-time linking keys. The SDK may reassign the actual label in the signed manifest.
+##### Minimal example
 
-Assign a `label` in the `add_ingredient` call and reference that same label in `ingredientIds`. This works whether or not the ingredient has an `instance_id`.
+Build a manifest whose action references a chosen label, then `add_ingredient` with that label on the signing builder. No `Reader`, no parsing of the archive:
 
 ```cpp
 c2pa::Context context;
 
-// Read the ingredient archive
-std::ifstream archive_file("ingredient_archive.c2pa", std::ios::binary);
-c2pa::Reader reader(context, "application/c2pa", archive_file);
-auto parsed = json::parse(reader.json());
-std::string active = parsed["active_manifest"];
-auto& ingredient = parsed["manifests"][active]["ingredients"][0];
-
-// Use a caller-assigned label as the linking key
 json manifest_json = {
     {"claim_generator_info", json::array({{{"name", "an-application"}, {"version", "1.0"}}})},
     {"assertions", json::array({
@@ -821,13 +824,60 @@ json manifest_json = {
 
 c2pa::Builder builder(context, manifest_json.dump());
 
-// The label on the ingredient JSON matches the entry in ingredientIds
+// Same string as in ingredientIds above — that is what links the action.
+builder.add_ingredient(
+    R"({
+        "title": "photo.jpg",
+        "relationship": "parentOf",
+        "label": "archived-ingredient"
+    })",
+    archive_path);
+
+builder.sign(source_path, output_path, signer);
+```
+
+##### Using streams
+
+The `add_ingredient` overload that takes a `std::istream` (with `"application/c2pa"` as the format) follows the same rule — the `label` on the ingredient JSON is what links the action:
+
+```cpp
+std::ifstream archive_file("ingredient_archive.c2pa", std::ios::binary);
+c2pa::Builder builder(context, manifest_json.dump());
+
+builder.add_ingredient(
+    R"({
+        "title": "photo.jpg",
+        "relationship": "parentOf",
+        "label": "archived-ingredient"
+    })",
+    "application/c2pa",
+    archive_file);
+
+builder.sign(source_path, output_path, signer);
+```
+
+##### Previewing the archive before linking
+
+If you want to inspect the archive (e.g. to decide whether to use it, or to copy `title` from it), open it with `Reader` first, then add it as an ingredient. The Reader step is independent of the linking — the link is still established by the `label` on the signing builder's `add_ingredient` call.
+
+```cpp
+std::ifstream archive_file("ingredient_archive.c2pa", std::ios::binary);
+c2pa::Reader reader(context, "application/c2pa", archive_file);
+auto parsed = json::parse(reader.json());
+std::string active = parsed["active_manifest"];
+auto& ingredient = parsed["manifests"][active]["ingredients"][0];
+
+// Inspect ingredient (thumbnail, validation_status, active_manifest, etc.)
+// before deciding to use it. See "Reading ingredient details from an ingredient archive".
+
+c2pa::Builder builder(context, manifest_json.dump());
+
 archive_file.seekg(0);
 builder.add_ingredient(
     json({
         {"title", ingredient["title"]},
         {"relationship", "parentOf"},
-        {"label", "archived-ingredient"}
+        {"label", "archived-ingredient"}  // The linking key — chosen here, not read from the archive.
     }).dump(),
     "application/c2pa",
     archive_file);
@@ -835,6 +885,26 @@ builder.add_ingredient(
 builder.sign(source_path, output_path, signer);
 ```
 
+#### Troubleshooting linking errors
+
+The most common sign-time error when linking ingredients is:
+
+```text
+Builder.sign failure: Other: assertion-specific error:
+Action ingredientId not found: <id>
+```
+
+`<id>` is the value the SDK could not resolve to an ingredient on the builder. Causes and fixes:
+
+| 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. `instance_id` is for catalog identification, not action linking. | 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. | 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 byte-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. | See [Filtering actions that reference ingredients](#filtering-actions-that-reference-ingredients) — keep the ingredient and its binary resources alongside the action. |
+
+For the linking rules, see [Linking an archived ingredient to an action](#linking-an-archived-ingredient-to-an-action) above.
+
 ### Merging multiple working stores
 
 In some cases you may need to merge ingredients from multiple working stores (builder archives) into a single `Builder`. This should be a **fallback strategy**—the recommended practice is to maintain a single active working store and add ingredients incrementally (archived ingredient catalogs help with this). Merging is available when multiple working stores must be consolidated.
diff --git a/tests/builder.test.cpp b/tests/builder.test.cpp
index 153f6e3..5dc94a0 100644
--- a/tests/builder.test.cpp
+++ b/tests/builder.test.cpp
@@ -4745,6 +4745,136 @@ TEST_F(BuilderTest, LinkArchiveLabelOnSigningBuilderOpened)
     EXPECT_TRUE(linked);
 }
 
+TEST_F(BuilderTest, LinkArchiveLabelOnSigningBuilderOpenedFromStream)
+{
+    // Same as LinkArchiveLabelOnSigningBuilderOpened but feeds the archive
+    // through the std::istream overload of add_ingredient.
+    auto archive_path = get_temp_path("label_on_signing_opened_stream.c2pa");
+    create_ingredient_archive(archive_path,
+        R"({"title": "photo.jpg", "relationship": "parentOf"})");
+
+    auto manifest_json = make_manifest_with_action("c2pa.opened", "my-ingredient",
+        "http://cv.iptc.org/newscodes/digitalsourcetype/digitalCreation");
+    auto context = c2pa::Context();
+    auto builder = c2pa::Builder(context, manifest_json.dump());
+
+    std::ifstream archive_stream(archive_path, std::ios::binary);
+    builder.add_ingredient(
+        R"({"title": "photo.jpg", "relationship": "parentOf", "label": "my-ingredient"})",
+        "application/c2pa",
+        archive_stream);
+    archive_stream.close();
+
+    auto signer = c2pa_test::create_test_signer();
+    auto output_path = get_temp_path("link_label_on_signing_opened_stream.jpg");
+
+    bool linked = verify_ingredient_linked(builder, output_path, signer, "c2pa.opened");
+    EXPECT_TRUE(linked);
+}
+
+TEST_F(BuilderTest, LinkArchiveLabelOnSigningBuilderPlacedFromStream)
+{
+    auto archive_path = get_temp_path("label_on_signing_placed_stream.c2pa");
+    create_ingredient_archive(archive_path,
+        R"({"title": "photo.jpg", "relationship": "componentOf"})");
+
+    auto manifest_json = make_manifest_with_action("c2pa.placed", "my-ingredient");
+    auto context = c2pa::Context();
+    auto builder = c2pa::Builder(context, manifest_json.dump());
+
+    std::ifstream archive_stream(archive_path, std::ios::binary);
+    builder.add_ingredient(
+        R"({"title": "photo.jpg", "relationship": "componentOf", "label": "my-ingredient"})",
+        "application/c2pa",
+        archive_stream);
+    archive_stream.close();
+
+    auto signer = c2pa_test::create_test_signer();
+    auto output_path = get_temp_path("link_label_on_signing_placed_stream.jpg");
+
+    bool linked = verify_ingredient_linked(builder, output_path, signer, "c2pa.placed");
+    EXPECT_TRUE(linked);
+}
+
+TEST_F(BuilderTest, LinkArchiveInstanceIdOnSigningBuilderFromStreamFails)
+{
+    // Stream overload counterpart of LinkArchiveInstanceIdFromArchiveOnSigningBuilder.
+    // instance_id cannot be used as a linking key for ingredient archives,
+    // regardless of whether the archive is added via path or stream.
+    auto context = c2pa::Context();
+    auto signer = c2pa_test::create_test_signer();
+    auto source_path = c2pa_test::get_fixture_path("A.jpg");
+
+    auto archive_path = get_temp_path("iid_from_archive_linking_stream.c2pa");
+    create_ingredient_archive(archive_path,
+        R"({"title": "photo.jpg", "relationship": "parentOf", "instance_id": "xmp:iid:test-archive-link-stream"})");
+
+    auto reader = c2pa::Reader(context, archive_path);
+    auto archive_parsed = json::parse(reader.json());
+    std::string active = archive_parsed["active_manifest"];
+    auto& archive_ingredient = archive_parsed["manifests"][active]["ingredients"][0];
+    ASSERT_TRUE(archive_ingredient.contains("instance_id"));
+    std::string instance_id = archive_ingredient["instance_id"];
+
+    json manifest_json = {
+        {"claim_generator_info", json::array({{{"name", "c2pa-test"}, {"version", "1.0"}}})},
+        {"assertions", json::array({
+            {
+                {"label", "c2pa.actions.v2"},
+                {"data", {{"actions", json::array({
+                    {
+                        {"action", "c2pa.opened"},
+                        {"digitalSourceType", "http://cv.iptc.org/newscodes/digitalsourcetype/digitalCreation"},
+                        {"parameters", {{"ingredientIds", json::array({instance_id})}}}
+                    }
+                })}}}
+            }
+        })}
+    };
+
+    auto builder = c2pa::Builder(context, manifest_json.dump());
+
+    std::ifstream archive_stream(archive_path, std::ios::binary);
+    builder.add_ingredient(
+        json({
+            {"title", archive_ingredient["title"]},
+            {"relationship", "parentOf"},
+            {"instance_id", instance_id}
+        }).dump(),
+        "application/c2pa",
+        archive_stream);
+    archive_stream.close();
+
+    auto output_path = get_temp_path("iid_from_archive_linking_stream_result.jpg");
+
+    EXPECT_THROW(builder.sign(source_path, output_path, signer), c2pa::C2paException);
+}
+
+TEST_F(BuilderTest, LinkArchiveBakedLabelAlsoSetOnSigningBuilder)
+{
+    // Probe: same baked label, AND the same label re-asserted on the signing
+    // builder's add_ingredient call. Should link successfully (signing-builder
+    // label is what counts).
+    auto archive_path = get_temp_path("baked_label_also_set.c2pa");
+    create_ingredient_archive(archive_path,
+        R"({"title": "photo.jpg", "relationship": "parentOf", "label": "baked-label"})");
+
+    auto manifest_json = make_manifest_with_action("c2pa.opened", "baked-label",
+        "http://cv.iptc.org/newscodes/digitalsourcetype/digitalCreation");
+    auto context = c2pa::Context();
+    auto builder = c2pa::Builder(context, manifest_json.dump());
+
+    builder.add_ingredient(
+        R"({"title": "photo.jpg", "relationship": "parentOf", "label": "baked-label"})",
+        archive_path);
+
+    auto signer = c2pa_test::create_test_signer();
+    auto output_path = get_temp_path("baked_label_also_set_result.jpg");
+
+    bool linked = verify_ingredient_linked(builder, output_path, signer, "c2pa.opened");
+    EXPECT_TRUE(linked);
+}
+
 TEST_F(BuilderTest, LinkArchiveTwoIngredientsUsingLabels)
 {
     auto archive1 = get_temp_path("two_labels_archive1.c2pa");

From 0bbde67cd52b82194d9c324329ca0dec9fae91d4 Mon Sep 17 00:00:00 2001
From: Tania Mathern <mathern@adobe.com>
Date: Mon, 4 May 2026 09:58:37 -0700
Subject: [PATCH 2/7] fix: Update docs

---
 docs/selective-manifests.md | 27 ++++++++++++++-------------
 tests/builder.test.cpp      | 30 ------------------------------
 2 files changed, 14 insertions(+), 43 deletions(-)

diff --git a/docs/selective-manifests.md b/docs/selective-manifests.md
index 9cfe760..ff671c1 100644
--- a/docs/selective-manifests.md
+++ b/docs/selective-manifests.md
@@ -722,7 +722,7 @@ new_builder.sign(source_path, output_path, signer);
 
 An ingredient archive is a serialized `Builder` containing exactly one and only one ingredient (see [Builder archives vs. ingredient archives](#builder-archives-vs-ingredient-archives)). Reading it with `Reader` allows the caller to inspect the ingredient before deciding whether to use it: its thumbnail, whether it carries provenance (e.g. an active manifest), validation status, relationship, etc.
 
-Reading is independent of linking — see [Linking an archived ingredient to an action](#linking-an-archived-ingredient-to-an-action) for how to attach the ingredient to an action without reading it first.
+Reading is independent of linking, see [Linking an archived ingredient to an action](#linking-an-archived-ingredient-to-an-action) for how to attach the ingredient to an action without reading it first.
 
 ```mermaid
 flowchart LR
@@ -741,7 +741,7 @@ auto parsed = json::parse(reader.json());
 std::string active = parsed["active_manifest"];
 auto manifest = parsed["manifests"][active];
 
-// An ingredient archive has exactly one ingredient
+// An ingredient archive must always have exactly one ingredient
 auto& ingredient = manifest["ingredients"][0];
 
 // Relationship
@@ -785,18 +785,20 @@ if (ingredient.contains("thumbnail")) {
 
 #### Linking an archived ingredient to an action
 
-Linking an archived ingredient to an action is **label-driven**. Set a `label` on the ingredient JSON passed to `add_ingredient` on the signing builder, and use that same string in the action's `ingredientIds`. Reading the archive first is *not* required to link it — `Reader` is only useful when the caller wants to preview the ingredient (thumbnail, provenance, validation status) before deciding whether to use it (see [Reading ingredient details from an ingredient archive](#reading-ingredient-details-from-an-ingredient-archive)).
+Linking an **archived** ingredient to an action is **label-driven**: archived ingredients can only be linked to actions using labels.
 
-> [!IMPORTANT]
+To do so, set a `label` on the archived ingredient's JSON passed to `add_ingredient` on the builder, and use that same string in the action's `ingredientIds`.
+
+Reading the archive first is *not* required to link it. `Reader` is only useful when the caller wants to preview the ingredient (thumbnail, provenance, validation status) before deciding whether to use it (see [Reading ingredient details from an ingredient archive](#reading-ingredient-details-from-an-ingredient-archive)).
+
+> [!WARNING]
 > **`instance_id` does not work as a linking key for ingredient archives.** Use `label` instead.
 >
-> **Labels baked into the archive ingredient at archive-creation time do not carry through as linking keys.** The label must be re-asserted on the signing builder's `add_ingredient` call.
->
-> Both rules apply whether the archive is added by file path or by stream. Attempting to link via `instance_id`, or relying on a baked-in label alone, produces a sign-time error: `Action ingredientId not found: <id>`. See [Troubleshooting linking errors](#troubleshooting-linking-errors).
+> **Labels baked into the archive ingredient at archive-creation time do not carry through as linking keys either.** The label must be re-asserted on the signing builder's `add_ingredient` call so action and archived ingredient properly link.
 
 Labels are build-time linking keys only. The SDK may reassign the actual label in the signed manifest.
 
-##### Minimal example
+##### Minimal archive to action linking example
 
 Build a manifest whose action references a chosen label, then `add_ingredient` with that label on the signing builder. No `Reader`, no parsing of the archive:
 
@@ -824,7 +826,7 @@ json manifest_json = {
 
 c2pa::Builder builder(context, manifest_json.dump());
 
-// Same string as in ingredientIds above — that is what links the action.
+// Same label string as in ingredientIds above: that is what links the action.
 builder.add_ingredient(
     R"({
         "title": "photo.jpg",
@@ -833,12 +835,11 @@ builder.add_ingredient(
     })",
     archive_path);
 
+// Note that a signing, the SDK may reassign the labels
 builder.sign(source_path, output_path, signer);
 ```
 
-##### Using streams
-
-The `add_ingredient` overload that takes a `std::istream` (with `"application/c2pa"` as the format) follows the same rule — the `label` on the ingredient JSON is what links the action:
+The `add_ingredient` overload that takes a `std::istream` (with `"application/c2pa"` as the format) follows the same rules: the `label` on the ingredient JSON is what links the action:
 
 ```cpp
 std::ifstream archive_file("ingredient_archive.c2pa", std::ios::binary);
@@ -858,7 +859,7 @@ builder.sign(source_path, output_path, signer);
 
 ##### Previewing the archive before linking
 
-If you want to inspect the archive (e.g. to decide whether to use it, or to copy `title` from it), open it with `Reader` first, then add it as an ingredient. The Reader step is independent of the linking — the link is still established by the `label` on the signing builder's `add_ingredient` call.
+If you want to inspect the archive (e.g. to decide whether to use it, or to copy a `title` from it), open it with `Reader` first, then add it as an ingredient. The Reader step is independent of the linking: the link is still established by the `label` on the signing builder's `add_ingredient` call.
 
 ```cpp
 std::ifstream archive_file("ingredient_archive.c2pa", std::ios::binary);
diff --git a/tests/builder.test.cpp b/tests/builder.test.cpp
index 5dc94a0..bfe4787 100644
--- a/tests/builder.test.cpp
+++ b/tests/builder.test.cpp
@@ -4747,8 +4747,6 @@ TEST_F(BuilderTest, LinkArchiveLabelOnSigningBuilderOpened)
 
 TEST_F(BuilderTest, LinkArchiveLabelOnSigningBuilderOpenedFromStream)
 {
-    // Same as LinkArchiveLabelOnSigningBuilderOpened but feeds the archive
-    // through the std::istream overload of add_ingredient.
     auto archive_path = get_temp_path("label_on_signing_opened_stream.c2pa");
     create_ingredient_archive(archive_path,
         R"({"title": "photo.jpg", "relationship": "parentOf"})");
@@ -4798,9 +4796,6 @@ TEST_F(BuilderTest, LinkArchiveLabelOnSigningBuilderPlacedFromStream)
 
 TEST_F(BuilderTest, LinkArchiveInstanceIdOnSigningBuilderFromStreamFails)
 {
-    // Stream overload counterpart of LinkArchiveInstanceIdFromArchiveOnSigningBuilder.
-    // instance_id cannot be used as a linking key for ingredient archives,
-    // regardless of whether the archive is added via path or stream.
     auto context = c2pa::Context();
     auto signer = c2pa_test::create_test_signer();
     auto source_path = c2pa_test::get_fixture_path("A.jpg");
@@ -4850,31 +4845,6 @@ TEST_F(BuilderTest, LinkArchiveInstanceIdOnSigningBuilderFromStreamFails)
     EXPECT_THROW(builder.sign(source_path, output_path, signer), c2pa::C2paException);
 }
 
-TEST_F(BuilderTest, LinkArchiveBakedLabelAlsoSetOnSigningBuilder)
-{
-    // Probe: same baked label, AND the same label re-asserted on the signing
-    // builder's add_ingredient call. Should link successfully (signing-builder
-    // label is what counts).
-    auto archive_path = get_temp_path("baked_label_also_set.c2pa");
-    create_ingredient_archive(archive_path,
-        R"({"title": "photo.jpg", "relationship": "parentOf", "label": "baked-label"})");
-
-    auto manifest_json = make_manifest_with_action("c2pa.opened", "baked-label",
-        "http://cv.iptc.org/newscodes/digitalsourcetype/digitalCreation");
-    auto context = c2pa::Context();
-    auto builder = c2pa::Builder(context, manifest_json.dump());
-
-    builder.add_ingredient(
-        R"({"title": "photo.jpg", "relationship": "parentOf", "label": "baked-label"})",
-        archive_path);
-
-    auto signer = c2pa_test::create_test_signer();
-    auto output_path = get_temp_path("baked_label_also_set_result.jpg");
-
-    bool linked = verify_ingredient_linked(builder, output_path, signer, "c2pa.opened");
-    EXPECT_TRUE(linked);
-}
-
 TEST_F(BuilderTest, LinkArchiveTwoIngredientsUsingLabels)
 {
     auto archive1 = get_temp_path("two_labels_archive1.c2pa");

From 0a346700be58350f5303272f751b080233e70009 Mon Sep 17 00:00:00 2001
From: Tania Mathern <mathern@adobe.com>
Date: Mon, 4 May 2026 10:13:20 -0700
Subject: [PATCH 3/7] fix: Archives

---
 docs/selective-manifests.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/docs/selective-manifests.md b/docs/selective-manifests.md
index ff671c1..cc02757 100644
--- a/docs/selective-manifests.md
+++ b/docs/selective-manifests.md
@@ -741,7 +741,7 @@ auto parsed = json::parse(reader.json());
 std::string active = parsed["active_manifest"];
 auto manifest = parsed["manifests"][active];
 
-// An ingredient archive must always have exactly one ingredient
+// An ingredient archive must always contain exactly one ingredient
 auto& ingredient = manifest["ingredients"][0];
 
 // Relationship
@@ -859,7 +859,7 @@ builder.sign(source_path, output_path, signer);
 
 ##### Previewing the archive before linking
 
-If you want to inspect the archive (e.g. to decide whether to use it, or to copy a `title` from it), open it with `Reader` first, then add it as an ingredient. The Reader step is independent of the linking: the link is still established by the `label` on the signing builder's `add_ingredient` call.
+If you want to inspect the ingredient archive (e.g. to decide whether to use it, or to copy a `title` from it), open it with `Reader` first, then add it as an ingredient. The Reader step is independent of the linking: the link is still established by the `label` on the signing builder's `add_ingredient` call.
 
 ```cpp
 std::ifstream archive_file("ingredient_archive.c2pa", std::ios::binary);
@@ -888,21 +888,21 @@ builder.sign(source_path, output_path, signer);
 
 #### Troubleshooting linking errors
 
-The most common sign-time error when linking ingredients is:
+A common signing-time error when linking ingredients is:
 
 ```text
 Builder.sign failure: Other: assertion-specific error:
-Action ingredientId not found: <id>
+Action ingredientId not found: <some id>
 ```
 
-`<id>` is the value the SDK could not resolve to an ingredient on the builder. Causes and fixes:
+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. `instance_id` is for catalog identification, not action linking. | 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. | 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 byte-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. | See [Filtering actions that reference ingredients](#filtering-actions-that-reference-ingredients) — keep the ingredient and its binary resources alongside the action. |
+| `Action ingredientId not found: xmp:iid:...` (or any `instance_id` value) | `instance_id` was used as the linking key for an ingredient archive. | 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. | Re-assert the same `label` in the signing builder's `add_ingredient` JSON when calling `add_ingredient`. |
+| `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, as the string is a linking key. |
+| 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. | See [Filtering actions that reference ingredients](#filtering-actions-that-reference-ingredients) to 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.
 

From 067062c64fd42c3c2d8bb472e9b23bce39520b48 Mon Sep 17 00:00:00 2001
From: tmathern <60901087+tmathern@users.noreply.github.com>
Date: Mon, 4 May 2026 10:29:13 -0700
Subject: [PATCH 4/7] fix: Docs

---
 docs/selective-manifests.md |  6 ++++
 docs/working-stores.md      | 45 +++++++++++++++++++++--
 tests/builder.test.cpp      | 72 +++++++++++++++++++++++++++++++------
 3 files changed, 109 insertions(+), 14 deletions(-)

diff --git a/docs/selective-manifests.md b/docs/selective-manifests.md
index cc02757..bb82043 100644
--- a/docs/selective-manifests.md
+++ b/docs/selective-manifests.md
@@ -783,6 +783,12 @@ if (ingredient.contains("thumbnail")) {
 }
 ```
 
+#### Ingredient vs. ingredient archive
+
+A plain ingredient is a source asset (image, video, document) the builder reads at `add_ingredient` time, with `label` (primary) or `instance_id` (fallback) usable as linking keys. An ingredient archive is a `.c2pa` file containing one already-formed ingredient. When passed to `add_ingredient`, the builder treats its contents as opaque provenance. The only linking key the action can resolve is the `label` set on the *current* `add_ingredient` call.
+
+For a side-by-side comparison, see [Ingredient vs. ingredient archive](working-stores.md#ingredient-vs-ingredient-archive) in the working-stores doc.
+
 #### Linking an archived ingredient to an action
 
 Linking an **archived** ingredient to an action is **label-driven**: archived ingredients can only be linked to actions using labels.
diff --git a/docs/working-stores.md b/docs/working-stores.md
index d2b0847..8588c58 100644
--- a/docs/working-stores.md
+++ b/docs/working-stores.md
@@ -442,7 +442,24 @@ builder.sign("source.jpg", "signed.jpg", signer);
 
 Ingredients represent source materials used to create an asset, preserving the provenance chain. Ingredients themselves can be turned into ingredient archives (`.c2pa`).
 
-An ingredient archive is a serialized `Builder` with _exactly one_ ingredient.  Once archived with only one ingredient, the Builder archive is an ingredient archive. Such ingredient archives can be used as ingredient in other working stores.
+### Ingredient vs. ingredient archive
+
+A **plain ingredient** is a source asset (image, video, ...) that the builder reads at `add_ingredient` time. The builder sees the asset's bytes, and stores live required ingredient data (including any caller-set `instance_id`) inside the new manifest.
+
+An **ingredient archive** is a `.c2pa` file produced by `to_archive()` that already contains a fully-formed ingredient ("ready to use"). 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.
+
+This difference governs how each can be linked to an action via `ingredientIds`:
+
+| Aspect | Plain ingredient | Ingredient archive |
+| --- | --- | --- |
+| Source format passed to `add_ingredient` | Asset MIME type (`image/jpeg`, `video/mp4`, ...) or asset path | `application/c2pa` or path to a `.c2pa` file |
+| What `add_ingredient` sees | Live asset bytes | A serialized manifest store (opaque provenance) |
+| Linking via `label` set on the signing builder's `add_ingredient` JSON | Primary linking key | Only linking key that works |
+| Linking via `instance_id` on the `add_ingredient` JSON | Fallback when `label` is absent | Does not link; sign-time error |
+| Linking via a `label` baked in at archive-creation time | N/A (no archive involved) | Does not carry through; must be re-asserted on the signing builder |
+| Caller-set metadata that survives signing | `instance_id`, `description`, `informational_URI`, `title` | Same |
+
+See [Linking an ingredient archive to an action](#linking-an-ingredient-archive-to-an-action) for the consequences when linking.
 
 ### Adding ingredients to a working store
 
@@ -479,7 +496,16 @@ builder.sign("new_asset.jpg", "signed_asset.jpg", signer);
 
 ### Linking an ingredient archive to an action
 
-To link an ingredient archive to an action via `ingredientIds`, you must use a `label` set in the `add_ingredient` call on the signing builder. Labels baked into the archive ingredient are not carried through, and `instance_id` does not work as a linking key for ingredient archives regardless of where it is set.
+> [!IMPORTANT]
+> **Linking an ingredient archive is `label`-driven only.**
+>
+> - `instance_id` does not work as a linking key for ingredient archives — use `label`.
+> - Labels baked into the archive at archive-creation time do not carry through. The label must be re-asserted in the signing builder's `add_ingredient` JSON.
+> - Both rules apply whether the archive is added by file path or by stream.
+>
+> Attempting to link via `instance_id`, or relying on a baked-in label alone, produces a sign-time error: `Action ingredientId not found: <id>`. See [Troubleshooting linking errors](#troubleshooting-linking-errors).
+
+To link an ingredient archive to an action via `ingredientIds`, set a `label` on the JSON passed to `add_ingredient` on the signing builder, and use the same string in the action's `ingredientIds` array. (Why this differs from plain ingredients: see [Ingredient vs. ingredient archive](#ingredient-vs-ingredient-archive). To inspect an archive before deciding to use it, see [Reading ingredient details from an ingredient archive](selective-manifests.md#reading-ingredient-details-from-an-ingredient-archive).)
 
 ```cpp
 c2pa::Context context;
@@ -519,6 +545,19 @@ builder.add_ingredient(
 builder.sign("source.jpg", "signed.jpg", signer);
 ```
 
+The stream overload of `add_ingredient` (with `"application/c2pa"` as the format) accepts the same `label`-based linking: open the archive as a `std::ifstream` and pass it instead of the file path:
+
+```cpp
+std::ifstream archive_stream("ingredient.c2pa", std::ios::binary);
+builder.add_ingredient(
+    R"({"title": "photo.jpg", "relationship": "componentOf", "label": "my-ingredient"})",
+    "application/c2pa",
+    archive_stream);
+archive_stream.close();
+
+builder.sign("source.jpg", "signed.jpg", signer);
+```
+
 When linking multiple ingredient archives, give each a distinct label and reference it in the appropriate action's `ingredientIds` array.
 
 If each ingredient has its own action (e.g., one `c2pa.opened` for the parent and one `c2pa.placed` for a composited element), set up two actions with separate `ingredientIds`:
@@ -609,7 +648,7 @@ const std::string ingredient_json = R"({
 builder.add_ingredient(ingredient_json, "base_layer.png");
 ```
 
-## Working with archives 
+## Working with archives
 
 An *archive* (C2PA archive) is a serialized working store (`Builder` object) saved to a file or stream.
 
diff --git a/tests/builder.test.cpp b/tests/builder.test.cpp
index bfe4787..11d7cdd 100644
--- a/tests/builder.test.cpp
+++ b/tests/builder.test.cpp
@@ -4747,14 +4747,43 @@ TEST_F(BuilderTest, LinkArchiveLabelOnSigningBuilderOpened)
 
 TEST_F(BuilderTest, LinkArchiveLabelOnSigningBuilderOpenedFromStream)
 {
-    auto archive_path = get_temp_path("label_on_signing_opened_stream.c2pa");
-    create_ingredient_archive(archive_path,
-        R"({"title": "photo.jpg", "relationship": "parentOf"})");
-
-    auto manifest_json = make_manifest_with_action("c2pa.opened", "my-ingredient",
-        "http://cv.iptc.org/newscodes/digitalsourcetype/digitalCreation");
+    // Test scenario:
+    // 1. Create the .c2pa ingredient archive.
+    // 2. Build a signing manifest whose action references a chosen label.
+    // 3. Open the archive as std::ifstream and add it via the stream
+    // overload, setting the same label on the ingredient JSON.
+    // 4. Sign, then read back and verify the action linked to the ingredient.
     auto context = c2pa::Context();
-    auto builder = c2pa::Builder(context, manifest_json.dump());
+    auto signer = c2pa_test::create_test_signer();
+    auto source_path = c2pa_test::get_fixture_path("A.jpg");
+    auto fixture_path = c2pa_test::get_fixture_path("A.jpg");
+
+    auto archive_path = get_temp_path("link_label_opened_stream_full_flow.c2pa");
+    {
+        auto archive_manifest = c2pa_test::read_text_file(c2pa_test::get_fixture_path("training.json"));
+        auto archive_builder = c2pa::Builder(context, archive_manifest);
+        archive_builder.add_ingredient(
+            R"({"title": "photo.jpg", "relationship": "parentOf"})",
+            fixture_path);
+        archive_builder.to_archive(archive_path);
+    }
+
+    json signing_manifest = {
+        {"claim_generator_info", json::array({{{"name", "c2pa-test"}, {"version", "1.0"}}})},
+        {"assertions", json::array({
+            {
+                {"label", "c2pa.actions.v2"},
+                {"data", {{"actions", json::array({
+                    {
+                        {"action", "c2pa.opened"},
+                        {"digitalSourceType", "http://cv.iptc.org/newscodes/digitalsourcetype/digitalCreation"},
+                        {"parameters", {{"ingredientIds", json::array({"my-ingredient"})}}}
+                    }
+                })}}}
+            }
+        })}
+    };
+    auto builder = c2pa::Builder(context, signing_manifest.dump());
 
     std::ifstream archive_stream(archive_path, std::ios::binary);
     builder.add_ingredient(
@@ -4763,11 +4792,32 @@ TEST_F(BuilderTest, LinkArchiveLabelOnSigningBuilderOpenedFromStream)
         archive_stream);
     archive_stream.close();
 
-    auto signer = c2pa_test::create_test_signer();
-    auto output_path = get_temp_path("link_label_on_signing_opened_stream.jpg");
+    auto output_path = get_temp_path("link_label_opened_stream_full_flow_result.jpg");
+    ASSERT_NO_THROW(builder.sign(source_path, output_path, signer));
 
-    bool linked = verify_ingredient_linked(builder, output_path, signer, "c2pa.opened");
-    EXPECT_TRUE(linked);
+    auto reader = c2pa::Reader(context, output_path);
+    auto parsed = json::parse(reader.json());
+    std::string active = parsed["active_manifest"];
+    auto& manifest = parsed["manifests"][active];
+
+    bool found_action = false;
+    std::string resolved_url;
+    for (auto& assertion : manifest["assertions"]) {
+        if (assertion["label"] != "c2pa.actions.v2") continue;
+        for (auto& action : assertion["data"]["actions"]) {
+            if (action["action"] != "c2pa.opened") continue;
+            found_action = true;
+            ASSERT_TRUE(action.contains("parameters"));
+            ASSERT_TRUE(action["parameters"].contains("ingredients"));
+            auto& ingredients = action["parameters"]["ingredients"];
+            ASSERT_TRUE(ingredients.is_array());
+            ASSERT_EQ(ingredients.size(), 1u);
+            resolved_url = ingredients[0]["url"];
+        }
+    }
+    ASSERT_TRUE(found_action) << "c2pa.opened action not found in signed manifest";
+    EXPECT_EQ(resolved_url, "self#jumbf=c2pa.assertions/c2pa.ingredient.v3")
+        << "Action did not resolve to the linked ingredient";
 }
 
 TEST_F(BuilderTest, LinkArchiveLabelOnSigningBuilderPlacedFromStream)

From 4fe23470b5a03fc5306e60481b14f73c2e3785eb Mon Sep 17 00:00:00 2001
From: Tania Mathern <mathern@adobe.com>
Date: Mon, 4 May 2026 10:41:11 -0700
Subject: [PATCH 5/7] fix: Archives

---
 docs/selective-manifests.md |  2 +-
 docs/working-stores.md      | 15 ++++++---------
 2 files changed, 7 insertions(+), 10 deletions(-)

diff --git a/docs/selective-manifests.md b/docs/selective-manifests.md
index bb82043..0147a22 100644
--- a/docs/selective-manifests.md
+++ b/docs/selective-manifests.md
@@ -884,7 +884,7 @@ builder.add_ingredient(
     json({
         {"title", ingredient["title"]},
         {"relationship", "parentOf"},
-        {"label", "archived-ingredient"}  // The linking key — chosen here, not read from the archive.
+        {"label", "archived-ingredient"}  // The linking key: chosen here, not read from the archive.
     }).dump(),
     "application/c2pa",
     archive_file);
diff --git a/docs/working-stores.md b/docs/working-stores.md
index 8588c58..7fa7db7 100644
--- a/docs/working-stores.md
+++ b/docs/working-stores.md
@@ -444,22 +444,19 @@ Ingredients represent source materials used to create an asset, preserving the p
 
 ### Ingredient vs. ingredient archive
 
-A **plain ingredient** is a source asset (image, video, ...) that the builder reads at `add_ingredient` time. The builder sees the asset's bytes, and stores live required ingredient data (including any caller-set `instance_id`) inside the new manifest.
+A **(plain) ingredient** is a source asset that the builder reads at `add_ingredient` time. The builder sees the asset's bytes, and stores live required ingredient data (including any caller-set `instance_id`) inside the new manifest.
 
-An **ingredient archive** is a `.c2pa` file produced by `to_archive()` that already contains a fully-formed ingredient ("ready to use"). 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.
+An **ingredient archive** (in c2pa-archive-format) is a `.c2pa` file produced by `to_archive()` that already contains a fully-formed ingredient ("ready to use"). 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.
 
 This difference governs how each can be linked to an action via `ingredientIds`:
 
-| Aspect | Plain ingredient | Ingredient archive |
+| Aspect | Ingredient | Ingredient archive |
 | --- | --- | --- |
 | Source format passed to `add_ingredient` | Asset MIME type (`image/jpeg`, `video/mp4`, ...) or asset path | `application/c2pa` or path to a `.c2pa` file |
-| What `add_ingredient` sees | Live asset bytes | A serialized manifest store (opaque provenance) |
+| What `add_ingredient` sees | "Live" asset | A serialized manifest store (opaque provenance) |
 | Linking via `label` set on the signing builder's `add_ingredient` JSON | Primary linking key | Only linking key that works |
-| Linking via `instance_id` on the `add_ingredient` JSON | Fallback when `label` is absent | Does not link; sign-time error |
-| Linking via a `label` baked in at archive-creation time | N/A (no archive involved) | Does not carry through; must be re-asserted on the signing builder |
-| Caller-set metadata that survives signing | `instance_id`, `description`, `informational_URI`, `title` | Same |
-
-See [Linking an ingredient archive to an action](#linking-an-ingredient-archive-to-an-action) for the consequences when linking.
+| Linking via `instance_id` on the `add_ingredient` JSON | Fallback when `label` is absent | Does not link, sign-time error |
+| Linking via a `label` baked in at archive-creation time | N/A (not an archive) | Does not carry through, must be re-asserted on the signing builder |
 
 ### Adding ingredients to a working store
 

From d742b3ded8a1f3e96df2d5ca3b5455e1e406a660 Mon Sep 17 00:00:00 2001
From: Tania Mathern <mathern@adobe.com>
Date: Mon, 4 May 2026 13:18:11 -0700
Subject: [PATCH 6/7] fix: Archives

---
 docs/working-stores.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/working-stores.md b/docs/working-stores.md
index 7fa7db7..46398ac 100644
--- a/docs/working-stores.md
+++ b/docs/working-stores.md
@@ -446,17 +446,17 @@ Ingredients represent source materials used to create an asset, preserving the p
 
 A **(plain) ingredient** is a source asset that the builder reads at `add_ingredient` time. The builder sees the asset's bytes, and stores live required ingredient data (including any caller-set `instance_id`) inside the new manifest.
 
-An **ingredient archive** (in c2pa-archive-format) is a `.c2pa` file produced by `to_archive()` that already contains a fully-formed ingredient ("ready to use"). 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.
+An **ingredient archive** (in c2pa-archive-format) is a `.c2pa` file produced by `to_archive()` that already contains a fully-formed ingredient ("a ready to use ingredient"). 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.
 
 This difference governs how each can be linked to an action via `ingredientIds`:
 
 | Aspect | Ingredient | Ingredient archive |
 | --- | --- | --- |
-| Source format passed to `add_ingredient` | Asset MIME type (`image/jpeg`, `video/mp4`, ...) or asset path | `application/c2pa` or path to a `.c2pa` file |
-| What `add_ingredient` sees | "Live" asset | A serialized manifest store (opaque provenance) |
-| Linking via `label` set on the signing builder's `add_ingredient` JSON | Primary linking key | Only linking key that works |
-| Linking via `instance_id` on the `add_ingredient` JSON | Fallback when `label` is absent | Does not link, sign-time error |
-| Linking via a `label` baked in at archive-creation time | N/A (not an archive) | Does not carry through, must be re-asserted on the signing builder |
+| Source format passed to `add_ingredient` | Asset MIME type (`image/jpeg`, `video/mp4`, ...) or asset path | `application/c2pa` or path to a `.c2pa` ingredient archive file |
+| What it is | "Live" asset | A serialized manifest store (opaque provenance) |
+| Linking via `label` | Primary linking key, set on the signing builder's `add_ingredient` JSON parameter | Only linking key that works, set on the signing builder's `add_ingredient` JSON |
+| Linking via `instance_id` | Alternative to using `label` | Does not link, signing-time error |
+| Linking via a `label` baked in at archive-creation time | N/A (not an archive) | Does not carry through, must be re-asserted on the signing builder, set on the signing builder's `add_ingredient` JSON parameter |
 
 ### Adding ingredients to a working store
 

From a88aeed5c0083968ed7adc38541843094c6315c2 Mon Sep 17 00:00:00 2001
From: Tania Mathern <mathern@adobe.com>
Date: Mon, 4 May 2026 13:22:03 -0700
Subject: [PATCH 7/7] fix: Details

---
 docs/selective-manifests.md | 2 +-
 docs/working-stores.md      | 5 +++--
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/selective-manifests.md b/docs/selective-manifests.md
index 0147a22..ff674b8 100644
--- a/docs/selective-manifests.md
+++ b/docs/selective-manifests.md
@@ -802,7 +802,7 @@ Reading the archive first is *not* required to link it. `Reader` is only useful
 >
 > **Labels baked into the archive ingredient at archive-creation time do not carry through as linking keys either.** The label must be re-asserted on the signing builder's `add_ingredient` call so action and archived ingredient properly link.
 
-Labels are build-time linking keys only. The SDK may reassign the actual label in the signed manifest.
+Labels are build-time linking keys only. A label, as linking key, links ingredients and actions using it together: the label identifies the link. The SDK may reassign the actual label in the signed manifest.
 
 ##### Minimal archive to action linking example
 
diff --git a/docs/working-stores.md b/docs/working-stores.md
index 46398ac..c8211b2 100644
--- a/docs/working-stores.md
+++ b/docs/working-stores.md
@@ -496,13 +496,14 @@ builder.sign("new_asset.jpg", "signed_asset.jpg", signer);
 > [!IMPORTANT]
 > **Linking an ingredient archive is `label`-driven only.**
 >
-> - `instance_id` does not work as a linking key for ingredient archives — use `label`.
+> - `instance_id` does not work as a linking key for ingredient archives, use `label` instead.
 > - Labels baked into the archive at archive-creation time do not carry through. The label must be re-asserted in the signing builder's `add_ingredient` JSON.
 > - Both rules apply whether the archive is added by file path or by stream.
 >
 > Attempting to link via `instance_id`, or relying on a baked-in label alone, produces a sign-time error: `Action ingredientId not found: <id>`. See [Troubleshooting linking errors](#troubleshooting-linking-errors).
 
-To link an ingredient archive to an action via `ingredientIds`, set a `label` on the JSON passed to `add_ingredient` on the signing builder, and use the same string in the action's `ingredientIds` array. (Why this differs from plain ingredients: see [Ingredient vs. ingredient archive](#ingredient-vs-ingredient-archive). To inspect an archive before deciding to use it, see [Reading ingredient details from an ingredient archive](selective-manifests.md#reading-ingredient-details-from-an-ingredient-archive).)
+To link an ingredient archive to an action via `ingredientIds`, set a `label` on the JSON passed to `add_ingredient` on the signing builder, and use the same string in the action's `ingredientIds` array. A label, as linking key, links ingredients and actions using it together: the label identifies the link. Labels are build-time linking keys only. The SDK may reassign the actual label in the signed manifest during signing.
+
 
 ```cpp
 c2pa::Context context;