@ggui-ai/registry-core 0.1.0-rc.1

package/dist/interfaces/bundle-storage.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `BundleStorage` — bundle + signature + manifest blob storage. The
+ * hosted registry backs this with S3 behind a CDN; the open-source
+ * server backs it with the filesystem under
+ * `<root>/bundles/<scope>/<name>/<version>/`. A memory impl is
+ * provided for tests.
+ *
+ * Each `put*` method returns the fully-qualified URL the consumer
+ * (iframe runtime, install CLI) can fetch. The URL prefix is
+ * determined by the impl's constructor — a CDN alias for the hosted
+ * registry, or `http://localhost:9001` (or whatever the server is
+ * bound to) for the open-source server.
+ *
+ * Bundles are immutable post-publish. Responses MUST emit
+ * `Cache-Control: public, max-age=31536000, immutable` — SRI integrity
+ * depends on it. The OSS server's bundle route sets this header
+ * explicitly; the cloud's CloudFront distribution sets it via its
+ * cache policy.
+ *
+ * ## Protocol & Contract Bar
+ *
+ * **Parties:**
+ * - Producer: {@link publishArtifact} writes bundle (gadgets),
+ *   signature (gadgets), and manifest (always) on every publish.
+ * - Consumer: iframe-runtime (bundleUrl), install CLI (signatureUrl,
+ *   manifestUrl), audit tooling (manifestUrl on yanked versions).
+ *
+ * **Obligations:**
+ * - `put*` methods MUST be idempotent — re-publishes of the same
+ *   `(scope, name, version)` triple write identical bytes (the
+ *   per-version row immutability invariant on {@link RegistryStorage}
+ *   prevents true re-publishes; the bundle-storage layer needs no
+ *   conflict semantics).
+ * - URL composition methods (`bundleUrl`, `signatureUrl`,
+ *   `manifestUrl`) MUST be pure — no I/O, no async. Consumers cache
+ *   URLs liberally.
+ *
+ * **Failure mode:**
+ * - Transport-level failures throw; the publish op wraps and returns
+ *   500.
+ * - Missing-blob reads return `null`; never throw.
+ *
+ * **Observable violation:**
+ * - Contract test {@link bundleStorageContract} covers: bundle
+ *   round-trip preserves bytes; signature round-trip preserves the
+ *   structured object; manifest round-trip preserves the full
+ *   discriminated-union shape; URL methods compose without side effects;
+ *   missing reads return null.
+ */
+import type { ArtifactManifest } from '@ggui-ai/artifact-manifest';
+import type { GadgetSignature } from '@ggui-ai/gadget-signing';
+export interface BundleStorage {
+    /** Write gadget bundle bytes. Returns the public URL. */
+    putBundle(scope: string, name: string, version: string, bytes: Uint8Array): Promise<string>;
+    /** Read gadget bundle bytes. `null` on miss. */
+    getBundle(scope: string, name: string, version: string): Promise<Uint8Array | null>;
+    /**
+     * Write the signature envelope. Returns the public URL.
+     *
+     * The envelope is a {@link GadgetSignature} — a discriminated union
+     * over `algorithm` (`ed25519` for private gadgets, `sigstore-cosign`
+     * for public). Impls serialize via `JSON.stringify(signature)` and
+     * store the resulting bytes verbatim.
+     */
+    putSignature(scope: string, name: string, version: string, signature: GadgetSignature): Promise<string>;
+    /** Read the signature envelope. `null` on miss. */
+    getSignature(scope: string, name: string, version: string): Promise<GadgetSignature | null>;
+    /** Write the manifest verbatim. Returns the public URL. */
+    putManifest(scope: string, name: string, version: string, manifest: ArtifactManifest): Promise<string>;
+    /** Read the manifest. `null` on miss. */
+    getManifest(scope: string, name: string, version: string): Promise<ArtifactManifest | null>;
+    /** Compose the public bundle URL. No I/O. */
+    bundleUrl(scope: string, name: string, version: string): string;
+    /** Compose the public signature URL. No I/O. */
+    signatureUrl(scope: string, name: string, version: string): string;
+    /** Compose the public manifest URL. No I/O. */
+    manifestUrl(scope: string, name: string, version: string): string;
+}
+//# sourceMappingURL=bundle-storage.d.ts.map

