@ggui-ai/artifact-manifest 0.2.0-alpha.4 → 0.3.0-rc.0

package/README.md

@@ -34,14 +34,14 @@ const artifact = parseArtifactManifest(json);
 
 ## Exports
 
-| Symbol                                                                                                            | What it is                                 |
-| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
-| `gadgetManifestSchema`, `parseGadgetManifest`, `safeParseGadgetManifest`, `assertGadgetManifestValid`             | Gadget manifest schema + parsers           |
-| `blueprintManifestSchema`, `parseBlueprintManifest`, `safeParseBlueprintManifest`, `assertBlueprintManifestValid` | Blueprint manifest schema + parsers        |
-| `artifactManifestSchema`, `parseArtifactManifest`, `safeParseArtifactManifest`, `assertArtifactManifestValid`     | Discriminated union over both kinds        |
-| `manifestToRegistryEntry`                                                                                         | Translate a manifest into a registry entry |
-| `GADGET_NAME_RE`, `BLUEPRINT_NAME_RE`, `ArtifactScopeSchema`, `ArtifactVersionSchema`                             | Shared name + version validators           |
-| `GGUI_GADGET_JSON_FILENAME`, `GGUI_BLUEPRINT_JSON_FILENAME`                                                       | Canonical manifest filenames               |
+| Symbol                                                                                | What it is                                 |
+| ------------------------------------------------------------------------------------- | ------------------------------------------ |
+| `gadgetManifestSchema`, `parseGadgetManifest`, `safeParseGadgetManifest`              | Gadget manifest schema + parsers           |
+| `blueprintManifestSchema`, `parseBlueprintManifest`, `safeParseBlueprintManifest`     | Blueprint manifest schema + parsers        |
+| `artifactManifestSchema`, `parseArtifactManifest`, `safeParseArtifactManifest`        | Discriminated union over both kinds        |
+| `manifestToRegistryEntry`                                                             | Translate a manifest into a registry entry |
+| `GADGET_NAME_RE`, `BLUEPRINT_NAME_RE`, `ArtifactScopeSchema`, `ArtifactVersionSchema` | Shared name + version validators           |
+| `GGUI_GADGET_JSON_FILENAME`, `GGUI_BLUEPRINT_JSON_FILENAME`                           | Canonical manifest filenames               |
 
 `GadgetManifest`, `BlueprintManifest`, and `ArtifactManifest` types are exported alongside their schemas.
 

package/dist/artifact-manifest.d.ts

@@ -89,6 +89,8 @@ export declare const artifactManifestSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
     contract: z.ZodOptional<z.ZodType<import("@ggui-ai/protocol").DataContract, unknown, z.core.$ZodTypeInternals<import("@ggui-ai/protocol").DataContract, unknown>>>;
     fixtureProps: z.ZodOptional<z.ZodUnknown>;
     variance: z.ZodOptional<z.ZodType<import("@ggui-ai/protocol").BlueprintVariance, unknown, z.core.$ZodTypeInternals<import("@ggui-ai/protocol").BlueprintVariance, unknown>>>;
+    generatorProtocolVersion: z.ZodOptional<z.ZodString>;
+    toolIdentityCatalogHash: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>], "kind">;
 /**
  * Static TypeScript type derived from {@link artifactManifestSchema}.
@@ -104,11 +106,6 @@ export type ArtifactManifest = z.infer<typeof artifactManifestSchema>;
  * including unknown / missing `kind` discriminator at `path: ["kind"]`.
  */
 export declare function parseArtifactManifest(raw: unknown): ArtifactManifest;
-/**
- * Assertion helper — narrows `raw` to {@link ArtifactManifest} on
- * success, throws `ZodError` on failure.
- */
-export declare function assertArtifactManifestValid(raw: unknown): asserts raw is ArtifactManifest;
 /**
  * Safe-parse variant — returns a `z.safeParse` result. Prefer this
  * inside CLI tooling where you want to render the issue list without

package/dist/artifact-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifact-manifest.d.ts","sourceRoot":"","sources":["../src/artifact-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAGjC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAatE;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAEpE;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,GAAG,IAAI,gBAAgB,CAEjC;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,sBAAsB,CAAC,SAAS,CAAC,CAErD"}
+{"version":3,"file":"artifact-manifest.d.ts","sourceRoot":"","sources":["../src/artifact-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAGjC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAatE;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,sBAAsB,CAAC,SAAS,CAAC,CAErD"}

package/dist/artifact-manifest.js

@@ -52,13 +52,6 @@ void _artifactUnionTypeCheck;
 export function parseArtifactManifest(raw) {
     return artifactManifestSchema.parse(raw);
 }
-/**
- * Assertion helper — narrows `raw` to {@link ArtifactManifest} on
- * success, throws `ZodError` on failure.
- */
-export function assertArtifactManifestValid(raw) {
-    artifactManifestSchema.parse(raw);
-}
 /**
  * Safe-parse variant — returns a `z.safeParse` result. Prefer this
  * inside CLI tooling where you want to render the issue list without

package/dist/base.d.ts

@@ -52,17 +52,17 @@ export declare const BLUEPRINT_NAME_RE: RegExp;
  */
 export declare const ArtifactVersionSchema: z.ZodString;
 /**
- * Visibility — controls how the artifact is stored + distributed:
+ * Visibility — controls how the artifact is signed + distributed:
  *
- *   - `public`  — sigstore-signed, served from S3 `public/` prefix,
- *                 publicly listable via `/search`.
- *   - `private` — Ed25519-signed, served from `private/<orgId>/`
- *                 with signed CloudFront URLs, only visible to the
- *                 publisher's Cognito org.
+ *   - `public`  — sigstore-signed, publicly listable via `/search`.
+ *   - `private` — Ed25519-signed, scoped to the publisher's org;
+ *                 never publicly listable.
  *
  * Both paths land in the same registry stack; the visibility flag
- * picks the signing trust chain + S3 prefix at publish time. No
- * "internal" / "team" third option in MVP.
+ * picks the signing trust chain at publish time. How a registry
+ * implementation partitions storage or gates download URLs per
+ * visibility is the storage adapter's concern. No "internal" /
+ * "team" third option in MVP.
  */
 export declare const ArtifactVisibilitySchema: z.ZodEnum<{
     public: "public";

package/dist/base.js

@@ -60,17 +60,17 @@ export const ArtifactVersionSchema = z
     message: 'version must be valid semver (MAJOR.MINOR.PATCH with optional `-pre` / `+build`).',
 });
 /**
- * Visibility — controls how the artifact is stored + distributed:
+ * Visibility — controls how the artifact is signed + distributed:
  *
- *   - `public`  — sigstore-signed, served from S3 `public/` prefix,
- *                 publicly listable via `/search`.
- *   - `private` — Ed25519-signed, served from `private/<orgId>/`
- *                 with signed CloudFront URLs, only visible to the
- *                 publisher's Cognito org.
+ *   - `public`  — sigstore-signed, publicly listable via `/search`.
+ *   - `private` — Ed25519-signed, scoped to the publisher's org;
+ *                 never publicly listable.
  *
  * Both paths land in the same registry stack; the visibility flag
- * picks the signing trust chain + S3 prefix at publish time. No
- * "internal" / "team" third option in MVP.
+ * picks the signing trust chain at publish time. How a registry
+ * implementation partitions storage or gates download URLs per
+ * visibility is the storage adapter's concern. No "internal" /
+ * "team" third option in MVP.
  */
 export const ArtifactVisibilitySchema = z.enum(['public', 'private']);
 /**

package/dist/blueprint-manifest.d.ts

@@ -14,21 +14,24 @@
  *     hints that drive the LLM-driven variant selector when multiple
  *     blueprints share a `(appId, contractHash)` group.
  *
- * ## In-process counterpart
+ * ## Relation to `ggui_ops_register_blueprint`
  *
- * The in-process registration tool at
- * `cloud/ggui-protocol-pod/src/tools/register-blueprint.ts` accepts
- * `{source, contract?, fixtureProps?}` and a slug
- * `^[a-z0-9][a-z0-9_-]{0,63}$`. This manifest's `source` /
- * `contract` / `fixtureProps` fields mirror that envelope exactly
- * — round-tripping a blueprint through
- * `ggui_ops_register_blueprint` then exporting it back into a
- * `ggui.blueprint.json` must not require any field rewriting beyond
- * adding the marketplace identity (`scope`, `name`, `version`,
- * `kind`, `visibility`) and optional variance tags.
+ * The operator registration tool `ggui_ops_register_blueprint`
+ * (`@ggui-ai/mcp-server-handlers`) takes `{contract, componentCode,
+ * generator?, persona?, aesthetic?, context?, seedPrompt?,
+ * setAsOperatorDefault?}`. Mapping a manifest onto that envelope:
  *
- * The `name` regex matches the in-process slug rule
- * ({@link BLUEPRINT_NAME_RE}) — diverging would break round-trip.
+ *   - `source`            → `componentCode` (verbatim TSX body).
+ *   - `contract`          → `contract` (optional on the manifest,
+ *                           REQUIRED by the tool — a contract-less
+ *                           manifest cannot be registered as-is).
+ *   - `variance`          → the flat `persona` / `aesthetic` /
+ *                           `context` / `seedPrompt` fields.
+ *   - `fixtureProps`      → no counterpart. Conformance-gate-only:
+ *                           consumed by the registry's runtime probe,
+ *                           never sent on the register envelope.
+ *   - marketplace identity (`scope`, `name`, `version`, `kind`,
+ *     `visibility`) → no counterpart; registry-side only.
  *
  * ## Why no `matchers` field
  *
@@ -88,6 +91,8 @@ export declare const blueprintManifestSchema: z.ZodObject<{
     contract: z.ZodOptional<z.ZodType<DataContract, unknown, z.core.$ZodTypeInternals<DataContract, unknown>>>;
     fixtureProps: z.ZodOptional<z.ZodUnknown>;
     variance: z.ZodOptional<z.ZodType<BlueprintVariance, unknown, z.core.$ZodTypeInternals<BlueprintVariance, unknown>>>;
+    generatorProtocolVersion: z.ZodOptional<z.ZodString>;
+    toolIdentityCatalogHash: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 /**
  * Static TypeScript type derived from {@link blueprintManifestSchema}.
@@ -113,11 +118,6 @@ export declare const GGUI_BLUEPRINT_JSON_FILENAME = "ggui.blueprint.json";
  * decoded the JSON (`JSON.parse(source)`).
  */
 export declare function parseBlueprintManifest(raw: unknown): BlueprintManifest;