package/dist/interfaces/bundle-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-storage.d.ts","sourceRoot":"","sources":["../../src/interfaces/bundle-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5F,gDAAgD;IAChD,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAEpF;;;;;;;OAOG;IACH,YAAY,CACV,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,eAAe,GACzB,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,mDAAmD;IACnD,YAAY,CACV,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IAEnC,2DAA2D;IAC3D,WAAW,CACT,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,yCAAyC;IACzC,WAAW,CACT,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAEpC,6CAA6C;IAC7C,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAChE,gDAAgD;IAChD,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IACnE,+CAA+C;IAC/C,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;CACnE"}

package/dist/interfaces/bundle-storage.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/registry-storage.d.ts

@@ -0,0 +1,204 @@
+/**
+ * `RegistryStorage` — the per-row persistence seam for the marketplace
+ * registry. The interface mirrors a three-table DynamoDB shape
+ * (artifacts + artifact-versions + author-keys) so a hosted DynamoDB
+ * adapter can be a structural pass-through. Memory + filesystem impls
+ * back the open-source server and unit tests.
+ *
+ * The shape follows a single-interface / multiple-impls / contract-test
+ * pattern, with a Protocol & Contract Bar docstring.
+ *
+ * The umbrella noun is `artifact`: the registry stores BOTH gadgets
+ * AND blueprints, and `kind` discriminates.
+ *
+ * ## Protocol & Contract Bar
+ *
+ * **Parties:**
+ * - Producer / writer: {@link publishArtifact} — writes
+ *   {@link ArtifactsMetadataRow} on every publish (upserting
+ *   `latestVersion`) and writes {@link ArtifactVersionRow} once per
+ *   version via {@link putArtifactVersionIfAbsent}.
+ * - Reader: {@link readArtifact}, {@link searchArtifacts},
+ *   {@link publishArtifact} (signature verification path).
+ *
+ * **Obligations:**
+ * - {@link putArtifactVersionIfAbsent} MUST atomically reject when a row
+ *   exists for `(artifactId, version)`. Mirrors DDB's
+ *   `ConditionExpression: attribute_not_exists(...)`. Implementations
+ *   MUST NOT overwrite on conflict — per-version immutability is a
+ *   load-bearing registry invariant.
+ * - {@link getArtifactMetadata} / {@link getArtifactVersion} MUST return
+ *   exactly what was last written. `null` on miss; throw on transport
+ *   failure (caller decides retry).
+ * - {@link scanArtifacts} returns rows in arbitrary order (cloud DDB
+ *   Scan order; memory insertion order; filesystem directory order).
+ *   Consumers MUST treat ordering as non-deterministic.
+ *
+ * **Failure mode:**
+ * - Transport-level failures (DDB throttle, disk full) throw.
+ *   {@link publishArtifact} wraps and returns 500 with `internal`
+ *   error code.
+ * - Missing rows return `null`; never throw.
+ *
+ * **Observable violation:**
+ * - Contract test {@link registryStorageContract} covers:
+ *   round-trip preservation, idempotent {@link putArtifactMetadata},
+ *   `putArtifactVersionIfAbsent` rejects on collision, missing returns
+ *   null, `listAuthorKeys` returns only keys for the queried subject.
+ */
+import type { ArtifactScanFilter, ArtifactVersionRow, ArtifactsMetadataRow, AuthorKeyRow, CompiledBlobRow } from '../types.js';
+/**
+ * Optional flags for {@link RegistryStorage.putAuthorKey}.
+ *
+ * `ifNotExists` — when `true`, the write MUST be conditional on no
+ * existing row for `(subject, keyId)`. On conflict (a concurrent first
+ * write landed between the caller's check and this put), implementations
+ * MUST throw {@link AuthorKeyAlreadyExistsError}. Used by
+ * {@link registerAuthorKey} to close the TOCTOU window between its
+ * idempotency read and the put.
+ */
+export interface PutAuthorKeyOptions {
+    readonly ifNotExists?: boolean;
+}
+/**
+ * Thrown by {@link RegistryStorage.putAuthorKey} when the caller passed
+ * `ifNotExists: true` AND a row already exists for `(subject, keyId)`.
+ * Cloud DDB adapter surfaces `ConditionalCheckFailedException` as this
+ * type; in-memory impl mirrors the contract synchronously.
+ *
+ * Callers re-read via {@link RegistryStorage.getAuthorKey} and dispatch
+ * same-publicKey → 200, different-publicKey → 409.
+ */
+export declare class AuthorKeyAlreadyExistsError extends Error {
+    readonly subject: string;
+    readonly keyId: string;
+    constructor(subject: string, keyId: string);
+}
+export interface RegistryStorage {
+    getArtifactMetadata(artifactId: string): Promise<ArtifactsMetadataRow | null>;
+    putArtifactMetadata(row: ArtifactsMetadataRow): Promise<void>;
+    /**
+     * Scan the metadata-row family with paginated cursor + post-fetch
+     * filter. The filter is applied per-row; impls MAY push it down
+     * (cloud GSI when available) or run it in-memory after a wide scan.
+     * `limit` is treated as a per-page ceiling; consumers may iterate
+     * via `nextCursor` for multi-page reads.
+     */
+    scanArtifacts(filter: ArtifactScanFilter): Promise<{
+        readonly rows: readonly ArtifactsMetadataRow[];
+        readonly nextCursor?: string;
+    }>;
+    getArtifactVersion(artifactId: string, version: string): Promise<ArtifactVersionRow | null>;
+    /**
+     * List every version row for `artifactId`. Returns in arbitrary order
+     * (DDB Query order by SK = version, lexicographic; memory map
+     * insertion order; filesystem directory order). Callers MUST sort
+     * by semver themselves if they need ordering.
+     *
+     * Backs the `GET /pkg/:scope/:name` list-versions route.
+     *
+     * **Cost note.** A DynamoDB impl uses `Query` with `PK = artifactId`,
+     * which is the cheapest possible per-artifact lookup (no Scan, no
+     * GSI). Memory + filesystem impls do a full table walk filtered by
+     * artifactId — adequate for bounded row counts.
+     *
+     * **Returns:** empty array when no versions exist (NOT null) — the
+     * "metadata-row present but no version rows" state should never
+     * happen post-publish but is technically representable; the empty
+     * array keeps the type narrow.
+     */
+    listArtifactVersions(artifactId: string): Promise<readonly ArtifactVersionRow[]>;
+    /**
+     * Atomically conditional put — succeeds only when no row exists for
+     * `(artifactId, version)`. The single load-bearing concurrency primitive
+     * in the registry; consumers MUST NOT pre-check with
+     * {@link getArtifactVersion} + put (race-prone).
+     */
+    putArtifactVersionIfAbsent(row: ArtifactVersionRow): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: 'version_exists';
+    }>;
+    yankArtifactVersion(artifactId: string, version: string): Promise<void>;
+    /**
+     * Fetch the compiled-bytes row for `compiledDigest`. Returns `null` on miss.
+     *
+     * Used by:
+     *   - Read op — projecting `compiledBytes` into
+     *     {@link ReadPkgResponse} alongside the version row.
+     *   - Install path — two-layer resolution of
+     *     `ArtifactVersionRow.compiledDigest` → `CompiledBlobRow`.
+     *     A missing blob when the version row's pointer is set is a
+     *     CRITICAL inconsistency the caller surfaces, not silently
+     *     fallback.
+     *   - Tests / fixtures that pre-seed blob rows without a paired
+     *     publish.
+     */
+    getCompiledBlob(compiledDigest: string): Promise<CompiledBlobRow | null>;
+    /**
+     * Atomically commit BOTH the version row AND the compiled-blob row
+     * under a single logical transaction. A single transaction avoids
+     * the "dangling pointer" failure mode where a blob write fails
+     * after the version row is already durable.
+     *
+     * **Two paths**, dispatched by the storage impl:
+     *
+     *   - **New-blob path** — `blobRow.compiledDigest` is not yet present.
+     *     Both rows are PUT-INSERTed under one transaction with
+     *     `attribute_not_exists` conditions on each. Returns
+     *     `{ ok: true, mode: 'new-blob' }`.
+     *   - **Dedup path** — `blobRow.compiledDigest` already has a row.
+     *     The version row is PUT-INSERTed AND the existing blob row's
+     *     `refCount` is incremented under one transaction. Returns
+     *     `{ ok: true, mode: 'dedup' }`.
+     *
+     * **Failure mode:**
+     *
+     *   - Version-row conflict — `(artifactId, version)` already exists.
+     *     NEITHER row mutates. Returns `{ ok: false, reason: 'version_exists' }`.
+     *     The publisher's idempotent-retry path.
+     *   - Transport-level failures (DDB throttle, disk full, transaction
+     *     conflict not attributable to either conditional) throw —
+     *     {@link publishArtifact} wraps and returns 500.
+     *
+     * **Atomicity guarantee:**
+     *
+     *   - Memory + filesystem impls: single-threaded JS event loop —
+     *     the function awaits both writes before returning, no other
+     *     awaitable interleaves.
+     *   - Cloud DDB impl: `TransactWriteItems` is all-or-nothing at the
+     *     service level. The new-blob path issues one transaction; the
+     *     dedup path may retry once if the optimistic new-blob path
+     *     fails because the digest landed between read-and-write.
+     *
+     * **Why a single transaction matters (refCount double-increment on
+     * retry)**: a sequenced write path could increment refCount, then
+     * crash before persisting the version row, then on retry increment
+     * again. With TransactWriteItems both mutations either land together
+     * or not at all — refCount can only grow when a version row also
+     * lands.
+     *
+     * **Invariant preserved:** once a version row is durable, the
+     * `(artifactId, version)` tuple cannot be re-used — semver
+     * immutability holds.
+     */
+    commitVersionAndBlob(versionRow: ArtifactVersionRow, blobRow: CompiledBlobRow): Promise<{
+        ok: true;
+        mode: 'new-blob' | 'dedup';
+    } | {
+        ok: false;
+        reason: 'version_exists';
+    }>;
+    getAuthorKey(subject: string, keyId: string): Promise<AuthorKeyRow | null>;
+    /**
+     * Write an AuthorKey row. With `options.ifNotExists === true`, the
+     * write is conditional on no existing row for `(subject, keyId)`;
+     * on conflict, implementations MUST throw
+     * {@link AuthorKeyAlreadyExistsError}. Default (no options) is an
+     * unconditional upsert.
+     */
+    putAuthorKey(row: AuthorKeyRow, options?: PutAuthorKeyOptions): Promise<void>;
+    listAuthorKeys(subject: string): Promise<readonly AuthorKeyRow[]>;
+}
+//# sourceMappingURL=registry-storage.d.ts.map

package/dist/interfaces/registry-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-storage.d.ts","sourceRoot":"","sources":["../../src/interfaces/registry-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,YAAY,EACZ,eAAe,EAChB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBACX,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAQ3C;AAED,MAAM,WAAW,eAAe;IAE9B,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;IAC9E,mBAAmB,CAAC,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D;;;;;;OAMG;IACH,aAAa,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC;QACjD,QAAQ,CAAC,IAAI,EAAE,SAAS,oBAAoB,EAAE,CAAC;QAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC,CAAC;IAGH,kBAAkB,CAChB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IACtC;;;;;;;;;;;;;;;;;OAiBG;IACH,oBAAoB,CAClB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,SAAS,kBAAkB,EAAE,CAAC,CAAC;IAC1C;;;;;OAKG;IACH,0BAA0B,CACxB,GAAG,EAAE,kBAAkB,GACtB,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,gBAAgB,CAAA;KAAE,CAAC,CAAC;IACnE,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAGxE;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8CG;IACH,oBAAoB,CAClB,UAAU,EAAE,kBAAkB,EAC9B,OAAO,EAAE,eAAe,GACvB,OAAO,CACN;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAA;KAAE,GACxC;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,gBAAgB,CAAA;KAAE,CAC1C,CAAC;IAGF,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC3E;;;;;;OAMG;IACH,YAAY,CACV,GAAG,EAAE,YAAY,EACjB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CAAC;CACnE"}