-/**
- * Assertion helper — narrows `raw` to {@link BlueprintManifest} on
- * success, throws `ZodError` on failure.
- */
-export declare function assertBlueprintManifestValid(raw: unknown): asserts raw is BlueprintManifest;
 /**
  * Safe-parse variant — returns a discriminated `z.safeParse` result
  * (`{ success: true, data }` vs `{ success: false, error }`).

package/dist/blueprint-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blueprint-manifest.d.ts","sourceRoot":"","sources":["../src/blueprint-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAGlB,MAAM,mBAAmB,CAAC;AAgC3B;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;kBAiDlC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAmBxE;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,wBAAwB,CAAC;AAElE;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,CAEtE;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,GAAG,IAAI,iBAAiB,CAElC;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,uBAAuB,CAAC,SAAS,CAAC,CAEtD"}
+{"version":3,"file":"blueprint-manifest.d.ts","sourceRoot":"","sources":["../src/blueprint-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAGlB,MAAM,mBAAmB,CAAC;AA+B3B;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;kBAiElC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAmBxE;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,wBAAwB,CAAC;AAElE;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,CAEtE;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,uBAAuB,CAAC,SAAS,CAAC,CAEtD"}

package/dist/blueprint-manifest.js

@@ -14,21 +14,24 @@
  *     hints that drive the LLM-driven variant selector when multiple
  *     blueprints share a `(appId, contractHash)` group.
  *
- * ## In-process counterpart
+ * ## Relation to `ggui_ops_register_blueprint`
  *
- * The in-process registration tool at
- * `cloud/ggui-protocol-pod/src/tools/register-blueprint.ts` accepts
- * `{source, contract?, fixtureProps?}` and a slug
- * `^[a-z0-9][a-z0-9_-]{0,63}$`. This manifest's `source` /
- * `contract` / `fixtureProps` fields mirror that envelope exactly
- * — round-tripping a blueprint through
- * `ggui_ops_register_blueprint` then exporting it back into a
- * `ggui.blueprint.json` must not require any field rewriting beyond
- * adding the marketplace identity (`scope`, `name`, `version`,
- * `kind`, `visibility`) and optional variance tags.
+ * The operator registration tool `ggui_ops_register_blueprint`
+ * (`@ggui-ai/mcp-server-handlers`) takes `{contract, componentCode,
+ * generator?, persona?, aesthetic?, context?, seedPrompt?,
+ * setAsOperatorDefault?}`. Mapping a manifest onto that envelope:
  *
- * The `name` regex matches the in-process slug rule
- * ({@link BLUEPRINT_NAME_RE}) — diverging would break round-trip.
+ *   - `source`            → `componentCode` (verbatim TSX body).
+ *   - `contract`          → `contract` (optional on the manifest,
+ *                           REQUIRED by the tool — a contract-less
+ *                           manifest cannot be registered as-is).
+ *   - `variance`          → the flat `persona` / `aesthetic` /
+ *                           `context` / `seedPrompt` fields.
+ *   - `fixtureProps`      → no counterpart. Conformance-gate-only:
+ *                           consumed by the registry's runtime probe,
+ *                           never sent on the register envelope.
+ *   - marketplace identity (`scope`, `name`, `version`, `kind`,
+ *     `visibility`) → no counterpart; registry-side only.
  *
  * ## Why no `matchers` field
  *
@@ -70,8 +73,7 @@ const BlueprintNameSchema = z.string().min(2).max(64).regex(BLUEPRINT_NAME_RE, {
  * runtime probe round-trips it through `JSON.stringify` and feeds it
  * as `props` to the rendered TSX. Any JSON-safe shape rides through;
  * the blueprint's own `contract.propsSchema` (when present) is what
- * actually validates the shape at runtime probe time. Mirrors the
- * in-process register-blueprint's `fixtureProps: z.unknown().optional()`.
+ * actually validates the shape at runtime probe time.
  *
  * `z.unknown()` is permitted here (not `Record<string, unknown>`)
  * because the value is genuinely shape-unknown at THIS layer — only
@@ -94,13 +96,13 @@ export const blueprintManifestSchema = z.strictObject({
         .describe('Discriminator — picks the blueprint variant of the artifact-manifest union. MUST be the literal string `"blueprint"`.'),
     // ---- Identity (required) ----
     scope: ArtifactScopeSchema.describe('Blueprint scope. Must start with `@` (e.g. `@my-org`). Disambiguates the `<scope>/<name>` install identifier.'),
-    name: BlueprintNameSchema.describe('Blueprint slug. 2-64 chars, `^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$` — kebab-case, no underscores, no single-character names. Unified with the gadget naming rule under LOCKED-25 (2026-05-18). The in-process `ggui_ops_register_blueprint` slug rule mirrors this for round-trip preservation.'),
+    name: BlueprintNameSchema.describe('Blueprint slug. 2-64 chars, `^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$` — kebab-case, no underscores, no single-character names. Unified with the gadget naming rule under LOCKED-25 (2026-05-18).'),
     version: ArtifactVersionSchema.describe('SemVer. `MAJOR.MINOR.PATCH` with optional `-pre` / `+build` suffixes. Per-version immutable once published.'),
     // ---- Core blueprint shape (required: source) ----
     source: z
         .string()
         .min(1)
-        .describe('TSX source body with a default-exported React component. Mirrors the in-process register-blueprint `blueprint.source` field — the conformance gate compiles + runtime-probes this string before the registry accepts the upload.'),
+        .describe('TSX source body with a default-exported React component. Maps to `ggui_ops_register_blueprint`’s `componentCode` field; the conformance gate compiles + runtime-probes this string before the registry accepts the upload.'),
     visibility: ArtifactVisibilitySchema.describe('Storage + signing posture. `public` = sigstore-signed, listable; `private` = Ed25519-signed, visible only within publisher org.'),
     // ---- Optional core blueprint shape ----
     contract: dataContractSchema
@@ -112,6 +114,17 @@ export const blueprintManifestSchema = z.strictObject({
     variance: blueprintVarianceSchema
         .optional()
         .describe("Persona + aesthetic + context + seedPrompt hints that drive the LLM-driven variant selector when multiple blueprints share a `(appId, contractHash)` group. Mirrors `Blueprint.variance` in `@ggui-ai/protocol`."),
+    // ---- Persistence-contract stamps (mirrors `PortableBlueprint`) ----
+    generatorProtocolVersion: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('PROTOCOL_VERSION of the toolchain that authored + signed this manifest. Import gates compare it against the importing deployment’s era before admitting the blueprint into a reuse pool — an era mismatch (or a missing stamp) drops the row loudly instead of serving code generated against a different protocol shape. Publishing tools stamp this automatically right before signing; deployments that consume installed blueprints into a matcher pool require it.'),
+    toolIdentityCatalogHash: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('SHA256(16) of the tool-identity catalog used to canonicalize `contract` at authoring time. Importers re-canonicalize against their own catalog and recompute the key; a divergence means the same intent would mis-key and silently cold-gen, so it is rejected. Optional — most marketplace blueprints are authored without a live tool catalog, which leaves the import gate’s re-key check inert.'),
     // ---- Shared metadata ----
     ...sharedMetadataShape,
 });
@@ -143,13 +156,6 @@ export const GGUI_BLUEPRINT_JSON_FILENAME = 'ggui.blueprint.json';
 export function parseBlueprintManifest(raw) {
     return blueprintManifestSchema.parse(raw);
 }
-/**
- * Assertion helper — narrows `raw` to {@link BlueprintManifest} on
- * success, throws `ZodError` on failure.
- */
-export function assertBlueprintManifestValid(raw) {
-    blueprintManifestSchema.parse(raw);
-}
 /**
  * Safe-parse variant — returns a discriminated `z.safeParse` result
  * (`{ success: true, data }` vs `{ success: false, error }`).

package/dist/gadget-manifest.d.ts

@@ -130,8 +130,8 @@ export declare const gadgetManifestSchema: z.ZodObject<{
      *   3. THIS field — gadget author's default
      *   4. spec default `registry.ggui.ai`
      *
-     * Most wrappers omit this (they publish to the hosted registry, and
-     * the spec default covers them). Set this only when the wrapper ships
+     * Most wrappers omit this (they publish to the default registry,
+     * and the spec default covers them). Set this only when the wrapper ships
      * via a non-default registry (private org registry, sandbox-only
      * fixture, …). The operator override remains the right knob for
      * sandbox-vs-prod swaps.
@@ -163,13 +163,6 @@ export declare const GGUI_GADGET_JSON_FILENAME = "ggui.gadget.json";
  * decoded the JSON (`JSON.parse(source)`).
  */
 export declare function parseGadgetManifest(raw: unknown): GadgetManifest;
-/**
- * Assertion helper — narrows `raw` to {@link GadgetManifest} on
- * success, throws `ZodError` on failure. Useful when the caller wants
- * to keep the original reference (rather than the parsed copy
- * `parseGadgetManifest` returns).
- */
-export declare function assertGadgetManifestValid(raw: unknown): asserts raw is GadgetManifest;
 /**
  * Safe-parse variant — returns a discriminated `z.safeParse` result
  * (`{ success: true, data }` vs `{ success: false, error }`). Prefer

package/dist/gadget-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gadget-manifest.d.ts","sourceRoot":"","sources":["../src/gadget-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAsFxB;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;oBAwB7B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA4D/B;;;;;OAKG;;;IAcH;;;;;;;;;;;;;;;;;OAiBG;;kBAwBH,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,qBAAqB,CAAC;AAE5D;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,GAAG,IAAI,cAAc,CAE/B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,oBAAoB,CAAC,SAAS,CAAC,CAEnD"}
+{"version":3,"file":"gadget-manifest.d.ts","sourceRoot":"","sources":["../src/gadget-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAsFxB;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;oBAwB7B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA4D/B;;;;;OAKG;;;IAcH;;;;;;;;;;;;;;;;;OAiBG;;kBAwBH,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,qBAAqB,CAAC;AAE5D;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,oBAAoB,CAAC,SAAS,CAAC,CAEnD"}

package/dist/gadget-manifest.js

@@ -207,8 +207,8 @@ export const gadgetManifestSchema = z.strictObject({
      *   3. THIS field — gadget author's default
      *   4. spec default `registry.ggui.ai`
      *
-     * Most wrappers omit this (they publish to the hosted registry, and
-     * the spec default covers them). Set this only when the wrapper ships
+     * Most wrappers omit this (they publish to the default registry,
+     * and the spec default covers them). Set this only when the wrapper ships
      * via a non-default registry (private org registry, sandbox-only
      * fixture, …). The operator override remains the right knob for
      * sandbox-vs-prod swaps.
@@ -250,15 +250,6 @@ export const GGUI_GADGET_JSON_FILENAME = 'ggui.gadget.json';
 export function parseGadgetManifest(raw) {
     return gadgetManifestSchema.parse(raw);
 }
-/**
- * Assertion helper — narrows `raw` to {@link GadgetManifest} on
- * success, throws `ZodError` on failure. Useful when the caller wants
- * to keep the original reference (rather than the parsed copy
- * `parseGadgetManifest` returns).
- */
-export function assertGadgetManifestValid(raw) {
-    gadgetManifestSchema.parse(raw);
-}
 /**
  * Safe-parse variant — returns a discriminated `z.safeParse` result
  * (`{ success: true, data }` vs `{ success: false, error }`). Prefer

package/dist/index.d.ts

@@ -11,14 +11,19 @@
  * kinds for tooling that handles them generically (signing, registry
  * upload, search-index ingestion).
  *
+ * Also the single owner of the seed-pool wrapper-artifact format
+ * (`pool-artifact.ts`) — the `manifest.json` + `codes/` directory
+ * layout that pool exporters write and seed-pool readers consume.
+ *
  * Browser-safe (no Node dependencies) — pure schema + parsers.
  */