package/dist/interfaces/registry-storage.js

@@ -0,0 +1,19 @@
+/**
+ * Thrown by {@link RegistryStorage.putAuthorKey} when the caller passed
+ * `ifNotExists: true` AND a row already exists for `(subject, keyId)`.
+ * Cloud DDB adapter surfaces `ConditionalCheckFailedException` as this
+ * type; in-memory impl mirrors the contract synchronously.
+ *
+ * Callers re-read via {@link RegistryStorage.getAuthorKey} and dispatch
+ * same-publicKey → 200, different-publicKey → 409.
+ */
+export class AuthorKeyAlreadyExistsError extends Error {
+    subject;
+    keyId;
+    constructor(subject, keyId) {
+        super(`AuthorKey row already exists for (subject=${subject}, keyId=${keyId})`);
+        this.name = 'AuthorKeyAlreadyExistsError';
+        this.subject = subject;
+        this.keyId = keyId;
+    }
+}

package/dist/ops/compile.d.ts

@@ -0,0 +1,48 @@
+/** Compile output — base64-encoded bytes, hex digest, decoded size. */
+export interface CompileBlueprintOk {
+    readonly ok: true;
+    readonly compiledBytes: string;
+    readonly compiledDigest: string;
+    readonly compiledSize: number;
+}
+/** Compile failure — structured esbuild diagnostics for wire surfacing. */
+export interface CompileBlueprintErr {
+    readonly ok: false;
+    readonly errors: ReadonlyArray<{
+        readonly message: string;
+        readonly location?: {
+            readonly line?: number;
+            readonly column?: number;
+        };
+    }>;
+}
+export type CompileBlueprintResult = CompileBlueprintOk | CompileBlueprintErr;
+/**
+ * Always-allowed imports on the SOURCE side. Mirrors the conformance
+ * gate's `BLUEPRINT_ALLOWED_IMPORTS` to keep the wire-contract aligned;
+ * any addition here MUST land in the conformance gate at the same
+ * commit (and vice versa).
+ */
+export declare const BLUEPRINT_EXTERNAL_MODULES: readonly string[];
+/**
+ * Hex SHA-256 of `compiledBytes` (base64-decoded). Pure function; the
+ * deterministic-compile contract is `compile(source) → sha256(bytes)`.
+ *
+ * Exported for callers that want to recompute the digest without
+ * re-compiling (e.g. install-time defense-in-depth).
+ */
+export declare function compiledDigestHex(compiledBytes: string): string;
+/**
+ * Compile a blueprint's TSX `source` into canonical compiled JS bytes.
+ *
+ * Sync at call site — esbuild's `transformSync` is used to keep the
+ * publish op's transaction boundaries clean (one async hop into
+ * compile, one async hop into storage). The transform is itself fast
+ * (<10ms for typical blueprints).
+ *
+ * @returns Discriminated-union result. Caller projects errors onto
+ *          the conformance-failure wire envelope; success is a
+ *          base64 string + hex digest + decoded byte count.
+ */
+export declare function compileBlueprint(source: string): CompileBlueprintResult;
+//# sourceMappingURL=compile.d.ts.map

package/dist/ops/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../src/ops/compile.ts"],"names":[],"mappings":"AAsDA,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;QAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE;YAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KAC1E,CAAC,CAAC;CACJ;AAED,MAAM,MAAM,sBAAsB,GAAG,kBAAkB,GAAG,mBAAmB,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAKtD,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,sBAAsB,CA6CvE"}

package/dist/ops/compile.js

@@ -0,0 +1,163 @@
+/**
+ * `compileBlueprint` — the TSX → JS compile boundary.
+ *
+ * Pure transform from a blueprint's `manifest.source` (TSX text) to
+ * compiled JS bytes + content digest. Called by the publish op before
+ * writing the {@link CompiledBlobRow} + {@link ArtifactVersionRow}.
+ * NO I/O — esbuild's synchronous transform API is used so this op
+ * stays at the seam where reads and writes are sequenced by the
+ * caller's transaction.
+ *
+ * **Determinism.** The compile config below is a fixed settings
+ * matrix. Changing any field is a `compiledDigest` mass-invalidation
+ * — every previously-published version produces a different digest.
+ * Any change to this matrix requires a migration plan, because the
+ * matcher's cross-app cache sharing and federation keys depend on
+ * stable digests across all federating registries.
+ *
+ *   format: 'esm'              — required (the iframe runtime + matcher
+ *                                 consume ES modules; no CJS path).
+ *   target: 'es2022'           — pinned to the lowest engine the
+ *                                 protocol supports; rebumping is a
+ *                                 minor protocol version bump.
+ *   bundle: true               — single-file output; the matcher writes
+ *                                 the bytes directly into componentCode.
+ *   minify: false              — readability matters more than size at
+ *                                 this scale (~10s of KB per blueprint).
+ *   external: ['react',        — host-provided modules at iframe-render
+ *              'react-dom',      time. The conformance gate enforces
+ *              'react/jsx-runtime', the same allow-list on the SOURCE
+ *              '@ggui-ai/gadgets']  side so we never compile a blueprint
+ *                                   whose imports don't survive bundling.
+ *   loader.tsx: 'tsx'          — input is JSX/TSX text.
+ *   treeShaking: false         — preserve all imports so the conformance
+ *                                gate's import-walk matches what's in
+ *                                the compiled output.
+ *
+ * **esbuild version pin.** `packages/registry-core/package.json` pins
+ * `esbuild` to a single minor — the digest is sensitive to esbuild's
+ * own version bumps. Bumping esbuild is a coordinated re-publish
+ * exercise; the policy lives in the migration doc.
+ *
+ * **Failure mode.** Compile errors surface as a typed result
+ * `{ ok: false }` with structured `errors` from esbuild. The publish
+ * op projects them onto the conformance-failure wire envelope
+ * (`blueprint_compile_error`). The static-gates conformance op
+ * already runs a more permissive `esbuild.transformSync` to surface
+ * the same code at conformance-check time; this compile op is the
+ * load-bearing one (its OUTPUT is what's stored), but the two are
+ * deliberately separate so a `POST /conformance/check` dry-run
+ * remains cheap (no bundle resolution).
+ */
+import * as esbuild from 'esbuild';
+import { createHash } from 'node:crypto';
+/**
+ * Always-allowed imports on the SOURCE side. Mirrors the conformance
+ * gate's `BLUEPRINT_ALLOWED_IMPORTS` to keep the wire-contract aligned;
+ * any addition here MUST land in the conformance gate at the same
+ * commit (and vice versa).
+ */
+export const BLUEPRINT_EXTERNAL_MODULES = Object.freeze([
+    'react',
+    'react-dom',
+    'react/jsx-runtime',
+    '@ggui-ai/gadgets',
+]);
+/**
+ * Hex SHA-256 of `compiledBytes` (base64-decoded). Pure function; the
+ * deterministic-compile contract is `compile(source) → sha256(bytes)`.
+ *
+ * Exported for callers that want to recompute the digest without
+ * re-compiling (e.g. install-time defense-in-depth).
+ */
+export function compiledDigestHex(compiledBytes) {
+    return createHash('sha256').update(Buffer.from(compiledBytes, 'base64')).digest('hex');
+}
+/**
+ * Compile a blueprint's TSX `source` into canonical compiled JS bytes.
+ *
+ * Sync at call site — esbuild's `transformSync` is used to keep the
+ * publish op's transaction boundaries clean (one async hop into
+ * compile, one async hop into storage). The transform is itself fast
+ * (<10ms for typical blueprints).
+ *
+ * @returns Discriminated-union result. Caller projects errors onto
+ *          the conformance-failure wire envelope; success is a
+ *          base64 string + hex digest + decoded byte count.
+ */
+export function compileBlueprint(source) {
+    try {
+        // esbuild.buildSync would require a virtual-fs layer to handle
+        // imports; we use transformSync which compiles a single text input
+        // and emits a single text output. Tree-shaking is OFF and externals
+        // are not stripped (preserved as ESM import statements). This
+        // matches what the runtime + matcher consume.
+        const result = esbuild.transformSync(source, {
+            loader: 'tsx',
+            format: 'esm',
+            target: 'es2022',
+            minify: false,
+            treeShaking: false,
+            // `keepNames` keeps function/class names for stack traces — the
+            // matcher's source-map-less debug surface depends on these.
+            keepNames: true,
+            // `sourcemap` off — sourcemaps would inject non-deterministic
+            // path strings into the output, breaking digest stability.
+            sourcemap: false,
+        });
+        // Note on `BLUEPRINT_EXTERNAL_MODULES`: with `transformSync` (not
+        // `buildSync`) imports are preserved verbatim in the output —
+        // tree-shaking off + no bundle resolution means the import
+        // statements pass through unmodified. The externals list is the
+        // CONTRACT consumers (iframe runtime, matcher) honor at module-
+        // load time. The conformance gate's import-walk enforces the
+        // allow-list on the source side before publish.
+        const bytes = Buffer.from(result.code, 'utf-8');
+        const compiledBytes = bytes.toString('base64');
+        const compiledDigest = createHash('sha256').update(bytes).digest('hex');
+        return {
+            ok: true,
+            compiledBytes,
+            compiledDigest,
+            compiledSize: bytes.byteLength,
+        };
+    }
+    catch (err) {
+        // esbuild's BuildFailure shape exposes `errors: Message[]` with
+        // text + location. Other throw shapes (TypeError, OOM) surface
+        // as a single generic error.
+        const errors = extractEsbuildErrors(err);
+        return { ok: false, errors };
+    }
+}
+function extractEsbuildErrors(err) {
+    if (err === null || typeof err !== 'object') {
+        return [{ message: err instanceof Error ? err.message : String(err) }];
+    }
+    const maybeErrors = err.errors;
+    if (!Array.isArray(maybeErrors) || maybeErrors.length === 0) {
+        const message = err instanceof Error ? err.message : String(err);
+        return [{ message }];
+    }
+    const out = [];
+    for (const m of maybeErrors) {
+        if (m === null || typeof m !== 'object')
+            continue;
+        const msg = m;
+        const message = typeof msg.text === 'string' && msg.text.length > 0 ? msg.text : 'esbuild error';
+        if (msg.location !== null &&
+            msg.location !== undefined &&
+            (typeof msg.location.line === 'number' || typeof msg.location.column === 'number')) {
+            const location = {};
+            if (typeof msg.location.line === 'number')
+                location.line = msg.location.line;
+            if (typeof msg.location.column === 'number')
+                location.column = msg.location.column;
+            out.push({ message, location });
+        }
+        else {
+            out.push({ message });
+        }
+    }
+    return out;
+}