-export { GGUI_GADGET_JSON_FILENAME, assertGadgetManifestValid, parseGadgetManifest, gadgetManifestSchema, gadgetExportSchema, safeParseGadgetManifest, } from './gadget-manifest.js';
+export { GGUI_GADGET_JSON_FILENAME, parseGadgetManifest, gadgetManifestSchema, gadgetExportSchema, safeParseGadgetManifest, } from './gadget-manifest.js';
 export type { GadgetManifest } from './gadget-manifest.js';
-export { GGUI_BLUEPRINT_JSON_FILENAME, assertBlueprintManifestValid, blueprintManifestSchema, parseBlueprintManifest, safeParseBlueprintManifest, } from './blueprint-manifest.js';
+export { GGUI_BLUEPRINT_JSON_FILENAME, blueprintManifestSchema, parseBlueprintManifest, safeParseBlueprintManifest, } from './blueprint-manifest.js';
 export type { BlueprintManifest } from './blueprint-manifest.js';
-export { artifactManifestSchema, assertArtifactManifestValid, parseArtifactManifest, safeParseArtifactManifest, } from './artifact-manifest.js';
+export { artifactManifestSchema, parseArtifactManifest, safeParseArtifactManifest, } from './artifact-manifest.js';
 export type { ArtifactManifest } from './artifact-manifest.js';
 export { GADGET_NAME_RE, BLUEPRINT_NAME_RE, ArtifactScopeSchema, ArtifactVersionSchema, } from './base.js';
 export { manifestToRegistryEntry, type ManifestToRegistryEntryFields, } from './manifest-to-registry-entry.js';
+export { POOL_ARTIFACT_CODES_DIR, POOL_ARTIFACT_CODE_REF_PATTERN, POOL_ARTIFACT_MANIFEST_FILENAME, POOL_ARTIFACT_SCHEMA_VERSION, POOL_ARTIFACT_V1_REJECTION, buildPoolArtifactManifest, parsePoolArtifactManifest, poolArtifactCodeRef, serializePoolArtifactManifest, type ParsePoolArtifactManifestResult, type PoolArtifactManifest, type PoolArtifactManifestEntry, } from './pool-artifact.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EACL,yBAAyB,EACzB,yBAAyB,EACzB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,OAAO,EACL,4BAA4B,EAC5B,4BAA4B,EAC5B,uBAAuB,EACvB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAGjE,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAS/D,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,WAAW,CAAC;AAMnB,OAAO,EACL,uBAAuB,EACvB,KAAK,6BAA6B,GACnC,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,OAAO,EACL,4BAA4B,EAC5B,uBAAuB,EACvB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAGjE,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAS/D,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,WAAW,CAAC;AAMnB,OAAO,EACL,uBAAuB,EACvB,KAAK,6BAA6B,GACnC,MAAM,iCAAiC,CAAC;AAMzC,OAAO,EACL,uBAAuB,EACvB,8BAA8B,EAC9B,+BAA+B,EAC/B,4BAA4B,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,yBAAyB,EACzB,mBAAmB,EACnB,6BAA6B,EAC7B,KAAK,+BAA+B,EACpC,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,GAC/B,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -11,14 +11,18 @@
  * kinds for tooling that handles them generically (signing, registry
  * upload, search-index ingestion).
  *
+ * Also the single owner of the seed-pool wrapper-artifact format
+ * (`pool-artifact.ts`) — the `manifest.json` + `codes/` directory
+ * layout that pool exporters write and seed-pool readers consume.
+ *
  * Browser-safe (no Node dependencies) — pure schema + parsers.
  */
 // Gadget manifest — narrow surface.
-export { GGUI_GADGET_JSON_FILENAME, assertGadgetManifestValid, parseGadgetManifest, gadgetManifestSchema, gadgetExportSchema, safeParseGadgetManifest, } from './gadget-manifest.js';
+export { GGUI_GADGET_JSON_FILENAME, parseGadgetManifest, gadgetManifestSchema, gadgetExportSchema, safeParseGadgetManifest, } from './gadget-manifest.js';
 // Blueprint manifest — narrow surface.
-export { GGUI_BLUEPRINT_JSON_FILENAME, assertBlueprintManifestValid, blueprintManifestSchema, parseBlueprintManifest, safeParseBlueprintManifest, } from './blueprint-manifest.js';
+export { GGUI_BLUEPRINT_JSON_FILENAME, blueprintManifestSchema, parseBlueprintManifest, safeParseBlueprintManifest, } from './blueprint-manifest.js';
 // Discriminated union — top-level surface.
-export { artifactManifestSchema, assertArtifactManifestValid, parseArtifactManifest, safeParseArtifactManifest, } from './artifact-manifest.js';
+export { artifactManifestSchema, parseArtifactManifest, safeParseArtifactManifest, } from './artifact-manifest.js';
 // Shared name regexes — a single kebab-case rule unified across
 // gadget and blueprint kinds. External callers (registry tooling,
 // ops tools) import these instead of re-defining the regex inline so
@@ -32,3 +36,8 @@ export { GADGET_NAME_RE, BLUEPRINT_NAME_RE, ArtifactScopeSchema, ArtifactVersion
 // through this one function. Round-trip validated in the companion
 // test file.
 export { manifestToRegistryEntry, } from './manifest-to-registry-entry.js';
+// Seed-pool wrapper-artifact codec — single owner of the artifact
+// byte format (version literal, layout names, codeRef shape,
+// rejection messages). Pool writers and seed-pool readers both
+// import from here; they own only their IO.
+export { POOL_ARTIFACT_CODES_DIR, POOL_ARTIFACT_CODE_REF_PATTERN, POOL_ARTIFACT_MANIFEST_FILENAME, POOL_ARTIFACT_SCHEMA_VERSION, POOL_ARTIFACT_V1_REJECTION, buildPoolArtifactManifest, parsePoolArtifactManifest, poolArtifactCodeRef, serializePoolArtifactManifest, } from './pool-artifact.js';

package/dist/pool-artifact.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Pool-artifact wrapper codec — the SINGLE owner of the seed-pool
+ * artifact byte format (schemaVersion 2).
+ *
+ * A seed-pool artifact is a directory-shaped bundle of exported
+ * blueprints that one deployment writes and another reads:
+ *
+ *   - `manifest.json` — `{ schemaVersion: 2, blueprints: [{ record:
+ *     <PortableBlueprint minus componentCode>, codeRef:
+ *     "<sha256hex>.tsx" }] }`, UTF-8.
+ *   - `codes/<codeRef>` — raw UTF-8 component-code body (NOT
+ *     JSON-wrapped). Readers reconstruct each record as
+ *     `{ ...entry.record, componentCode }`.
+ *
+ * This module owns everything FORMAT: the schema-version literal, the
+ * layout names (`manifest.json`, `codes/`), the codeRef filename
+ * shape, the manifest types, the (de)serializers, and the canonical
+ * rejection/issue messages. Writers and readers — whatever transport
+ * they sit on (local filesystem, object storage) — import from here
+ * and own ONLY their IO: byte fetch/store and code-body splice. A
+ * future schemaVersion bump is therefore a single-point change; a
+ * writer and a reader can never disagree on the format.
+ *
+ * Records stay UNVALIDATED here (`record: object`): artifact bytes are
+ * an untrusted input, and the trust boundary for record shape is the
+ * protocol's `fromPortableBlueprint` inside the seed-pool builder
+ * (skip-with-log on rejection — a rejected seed entry is just a
+ * cold-gen). This codec validates only the wrapper: version, layout,
+ * entry shape, codeRef shape.
+ *
+ * Versioning: the wrapper version is bumped in lockstep with the
+ * record schema (`PORTABLE_BLUEPRINT_SCHEMA_VERSION`). v1 artifacts
+ * are rejected on read with {@link POOL_ARTIFACT_V1_REJECTION} — a
+ * blueprint pool is a cache, so the fix is a re-export, never a
+ * migration shim.
+ */
+/**
+ * Wrapper-artifact schema version. Bumped 1 → 2 in lockstep with
+ * PortableBlueprint v2 (records now carry required provenance).
+ */
+export declare const POOL_ARTIFACT_SCHEMA_VERSION = 2;
+/** Manifest filename inside the artifact directory/prefix. */
+export declare const POOL_ARTIFACT_MANIFEST_FILENAME = "manifest.json";
+/** Code-body directory name inside the artifact directory/prefix. */
+export declare const POOL_ARTIFACT_CODES_DIR = "codes";
+/**
+ * The codec's code-body filename shape: `<sha256 hex>.tsx`. Readers
+ * MUST honour only refs matching this pattern so a crafted manifest
+ * value like `../../etc/passwd` can never escape `codes/`.
+ */
+export declare const POOL_ARTIFACT_CODE_REF_PATTERN: RegExp;
+/** Rejection message for schemaVersion-1 wrapper artifacts. */
+export declare const POOL_ARTIFACT_V1_REJECTION = "re-export the pool: artifact schemaVersion 2 records carry complete provenance (PortableBlueprint v2)";
+/**
+ * One manifest entry. `record` is deliberately untyped beyond "an
+ * object": the inner record is untrusted artifact bytes readers
+ * forward verbatim; `fromPortableBlueprint` at the pool builder is
+ * the validating narrower.
+ */
+export interface PoolArtifactManifestEntry {
+    readonly record: object;
+    readonly codeRef: string;
+}
+export interface PoolArtifactManifest {
+    readonly schemaVersion: typeof POOL_ARTIFACT_SCHEMA_VERSION;
+    readonly blueprints: readonly PoolArtifactManifestEntry[];
+}
+/**
+ * Build the codeRef filename for a code body's sha256 hex digest.
+ * Throws when the input is not a 64-char lowercase hex digest — a
+ * writer must never produce a ref its own reader would reject.
+ */
+export declare function poolArtifactCodeRef(sha256Hex: string): string;
+/** Stamp the current schema version onto a manifest. Writer-side. */
+export declare function buildPoolArtifactManifest(blueprints: readonly PoolArtifactManifestEntry[]): PoolArtifactManifest;
+/** Canonical manifest bytes (pretty-printed JSON + trailing newline). */
+export declare function serializePoolArtifactManifest(manifest: PoolArtifactManifest): string;
+/**
+ * Parse + validate raw manifest bytes.
+ *
+ * Failure modes (the codec's contract, shared by every reader):
+ *   - Manifest-level problems — invalid JSON, non-object root, an
+ *     unsupported `schemaVersion` (v1 included), a missing/non-array
+ *     `blueprints` — return `{ok: false, reason}`. Readers THROW,
+ *     prefixing their transport context.
+ *   - Entry-level problems — a malformed entry or a codeRef failing
+ *     {@link POOL_ARTIFACT_CODE_REF_PATTERN} — DROP the entry and
+ *     append a canonical message to `issues`. Readers surface issues
+ *     (warn/collect), never throw on them: a single bad row is a
+ *     skipped blueprint, not a dead pool.
+ */
+export type ParsePoolArtifactManifestResult = {
+    readonly ok: true;
+    readonly manifest: PoolArtifactManifest;
+    readonly issues: readonly string[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export declare function parsePoolArtifactManifest(raw: string): ParsePoolArtifactManifestResult;
+//# sourceMappingURL=pool-artifact.d.ts.map

package/dist/pool-artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool-artifact.d.ts","sourceRoot":"","sources":["../src/pool-artifact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;GAGG;AACH,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAE9C,8DAA8D;AAC9D,eAAO,MAAM,+BAA+B,kBAAkB,CAAC;AAE/D,qEAAqE;AACrE,eAAO,MAAM,uBAAuB,UAAU,CAAC;AAE/C;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,QAAwB,CAAC;AAEpE,+DAA+D;AAC/D,eAAO,MAAM,0BAA0B,0GACkE,CAAC;AAE1G;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,aAAa,EAAE,OAAO,4BAA4B,CAAC;IAC5D,QAAQ,CAAC,UAAU,EAAE,SAAS,yBAAyB,EAAE,CAAC;CAC3D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQ7D;AAED,qEAAqE;AACrE,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,SAAS,yBAAyB,EAAE,GAC/C,oBAAoB,CAEtB;AAED,yEAAyE;AACzE,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,oBAAoB,GAC7B,MAAM,CAER;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,+BAA+B,GACvC;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC,GACD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,GACV,+BAA+B,CAwDjC"}

package/dist/pool-artifact.js

@@ -0,0 +1,144 @@
+/**
+ * Pool-artifact wrapper codec — the SINGLE owner of the seed-pool
+ * artifact byte format (schemaVersion 2).
+ *
+ * A seed-pool artifact is a directory-shaped bundle of exported
+ * blueprints that one deployment writes and another reads:
+ *
+ *   - `manifest.json` — `{ schemaVersion: 2, blueprints: [{ record:
+ *     <PortableBlueprint minus componentCode>, codeRef:
+ *     "<sha256hex>.tsx" }] }`, UTF-8.
+ *   - `codes/<codeRef>` — raw UTF-8 component-code body (NOT
+ *     JSON-wrapped). Readers reconstruct each record as
+ *     `{ ...entry.record, componentCode }`.
+ *
+ * This module owns everything FORMAT: the schema-version literal, the
+ * layout names (`manifest.json`, `codes/`), the codeRef filename
+ * shape, the manifest types, the (de)serializers, and the canonical
+ * rejection/issue messages. Writers and readers — whatever transport
+ * they sit on (local filesystem, object storage) — import from here
+ * and own ONLY their IO: byte fetch/store and code-body splice. A
+ * future schemaVersion bump is therefore a single-point change; a
+ * writer and a reader can never disagree on the format.
+ *
+ * Records stay UNVALIDATED here (`record: object`): artifact bytes are
+ * an untrusted input, and the trust boundary for record shape is the
+ * protocol's `fromPortableBlueprint` inside the seed-pool builder
+ * (skip-with-log on rejection — a rejected seed entry is just a
+ * cold-gen). This codec validates only the wrapper: version, layout,
+ * entry shape, codeRef shape.
+ *
+ * Versioning: the wrapper version is bumped in lockstep with the
+ * record schema (`PORTABLE_BLUEPRINT_SCHEMA_VERSION`). v1 artifacts
+ * are rejected on read with {@link POOL_ARTIFACT_V1_REJECTION} — a
+ * blueprint pool is a cache, so the fix is a re-export, never a
+ * migration shim.
+ */
+/**
+ * Wrapper-artifact schema version. Bumped 1 → 2 in lockstep with
+ * PortableBlueprint v2 (records now carry required provenance).
+ */
+export const POOL_ARTIFACT_SCHEMA_VERSION = 2;
+/** Manifest filename inside the artifact directory/prefix. */
+export const POOL_ARTIFACT_MANIFEST_FILENAME = 'manifest.json';
+/** Code-body directory name inside the artifact directory/prefix. */
+export const POOL_ARTIFACT_CODES_DIR = 'codes';
+/**
+ * The codec's code-body filename shape: `<sha256 hex>.tsx`. Readers
+ * MUST honour only refs matching this pattern so a crafted manifest
+ * value like `../../etc/passwd` can never escape `codes/`.
+ */
+export const POOL_ARTIFACT_CODE_REF_PATTERN = /^[0-9a-f]{64}\.tsx$/;
+/** Rejection message for schemaVersion-1 wrapper artifacts. */
+export const POOL_ARTIFACT_V1_REJECTION = 're-export the pool: artifact schemaVersion 2 records carry complete provenance (PortableBlueprint v2)';
+/**
+ * Build the codeRef filename for a code body's sha256 hex digest.
+ * Throws when the input is not a 64-char lowercase hex digest — a
+ * writer must never produce a ref its own reader would reject.
+ */
+export function poolArtifactCodeRef(sha256Hex) {
+    const ref = `${sha256Hex}.tsx`;
+    if (!POOL_ARTIFACT_CODE_REF_PATTERN.test(ref)) {
+        throw new Error(`pool artifact: codeRef input is not a sha256 hex digest: ${sha256Hex}`);
+    }
+    return ref;
+}
+/** Stamp the current schema version onto a manifest. Writer-side. */
+export function buildPoolArtifactManifest(blueprints) {
+    return { schemaVersion: POOL_ARTIFACT_SCHEMA_VERSION, blueprints };
+}
+/** Canonical manifest bytes (pretty-printed JSON + trailing newline). */
+export function serializePoolArtifactManifest(manifest) {
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+export function parsePoolArtifactManifest(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            reason: `${POOL_ARTIFACT_MANIFEST_FILENAME} is not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`,
+        };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return {
+            ok: false,
+            reason: `${POOL_ARTIFACT_MANIFEST_FILENAME} is not an object`,
+        };
+    }
+    const m = parsed;
+    if (m.schemaVersion !== POOL_ARTIFACT_SCHEMA_VERSION) {
+        if (m.schemaVersion === 1) {
+            return { ok: false, reason: POOL_ARTIFACT_V1_REJECTION };
+        }
+        return {
+            ok: false,
+            reason: `unsupported manifest schemaVersion ${String(m.schemaVersion)} (expected ${POOL_ARTIFACT_SCHEMA_VERSION})`,
+        };
+    }
+    if (!Array.isArray(m.blueprints)) {
+        return {
+            ok: false,
+            reason: 'manifest.blueprints is missing or not an array',
+        };
+    }
+    const blueprints = [];
+    const issues = [];
+    for (const entry of m.blueprints) {
+        if (!isPoolArtifactManifestEntry(entry)) {
+            issues.push('malformed manifest entry (missing record/codeRef); skipping blueprint');
+            continue;
+        }
+        if (!POOL_ARTIFACT_CODE_REF_PATTERN.test(entry.codeRef)) {
+            issues.push(`invalid code reference ${entry.codeRef}; skipping blueprint`);
+            continue;
+        }
+        blueprints.push(entry);
+    }
+    return {
+        ok: true,
+        manifest: { schemaVersion: POOL_ARTIFACT_SCHEMA_VERSION, blueprints },
+        issues,
+    };
+}
+/**
+ * Structural guard for a manifest entry: `codeRef` is a string and
+ * `record` is an object readers can splice `componentCode` back into.
+ * The record's inner fields are deliberately NOT validated here — see
+ * the module docstring's trust-boundary note.
+ */
+function isPoolArtifactManifestEntry(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    if (!('codeRef' in value) || typeof value.codeRef !== 'string')
+        return false;
+    if (!('record' in value) ||
+        typeof value.record !== 'object' ||
+        value.record === null ||
+        Array.isArray(value.record)) {
+        return false;
+    }
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/artifact-manifest",
-  "version": "0.2.0-alpha.4",
+  "version": "0.3.0-rc.0",
   "description": "Strict zod schemas + parsers for ggui marketplace artifact manifests — ggui.gadget.json (gadget bundles) and ggui.blueprint.json (cached UI blueprints).",
   "license": "Apache-2.0",
   "keywords": [
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "zod": "^4.3.6",
-    "@ggui-ai/protocol": "0.2.0-alpha.4"
+    "@ggui-ai/protocol": "0.3.0-rc.0"
   },
   "devDependencies": {
     "typescript": "^5.0.0",
@@ -50,7 +50,7 @@
   },
   "author": "ggui contributors <hello@ggui.ai>",
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",