@agentxm/registry-protocol 0.31.1-preview.35463507166.59e3bf3d74da → 0.33.0

package/README.md

@@ -1,20 +1,70 @@
 # @agentxm/registry-protocol
 
-The AgentXM Registry wire contracts that the AXM client and the Registry
-implementation must interpret identically: extension index and version entry
-schemas (`./unstable/registry/schema`), discovery responses
+The AXM client's typed representation of the public AgentXM Registry HTTP
+contract: extension index and version entry schemas
+(`./unstable/registry/schema`), discovery responses
 (`./unstable/registry/discover-schema`), publication-set preview and
 validation (`./unstable/registry/publication-set`), publish visibility
 (`./unstable/publish`), and the shared suggested-action and
 human-handoff error vocabulary (`./unstable/suggested-action`,
 `./unstable/human-handoff`).
 
+## Batch resolution metadata
+
+`./unstable/registry/resolution-metadata` defines the versioned contract for a
+repeat-safe `POST /v1/resolutions/metadata` query. The Registry owns the HTTP
+route and authorization; AXM keeps version selection, release-age policy, and
+dependency graph decisions. A request groups up to 100 items in one trusted
+Registry and credential context. Each item has a unique caller key, extension
+identity, and a `select` or `restore-exact` purpose. Exact restoration supplies
+the accepted version and integrity. The caller may also supply an expected
+publisher binding, a known representation revision, or a continuation bound to
+the previous revision.
+
+The response has exactly one outcome per submitted key in request order:
+
+| Outcome            | Meaning                                                                                                                                                                                          |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `metadata`         | An authorized page of version descriptors, dependency and package compatibility data, lifecycle information, and an opaque revision. A `null` continuation means the candidate list is complete. |
+| `unchanged`        | Current authorization and lifecycle still admit a matching complete representation already held by the client. A client without that representation repeats the item without `knownRevision`.    |
+| `unavailable`      | The identity is absent or inaccessible; the response deliberately does not distinguish those cases.                                                                                              |
+| `binding-conflict` | An authorized identity no longer has the expected publisher binding.                                                                                                                             |
+| `exact-conflict`   | An authorized exact version or integrity no longer matches the accepted identity.                                                                                                                |
+| `restart-required` | A continued page crossed a representation revision; discard the earlier pages and restart.                                                                                                       |
+
+A metadata page contains at most 100 versions. Clients must follow every
+continuation and check the revision and result keys before selecting a version;
+truncated pages are never complete selection input. Continuation tokens are
+opaque and must be bound by the Registry to the request identity, credential
+context, and revision. A changed binding, hold, visibility, yank, archival or
+deprecation fact must invalidate an `unchanged` result. Backend failures are
+envelope errors, never invented per-item absence. The query is private and
+non-cacheable across commands; its POST method does not make publish mutations
+retryable.
+
+The schema exports the item, version-page, request-body, and response-body
+limits. A server checks encoded body size before decoding and returns the
+declared `request-too-large` error when exceeded. Request keys correlate results
+only; they confer no identity or access.
+
+The exported `./unstable/registry/resolution-metadata.vectors.json` records
+selection examples for ordinary and exact yanks, release age, direct and pack
+constraints, package compatibility, and publisher-binding changes. Producer and
+consumer tests can use the same cases without moving selection to the server.
+
+The byte-vendorable
+`./unstable/registry/publication-set.vectors.json` export pins digest
+conformance examples for independent implementations of the public protocol.
+Its metadata describes the canonicalization and optional-field rules; changing
+the digest algorithm requires a new contract identifier and vector format
+rather than editing the meaning of existing vectors.
+
 Content parsing, Knowledge inspection, the lint catalog, and archive and
 manifest validation live in `@agentxm/extension-content`; version selection
 and release-age policy live in `@agentxm/workspace/resolution`.
 
-Every export lives under an explicit `./unstable/*` subpath: the surface is
-unsupported and may change in any release. Ordinary users should use the
-[`axm` CLI](https://axm.sh) instead.
+This package is bundled into `axm.sh`; it is not an independently published
+API. Its `./unstable/*` subpaths are workspace-internal boundaries. Ordinary
+users should use the [`axm` CLI](https://axm.sh) instead.
 
 FSL-1.1-MIT © 2025-2026 AgentXM, Inc.

package/dist/src/unstable/registry/index.d.ts

@@ -4,6 +4,7 @@
  * @experimental This API is unstable and may change without notice.
  */
 export { type DiscoverPackageInput, DiscoverPackageInputSchema, type DiscoverPackagesRequest, DiscoverPackagesRequestSchema, type DiscoverPackagesResponse, DiscoverPackagesResponseSchema, type DiscoveryDeclaredExtension, DiscoveryDeclaredExtensionSchema, type DiscoveryExtensionResult, DiscoveryExtensionResultSchema, DiscoveryGitResolutionSchema, DiscoveryGitResolvedExtensionSchema, type DiscoveryPackageResult, DiscoveryPackageResultSchema, DiscoveryPathResolutionSchema, DiscoveryPathResolvedExtensionSchema, DiscoveryRegistryResolutionSchema, DiscoveryRegistryResolvedExtensionSchema, type DiscoveryResolvedExtension, DiscoveryResolvedExtensionSchema, } from "./discover-schema.js";
+export { MAX_RESOLUTION_METADATA_ITEMS, MAX_RESOLUTION_METADATA_REQUEST_BYTES, MAX_RESOLUTION_METADATA_RESPONSE_BYTES, MAX_RESOLUTION_METADATA_VERSIONS_PER_PAGE, RESOLUTION_METADATA_SCHEMA_VERSION, RESOLUTION_SELECTION_POLICY_VERSION, decodeResolutionMetadataRequestBody, type ResolutionMetadataError, ResolutionMetadataErrorSchema, ResolutionMetadataIdentitySchema, ResolutionMetadataItemSchema, type ResolutionMetadataOutcome, ResolutionMetadataOutcomeSchema, type ResolutionMetadataRequest, ResolutionMetadataRequestSchema, type ResolutionMetadataResponse, ResolutionMetadataResponseSchema, resolutionMetadataResponseMatchesRequest, } from "./resolution-metadata.js";
 export { MAX_PUBLICATION_SET_CANDIDATES, PUBLICATION_SET_CONTRACT, type PackDependencyDescriptor, type PackDependencyFinding, PackDependencyFindingSchema, type PreviewPublicationSetRequest, PreviewPublicationSetRequestSchema, type PreviewPublicationSetResponse, PreviewPublicationSetResponseSchema, type PublicationCandidateResult, type PublicationDescriptor, type PublicationPackResult, type PublicationTarget, type PublicationVisibilityInput, PublicationVisibilityInputSchema, type Sha256Hex, Sha256HexSchema, archiveSha256Hex, formatPackDependencyFinding, comparePublicationTargets, normalizePublicationDescriptor, normalizePublicationSet, publicationDescriptorDigest, publicationSetDigest, publicationTargetKey, validatePublicationDescriptors, validatePublicationSetResponse, } from "./publication-set.js";
 export { type ArchivalManagementView, ArchivalManagementViewSchema, ArchivalRevisionSchema, type ArchivalTransition, ArchivalTransitionSchema, type DeprecationManagementView, DeprecationManagementViewSchema, type DeprecationReplacementIntent, DeprecationReplacementIntentSchema, DeprecationRevisionSchema, type DeprecationTransition, DeprecationTransitionSchema, type ExtensionIndex, ExtensionIndexSchema, type VersionEntry, VersionEntrySchema, packagesToPackageUrlParts, } from "./schema.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/unstable/registry/index.js

@@ -4,6 +4,7 @@
  * @experimental This API is unstable and may change without notice.
  */
 export { DiscoverPackageInputSchema, DiscoverPackagesRequestSchema, DiscoverPackagesResponseSchema, DiscoveryDeclaredExtensionSchema, DiscoveryExtensionResultSchema, DiscoveryGitResolutionSchema, DiscoveryGitResolvedExtensionSchema, DiscoveryPackageResultSchema, DiscoveryPathResolutionSchema, DiscoveryPathResolvedExtensionSchema, DiscoveryRegistryResolutionSchema, DiscoveryRegistryResolvedExtensionSchema, DiscoveryResolvedExtensionSchema, } from "./discover-schema.js";
+export { MAX_RESOLUTION_METADATA_ITEMS, MAX_RESOLUTION_METADATA_REQUEST_BYTES, MAX_RESOLUTION_METADATA_RESPONSE_BYTES, MAX_RESOLUTION_METADATA_VERSIONS_PER_PAGE, RESOLUTION_METADATA_SCHEMA_VERSION, RESOLUTION_SELECTION_POLICY_VERSION, decodeResolutionMetadataRequestBody, ResolutionMetadataErrorSchema, ResolutionMetadataIdentitySchema, ResolutionMetadataItemSchema, ResolutionMetadataOutcomeSchema, ResolutionMetadataRequestSchema, ResolutionMetadataResponseSchema, resolutionMetadataResponseMatchesRequest, } from "./resolution-metadata.js";
 export { MAX_PUBLICATION_SET_CANDIDATES, PUBLICATION_SET_CONTRACT, PackDependencyFindingSchema, PreviewPublicationSetRequestSchema, PreviewPublicationSetResponseSchema, PublicationVisibilityInputSchema, Sha256HexSchema, archiveSha256Hex, formatPackDependencyFinding, comparePublicationTargets, normalizePublicationDescriptor, normalizePublicationSet, publicationDescriptorDigest, publicationSetDigest, publicationTargetKey, validatePublicationDescriptors, validatePublicationSetResponse, } from "./publication-set.js";
 export { ArchivalManagementViewSchema, ArchivalRevisionSchema, ArchivalTransitionSchema, DeprecationManagementViewSchema, DeprecationReplacementIntentSchema, DeprecationRevisionSchema, DeprecationTransitionSchema, ExtensionIndexSchema, VersionEntrySchema, packagesToPackageUrlParts, } from "./schema.js";
 //# sourceMappingURL=index.js.map

package/dist/src/unstable/registry/publication-set.d.ts

@@ -29,6 +29,36 @@ export declare const PublicationVisibilityInputSchema: Schema.Struct<{
     readonly request: Schema.NullOr<Schema.Literals<readonly ["public", "private"]>>;
 }>;
 export type PublicationVisibilityInput = typeof PublicationVisibilityInputSchema.Type;
+export declare const PublicationDescriptorSchema: Schema.Struct<{
+    readonly target: Schema.Struct<{
+        readonly owner: Schema.brand<Schema.String, "Handle">;
+        readonly type: Schema.Literals<readonly ("skill" | "mcp-server" | "subagent" | "rule" | "hook" | "knowledge" | "pack")[]>;
+        readonly name: Schema.brand<Schema.NonEmptyString, "ExtensionName">;
+        readonly version: Schema.brand<Schema.String, "Version">;
+    }>;
+    readonly participation: Schema.Literals<readonly ["publish", "verified-existing"]>;
+    readonly archiveSha256Hex: Schema.optional<Schema.String>;
+    readonly visibility: Schema.Struct<{
+        readonly intent: Schema.NullOr<Schema.Struct<{
+            readonly value: Schema.Literals<readonly ["public", "private"]>;
+            readonly source: Schema.Literals<readonly ["manifest", "workspace"]>;
+            readonly fingerprint: Schema.String;
+        }>>;
+        readonly request: Schema.NullOr<Schema.Literals<readonly ["public", "private"]>>;
+    }>;
+    readonly pack: Schema.optional<Schema.Struct<{
+        readonly dependencies: Schema.$Array<Schema.Struct<{
+            readonly owner: Schema.brand<Schema.String, "Handle">;
+            readonly type: Schema.Literals<readonly ["hook", "knowledge", "mcp-server", "rule", "skill", "subagent"]>;
+            readonly name: Schema.brand<Schema.NonEmptyString, "ExtensionName">;
+            readonly range: Schema.brand<Schema.NonEmptyString, "VersionRange">;
+            readonly source: Schema.optional<Schema.Struct<{
+                readonly type: Schema.Literal<"registry">;
+                readonly url: Schema.URLFromString;
+            }>>;
+        }>>;
+    }>>;
+}>;
 export interface PublicationDescriptor {
     readonly target: PublicationTarget;
     readonly participation: "publish" | "verified-existing";
@@ -267,10 +297,10 @@ export type PreviewPublicationSetResponse = typeof PreviewPublicationSetResponse
 export type PublicationCandidateResult = PreviewPublicationSetResponse["candidates"][number];
 export type PublicationPackResult = PreviewPublicationSetResponse["packs"][number];
 export declare const comparePublicationTargets: (left: PublicationTarget, right: PublicationTarget) => number;
-export declare const normalizePublicationDescriptor: (descriptor: PublicationDescriptor) => PublicationDescriptor;
-export declare const normalizePublicationSet: (descriptors: ReadonlyArray<PublicationDescriptor>) => ReadonlyArray<PublicationDescriptor>;
-export declare const publicationDescriptorDigest: (descriptor: PublicationDescriptor) => Sha256Hex;
-export declare const publicationSetDigest: (descriptors: ReadonlyArray<PublicationDescriptor>) => Sha256Hex;
+export declare const normalizePublicationDescriptor: (input: unknown) => PublicationDescriptor;
+export declare const normalizePublicationSet: (descriptors: ReadonlyArray<unknown>) => ReadonlyArray<PublicationDescriptor>;
+export declare const publicationDescriptorDigest: (descriptor: unknown) => Sha256Hex;
+export declare const publicationSetDigest: (descriptors: ReadonlyArray<unknown>) => Sha256Hex;
 export declare const archiveSha256Hex: (archive: Uint8Array) => Sha256Hex;
 export declare const publicationTargetKey: (target: PublicationTarget) => string;
 export declare const validatePublicationDescriptors: (descriptors: ReadonlyArray<PublicationDescriptor>) => ReadonlyArray<PublicationDescriptor>;

package/dist/src/unstable/registry/publication-set.js

@@ -30,7 +30,7 @@ export const PublicationVisibilityInputSchema = Schema.Struct({
     intent: Schema.NullOr(VisibilityIntentSchema),
     request: Schema.NullOr(ExtensionVisibilitySchema),
 }).annotate({ identifier: "PublicationVisibilityInput" });
-const PublicationDescriptorSchema = Schema.Struct({
+export const PublicationDescriptorSchema = Schema.Struct({
     target: PublicationTargetSchema,
     participation: Schema.Literals(["publish", "verified-existing"]),
     archiveSha256Hex: Schema.optional(Sha256HexSchema),
@@ -39,6 +39,10 @@ const PublicationDescriptorSchema = Schema.Struct({
         dependencies: Schema.Array(PackDependencyDescriptorSchema),
     })),
 }).annotate({ identifier: "PublicationDescriptor" });
+const PublicationDescriptorInputSchema = Schema.Union([
+    PublicationDescriptorSchema,
+    Schema.toType(PublicationDescriptorSchema),
+]);
 export const PreviewPublicationSetRequestSchema = Schema.Struct({
     contract: Schema.Literal(PUBLICATION_SET_CONTRACT),
     candidates: Schema.Array(PublicationDescriptorSchema),
@@ -208,33 +212,88 @@ const compareDependencies = (left, right) => compareText(left.owner, right.owner
     compareText(left.name, right.name) ||
     compareText(left.range, right.range) ||
     compareText(left.source?.url.href ?? "", right.source?.url.href ?? "");
-export const normalizePublicationDescriptor = (descriptor) => ({
-    target: descriptor.target,
-    participation: descriptor.participation,
-    visibility: descriptor.visibility,
-    ...(descriptor.archiveSha256Hex === undefined
-        ? {}
-        : { archiveSha256Hex: descriptor.archiveSha256Hex }),
-    ...(descriptor.pack === undefined
-        ? {}
-        : {
-            pack: {
-                dependencies: [...descriptor.pack.dependencies].sort(compareDependencies),
-            },
-        }),
-});
+export const normalizePublicationDescriptor = (input) => {
+    const descriptor = Schema.decodeUnknownSync(PublicationDescriptorInputSchema)(input);
+    return {
+        target: {
+            owner: descriptor.target.owner,
+            type: descriptor.target.type,
+            name: descriptor.target.name,
+            version: descriptor.target.version,
+        },
+        participation: descriptor.participation,
+        visibility: {
+            intent: descriptor.visibility.intent === null
+                ? null
+                : {
+                    value: descriptor.visibility.intent.value,
+                    source: descriptor.visibility.intent.source,
+                    fingerprint: descriptor.visibility.intent.fingerprint,
+                },
+            request: descriptor.visibility.request,
+        },
+        ...(descriptor.archiveSha256Hex === undefined
+            ? {}
+            : { archiveSha256Hex: descriptor.archiveSha256Hex }),
+        ...(descriptor.pack === undefined
+            ? {}
+            : {
+                pack: {
+                    dependencies: descriptor.pack.dependencies
+                        .map((dependency) => ({
+                        owner: dependency.owner,
+                        type: dependency.type,
+                        name: dependency.name,
+                        range: dependency.range,
+                        ...(dependency.source === undefined
+                            ? {}
+                            : {
+                                source: {
+                                    type: dependency.source.type,
+                                    url: dependency.source.url,
+                                },
+                            }),
+                    }))
+                        .sort(compareDependencies),
+                },
+            }),
+    };
+};
 export const normalizePublicationSet = (descriptors) => descriptors
     .map(normalizePublicationDescriptor)
     .sort((left, right) => comparePublicationTargets(left.target, right.target));
 const canonicalBytes = (value) => new TextEncoder().encode(JSON.stringify(value));
+const canonicalPublicationDescriptor = (input) => {
+    const descriptor = normalizePublicationDescriptor(input);
+    return {
+        ...descriptor,
+        ...(descriptor.pack === undefined
+            ? {}
+            : {
+                pack: {
+                    dependencies: descriptor.pack.dependencies.map((dependency) => ({
+                        ...dependency,
+                        ...(dependency.source === undefined
+                            ? {}
+                            : {
+                                source: {
+                                    type: dependency.source.type,
+                                    url: dependency.source.url.href,
+                                },
+                            }),
+                    })),
+                },
+            }),
+    };
+};
 const sha256Hex = (bytes) => Schema.decodeUnknownSync(Sha256HexSchema)(createHash("sha256").update(bytes).digest("hex"));
 export const publicationDescriptorDigest = (descriptor) => sha256Hex(canonicalBytes({
     contract: PUBLICATION_SET_CONTRACT,
-    descriptor: normalizePublicationDescriptor(descriptor),
+    descriptor: canonicalPublicationDescriptor(descriptor),
 }));
 export const publicationSetDigest = (descriptors) => sha256Hex(canonicalBytes({
     contract: PUBLICATION_SET_CONTRACT,
-    candidates: normalizePublicationSet(descriptors),
+    candidates: normalizePublicationSet(descriptors).map(canonicalPublicationDescriptor),
 }));
 export const archiveSha256Hex = (archive) => sha256Hex(archive);
 export const publicationTargetKey = (target) => JSON.stringify([target.owner, target.type, target.name, target.version]);
@@ -243,12 +302,9 @@ export const validatePublicationDescriptors = (descriptors) => {
     if (descriptors.length > MAX_PUBLICATION_SET_CANDIDATES) {
         throw new RangeError(`Publication sets accept at most ${MAX_PUBLICATION_SET_CANDIDATES} candidates.`);
     }
-    Schema.decodeUnknownSync(Schema.toType(PreviewPublicationSetRequestSchema))({
-        contract: PUBLICATION_SET_CONTRACT,
-        candidates: descriptors,
-    });
+    const normalized = normalizePublicationSet(descriptors);
     const identities = new Set();
-    for (const descriptor of descriptors) {
+    for (const descriptor of normalized) {
         const key = publicationIdentityKey(descriptor.target);
         if (identities.has(key)) {
             throw new TypeError(`Duplicate publication target ${key}.`);
@@ -261,7 +317,7 @@ export const validatePublicationDescriptors = (descriptors) => {
             throw new TypeError("Pack declarations are required exactly for pack candidates.");
         }
     }
-    return normalizePublicationSet(descriptors);
+    return normalized;
 };
 const dependencyIdentityKey = (dependency) => `${dependency.owner}\u0000${dependency.type}\u0000${dependency.name}`;
 export const validatePublicationSetResponse = (descriptors, response) => {

package/dist/src/unstable/registry/resolution-metadata.d.ts

@@ -0,0 +1,351 @@
+/**
+ * Repeat-safe Registry metadata query contract. Selection stays with the client;
+ * each response page is evidence for one authorized identity and revision.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+import * as Result from "effect/Result";
+export declare const RESOLUTION_METADATA_SCHEMA_VERSION = 1;
+export declare const RESOLUTION_SELECTION_POLICY_VERSION = "1";
+export declare const MAX_RESOLUTION_METADATA_ITEMS = 100;
+export declare const MAX_RESOLUTION_METADATA_VERSIONS_PER_PAGE = 100;
+export declare const MAX_RESOLUTION_METADATA_REQUEST_BYTES: number;
+export declare const MAX_RESOLUTION_METADATA_RESPONSE_BYTES: number;
+export declare const ResolutionMetadataIdentitySchema: Schema.Struct<{
+    readonly owner: Schema.brand<Schema.String, "Handle">;
+    readonly type: Schema.Literals<readonly ("skill" | "mcp-server" | "subagent" | "rule" | "hook" | "knowledge" | "pack")[]>;
+    readonly name: Schema.brand<Schema.NonEmptyString, "ExtensionName">;
+}>;
+export declare const ResolutionMetadataItemSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly purpose: Schema.Literal<"select">;
+    readonly key: Schema.NonEmptyString;
+    readonly identity: Schema.Struct<{
+        readonly owner: Schema.brand<Schema.String, "Handle">;
+        readonly type: Schema.Literals<readonly ("skill" | "mcp-server" | "subagent" | "rule" | "hook" | "knowledge" | "pack")[]>;
+        readonly name: Schema.brand<Schema.NonEmptyString, "ExtensionName">;
+    }>;
+    readonly expectedPublisherBinding: Schema.optional<Schema.NonEmptyString>;
+    readonly knownRevision: Schema.optional<Schema.NonEmptyString>;
+    readonly continuation: Schema.optional<Schema.Struct<{
+        readonly token: Schema.NonEmptyString;
+        readonly revision: Schema.NonEmptyString;
+    }>>;
+}>, Schema.Struct<{
+    readonly purpose: Schema.Literal<"restore-exact">;
+    readonly accepted: Schema.Struct<{
+        readonly version: Schema.brand<Schema.String, "Version">;
+        readonly integrity: Schema.NonEmptyString;
+    }>;
+    readonly key: Schema.NonEmptyString;
+    readonly identity: Schema.Struct<{
+        readonly owner: Schema.brand<Schema.String, "Handle">;
+        readonly type: Schema.Literals<readonly ("skill" | "mcp-server" | "subagent" | "rule" | "hook" | "knowledge" | "pack")[]>;
+        readonly name: Schema.brand<Schema.NonEmptyString, "ExtensionName">;
+    }>;
+    readonly expectedPublisherBinding: Schema.optional<Schema.NonEmptyString>;
+    readonly knownRevision: Schema.optional<Schema.NonEmptyString>;
+    readonly continuation: Schema.optional<Schema.Struct<{
+        readonly token: Schema.NonEmptyString;
+        readonly revision: Schema.NonEmptyString;
+    }>>;
+}>]>;
+export declare const ResolutionMetadataRequestSchema: Schema.Struct<{
+    readonly schemaVersion: Schema.Literal<1>;
+    readonly selectionPolicyVersion: Schema.Literal<"1">;
+    readonly items: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly purpose: Schema.Literal<"select">;
+        readonly key: Schema.NonEmptyString;
+        readonly identity: Schema.Struct<{
+            readonly owner: Schema.brand<Schema.String, "Handle">;
+            readonly type: Schema.Literals<readonly ("skill" | "mcp-server" | "subagent" | "rule" | "hook" | "knowledge" | "pack")[]>;
+            readonly name: Schema.brand<Schema.NonEmptyString, "ExtensionName">;
+        }>;
+        readonly expectedPublisherBinding: Schema.optional<Schema.NonEmptyString>;
+        readonly knownRevision: Schema.optional<Schema.NonEmptyString>;
+        readonly continuation: Schema.optional<Schema.Struct<{
+            readonly token: Schema.NonEmptyString;
+            readonly revision: Schema.NonEmptyString;
+        }>>;
+    }>, Schema.Struct<{
+        readonly purpose: Schema.Literal<"restore-exact">;
+        readonly accepted: Schema.Struct<{
+            readonly version: Schema.brand<Schema.String, "Version">;
+            readonly integrity: Schema.NonEmptyString;
+        }>;
+        readonly key: Schema.NonEmptyString;
+        readonly identity: Schema.Struct<{
+            readonly owner: Schema.brand<Schema.String, "Handle">;
+            readonly type: Schema.Literals<readonly ("skill" | "mcp-server" | "subagent" | "rule" | "hook" | "knowledge" | "pack")[]>;
+            readonly name: Schema.brand<Schema.NonEmptyString, "ExtensionName">;
+        }>;
+        readonly expectedPublisherBinding: Schema.optional<Schema.NonEmptyString>;
+        readonly knownRevision: Schema.optional<Schema.NonEmptyString>;
+        readonly continuation: Schema.optional<Schema.Struct<{
+            readonly token: Schema.NonEmptyString;
+            readonly revision: Schema.NonEmptyString;
+        }>>;
+    }>]>>;
+}>;
+export type ResolutionMetadataRequest = typeof ResolutionMetadataRequestSchema.Type;
+export declare const ResolutionMetadataOutcomeSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly key: Schema.NonEmptyString;
+    readonly outcome: Schema.Literal<"metadata">;
+    readonly page: Schema.Struct<{
+        readonly versions: Schema.$Array<Schema.Struct<{
+            readonly version: Schema.brand<Schema.String, "Version">;
+            readonly published: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+            readonly dependencies: Schema.optional<Schema.$Record<Schema.String, Schema.brand<Schema.NonEmptyString, "VersionRange">>>;
+            readonly packages: Schema.optional<Schema.$Array<Schema.Struct<{
+                readonly purl: Schema.brand<Schema.NonEmptyString, "PackageIdentityPurl">;
+                readonly versionRange: Schema.optional<Schema.brand<Schema.decodeTo<Schema.toType<Schema.Struct<{
+                    readonly raw: Schema.NonEmptyString;
+                    readonly scheme: Schema.NonEmptyString;
+                    readonly constraints: Schema.$Array<Schema.Struct<{
+                        readonly comparator: Schema.Literals<readonly ["=", "!=", "<", "<=", ">", ">="]>;
+                        readonly version: Schema.NonEmptyString;
+                    }>>;
+                }>>, Schema.NonEmptyString, never, never>, "VersRange">>;
+            }>>>;
+            readonly integrity: Schema.String;
+            readonly yankedAt: Schema.optional<Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>>;
+            readonly yankCategory: Schema.optional<Schema.String>;
+            readonly yankNotice: Schema.optional<Schema.String>;
+        }>>;
+        readonly continuation: Schema.NullOr<Schema.NonEmptyString>;
+        readonly description: Schema.optional<Schema.String>;
+        readonly repository: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Struct<{
+            readonly type: Schema.optional<Schema.NonEmptyString>;
+            readonly url: Schema.NonEmptyString;
+            readonly directory: Schema.optional<Schema.NonEmptyString>;
+        }>]>>;
+        readonly bugs: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Struct<{
+            readonly url: Schema.optional<Schema.NonEmptyString>;
+            readonly email: Schema.optional<Schema.NonEmptyString>;
+        }>]>>;
+        readonly license: Schema.optional<Schema.String>;
+        readonly authors: Schema.optional<Schema.$Array<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly email: Schema.optional<Schema.String>;
+            readonly url: Schema.optional<Schema.String>;
+        }>>>;
+        readonly publisherBindingId: Schema.NonEmptyString;
+        readonly visibility: Schema.Literals<readonly ["public", "private"]>;
+        readonly archival: Schema.NullOr<Schema.Struct<{
+            readonly archivedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+            readonly reason: Schema.optional<Schema.String>;
+        }>>;
+        readonly deprecation: Schema.NullOr<Schema.Union<readonly [Schema.Struct<{
+            readonly deprecatedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+            readonly message: Schema.String;
+            readonly replacement: Schema.optional<Schema.Union<readonly [Schema.Struct<{
+                readonly status: Schema.Literal<"available">;
+                readonly fqn: Schema.String;
+            }>, Schema.Struct<{
+                readonly status: Schema.Literal<"unavailable">;
+                readonly fqn: Schema.optional<Schema.String>;
+            }>]>>;
+        }>, Schema.Struct<{
+            readonly deprecatedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+            readonly message: Schema.optional<Schema.String>;
+            readonly replacement: Schema.Union<readonly [Schema.Struct<{
+                readonly status: Schema.Literal<"available">;
+                readonly fqn: Schema.String;
+            }>, Schema.Struct<{
+                readonly status: Schema.Literal<"unavailable">;
+                readonly fqn: Schema.optional<Schema.String>;
+            }>]>;
+        }>]>>;
+        readonly revision: Schema.NonEmptyString;
+        readonly observedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+        readonly validUntil: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+    }>;
+}>, Schema.Struct<{
+    readonly exactVersion: Schema.optional<Schema.brand<Schema.String, "Version">>;
+    readonly publisherBindingId: Schema.NonEmptyString;
+    readonly visibility: Schema.Literals<readonly ["public", "private"]>;
+    readonly archival: Schema.NullOr<Schema.Struct<{
+        readonly archivedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+        readonly reason: Schema.optional<Schema.String>;
+    }>>;
+    readonly deprecation: Schema.NullOr<Schema.Union<readonly [Schema.Struct<{
+        readonly deprecatedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+        readonly message: Schema.String;
+        readonly replacement: Schema.optional<Schema.Union<readonly [Schema.Struct<{
+            readonly status: Schema.Literal<"available">;
+            readonly fqn: Schema.String;
+        }>, Schema.Struct<{
+            readonly status: Schema.Literal<"unavailable">;
+            readonly fqn: Schema.optional<Schema.String>;
+        }>]>>;
+    }>, Schema.Struct<{
+        readonly deprecatedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+        readonly message: Schema.optional<Schema.String>;
+        readonly replacement: Schema.Union<readonly [Schema.Struct<{
+            readonly status: Schema.Literal<"available">;
+            readonly fqn: Schema.String;
+        }>, Schema.Struct<{
+            readonly status: Schema.Literal<"unavailable">;
+            readonly fqn: Schema.optional<Schema.String>;
+        }>]>;
+    }>]>>;
+    readonly revision: Schema.NonEmptyString;
+    readonly observedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+    readonly validUntil: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+    readonly key: Schema.NonEmptyString;
+    readonly outcome: Schema.Literal<"unchanged">;
+}>, Schema.Struct<{
+    readonly key: Schema.NonEmptyString;
+    readonly outcome: Schema.Literal<"unavailable">;
+}>, Schema.Struct<{
+    readonly key: Schema.NonEmptyString;
+    readonly outcome: Schema.Literal<"binding-conflict">;
+    readonly publisherBindingId: Schema.NonEmptyString;
+}>, Schema.Struct<{
+    readonly key: Schema.NonEmptyString;
+    readonly outcome: Schema.Literal<"exact-conflict">;
+    readonly reason: Schema.Literals<readonly ["version-unavailable", "integrity-mismatch"]>;
+}>, Schema.Struct<{
+    readonly key: Schema.NonEmptyString;
+    readonly outcome: Schema.Literal<"restart-required">;
+    readonly revision: Schema.NonEmptyString;
+}>]>;
+export type ResolutionMetadataOutcome = typeof ResolutionMetadataOutcomeSchema.Type;
+export declare const ResolutionMetadataResponseSchema: Schema.Struct<{
+    readonly schemaVersion: Schema.Literal<1>;
+    readonly selectionPolicyVersion: Schema.Literal<"1">;
+    readonly observedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+    readonly results: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly key: Schema.NonEmptyString;
+        readonly outcome: Schema.Literal<"metadata">;
+        readonly page: Schema.Struct<{
+            readonly versions: Schema.$Array<Schema.Struct<{
+                readonly version: Schema.brand<Schema.String, "Version">;
+                readonly published: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+                readonly dependencies: Schema.optional<Schema.$Record<Schema.String, Schema.brand<Schema.NonEmptyString, "VersionRange">>>;
+                readonly packages: Schema.optional<Schema.$Array<Schema.Struct<{
+                    readonly purl: Schema.brand<Schema.NonEmptyString, "PackageIdentityPurl">;
+                    readonly versionRange: Schema.optional<Schema.brand<Schema.decodeTo<Schema.toType<Schema.Struct<{
+                        readonly raw: Schema.NonEmptyString;
+                        readonly scheme: Schema.NonEmptyString;
+                        readonly constraints: Schema.$Array<Schema.Struct<{
+                            readonly comparator: Schema.Literals<readonly ["=", "!=", "<", "<=", ">", ">="]>;
+                            readonly version: Schema.NonEmptyString;
+                        }>>;
+                    }>>, Schema.NonEmptyString, never, never>, "VersRange">>;
+                }>>>;
+                readonly integrity: Schema.String;
+                readonly yankedAt: Schema.optional<Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>>;
+                readonly yankCategory: Schema.optional<Schema.String>;
+                readonly yankNotice: Schema.optional<Schema.String>;
+            }>>;
+            readonly continuation: Schema.NullOr<Schema.NonEmptyString>;
+            readonly description: Schema.optional<Schema.String>;
+            readonly repository: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Struct<{
+                readonly type: Schema.optional<Schema.NonEmptyString>;
+                readonly url: Schema.NonEmptyString;
+                readonly directory: Schema.optional<Schema.NonEmptyString>;
+            }>]>>;
+            readonly bugs: Schema.optional<Schema.Union<readonly [Schema.String, Schema.Struct<{
+                readonly url: Schema.optional<Schema.NonEmptyString>;
+                readonly email: Schema.optional<Schema.NonEmptyString>;
+            }>]>>;
+            readonly license: Schema.optional<Schema.String>;
+            readonly authors: Schema.optional<Schema.$Array<Schema.Struct<{
+                readonly name: Schema.String;
+                readonly email: Schema.optional<Schema.String>;
+                readonly url: Schema.optional<Schema.String>;
+            }>>>;
+            readonly publisherBindingId: Schema.NonEmptyString;
+            readonly visibility: Schema.Literals<readonly ["public", "private"]>;
+            readonly archival: Schema.NullOr<Schema.Struct<{
+                readonly archivedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+                readonly reason: Schema.optional<Schema.String>;
+            }>>;
+            readonly deprecation: Schema.NullOr<Schema.Union<readonly [Schema.Struct<{
+                readonly deprecatedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+                readonly message: Schema.String;
+                readonly replacement: Schema.optional<Schema.Union<readonly [Schema.Struct<{
+                    readonly status: Schema.Literal<"available">;
+                    readonly fqn: Schema.String;
+                }>, Schema.Struct<{
+                    readonly status: Schema.Literal<"unavailable">;
+                    readonly fqn: Schema.optional<Schema.String>;
+                }>]>>;
+            }>, Schema.Struct<{
+                readonly deprecatedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+                readonly message: Schema.optional<Schema.String>;
+                readonly replacement: Schema.Union<readonly [Schema.Struct<{
+                    readonly status: Schema.Literal<"available">;
+                    readonly fqn: Schema.String;
+                }>, Schema.Struct<{
+                    readonly status: Schema.Literal<"unavailable">;
+                    readonly fqn: Schema.optional<Schema.String>;
+                }>]>;
+            }>]>>;
+            readonly revision: Schema.NonEmptyString;
+            readonly observedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+            readonly validUntil: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+        }>;
+    }>, Schema.Struct<{
+        readonly exactVersion: Schema.optional<Schema.brand<Schema.String, "Version">>;
+        readonly publisherBindingId: Schema.NonEmptyString;
+        readonly visibility: Schema.Literals<readonly ["public", "private"]>;
+        readonly archival: Schema.NullOr<Schema.Struct<{
+            readonly archivedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+            readonly reason: Schema.optional<Schema.String>;
+        }>>;
+        readonly deprecation: Schema.NullOr<Schema.Union<readonly [Schema.Struct<{
+            readonly deprecatedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+            readonly message: Schema.String;
+            readonly replacement: Schema.optional<Schema.Union<readonly [Schema.Struct<{
+                readonly status: Schema.Literal<"available">;
+                readonly fqn: Schema.String;
+            }>, Schema.Struct<{
+                readonly status: Schema.Literal<"unavailable">;
+                readonly fqn: Schema.optional<Schema.String>;
+            }>]>>;
+        }>, Schema.Struct<{
+            readonly deprecatedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+            readonly message: Schema.optional<Schema.String>;
+            readonly replacement: Schema.Union<readonly [Schema.Struct<{
+                readonly status: Schema.Literal<"available">;
+                readonly fqn: Schema.String;
+            }>, Schema.Struct<{
+                readonly status: Schema.Literal<"unavailable">;
+                readonly fqn: Schema.optional<Schema.String>;
+            }>]>;
+        }>]>>;
+        readonly revision: Schema.NonEmptyString;
+        readonly observedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+        readonly validUntil: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+        readonly key: Schema.NonEmptyString;
+        readonly outcome: Schema.Literal<"unchanged">;
+    }>, Schema.Struct<{
+        readonly key: Schema.NonEmptyString;
+        readonly outcome: Schema.Literal<"unavailable">;
+    }>, Schema.Struct<{
+        readonly key: Schema.NonEmptyString;
+        readonly outcome: Schema.Literal<"binding-conflict">;
+        readonly publisherBindingId: Schema.NonEmptyString;
+    }>, Schema.Struct<{
+        readonly key: Schema.NonEmptyString;
+        readonly outcome: Schema.Literal<"exact-conflict">;
+        readonly reason: Schema.Literals<readonly ["version-unavailable", "integrity-mismatch"]>;
+    }>, Schema.Struct<{
+        readonly key: Schema.NonEmptyString;
+        readonly outcome: Schema.Literal<"restart-required">;
+        readonly revision: Schema.NonEmptyString;
+    }>]>>;
+}>;
+export type ResolutionMetadataResponse = typeof ResolutionMetadataResponseSchema.Type;
+/** Validate the response against the submitted keys before consuming any page. */
+export declare const resolutionMetadataResponseMatchesRequest: (request: ResolutionMetadataRequest, response: ResolutionMetadataResponse) => boolean;
+export declare const ResolutionMetadataErrorSchema: Schema.Struct<{
+    readonly code: Schema.Literals<readonly ["invalid-request", "unsupported-schema-version", "unsupported-selection-policy-version", "request-too-large", "response-too-large", "backend-unavailable"]>;
+    readonly detail: Schema.String;
+}>;
+export type ResolutionMetadataError = typeof ResolutionMetadataErrorSchema.Type;
+/** Apply the encoded body limit before parsing an untrusted request. */
+export declare const decodeResolutionMetadataRequestBody: (body: Uint8Array) => Result.Result<ResolutionMetadataRequest, ResolutionMetadataError>;
+//# sourceMappingURL=resolution-metadata.d.ts.map

package/dist/src/unstable/registry/resolution-metadata.js

@@ -0,0 +1,198 @@
+/**
+ * Repeat-safe Registry metadata query contract. Selection stays with the client;
+ * each response page is evidence for one authorized identity and revision.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Schema from "effect/Schema";
+import * as Result from "effect/Result";
+import { DateTimeUtcSchema } from "@agentxm/extension-model/unstable/date-time";
+import { AuthorSchema, BugsSchema, ExtensionNameSchema, ExtensionTypeSchema, RepositorySchema, } from "@agentxm/extension-model/unstable/extensions/common";
+import { HandleSchema } from "@agentxm/extension-model/unstable/extensions/handle";
+import { VersionSchema } from "@agentxm/extension-model/unstable/version-constraints";
+import { ArchivalViewSchema } from "@agentxm/extension-model/unstable/extensions/archival";
+import { DeprecationViewSchema } from "@agentxm/extension-model/unstable/extensions/deprecation";
+import { VersionEntrySchema } from "./schema.js";
+export const RESOLUTION_METADATA_SCHEMA_VERSION = 1;
+export const RESOLUTION_SELECTION_POLICY_VERSION = "1";
+export const MAX_RESOLUTION_METADATA_ITEMS = 100;
+export const MAX_RESOLUTION_METADATA_VERSIONS_PER_PAGE = 100;
+export const MAX_RESOLUTION_METADATA_REQUEST_BYTES = 256 * 1024;
+export const MAX_RESOLUTION_METADATA_RESPONSE_BYTES = 1024 * 1024;
+export const ResolutionMetadataIdentitySchema = Schema.Struct({
+    owner: HandleSchema,
+    type: ExtensionTypeSchema,
+    name: ExtensionNameSchema,
+}).annotate({ identifier: "ResolutionMetadataIdentity" });
+const CallerKeySchema = Schema.NonEmptyString.check(Schema.isMaxLength(128)).annotate({
+    identifier: "ResolutionMetadataCallerKey",
+    description: "Opaque caller correlation key. It grants no identity or authority.",
+});
+const RevisionSchema = Schema.NonEmptyString.check(Schema.isMaxLength(256)).annotate({
+    identifier: "ResolutionMetadataRevision",
+});
+const ContinuationSchema = Schema.NonEmptyString.check(Schema.isMaxLength(2048)).annotate({
+    identifier: "ResolutionMetadataContinuation",
+    description: "Opaque token bound by the server to the request context and revision.",
+});
+const RequestEvidenceSchema = {
+    key: CallerKeySchema,
+    identity: ResolutionMetadataIdentitySchema,
+    expectedPublisherBinding: Schema.optional(Schema.NonEmptyString),
+    knownRevision: Schema.optional(RevisionSchema),
+    continuation: Schema.optional(Schema.Struct({ token: ContinuationSchema, revision: RevisionSchema })),
+};
+const SelectItemSchema = Schema.Struct({
+    ...RequestEvidenceSchema,
+    purpose: Schema.Literal("select"),
+});
+const RestoreExactItemSchema = Schema.Struct({
+    ...RequestEvidenceSchema,
+    purpose: Schema.Literal("restore-exact"),
+    accepted: Schema.Struct({
+        version: VersionSchema,
+        integrity: Schema.NonEmptyString,
+    }),
+});
+export const ResolutionMetadataItemSchema = Schema.Union([
+    SelectItemSchema,
+    RestoreExactItemSchema,
+]).check(Schema.makeFilter((item) => item.knownRevision === undefined || item.continuation === undefined
+    ? true
+    : "A continuation cannot also send a conditional revision"));
+export const ResolutionMetadataRequestSchema = Schema.Struct({
+    schemaVersion: Schema.Literal(RESOLUTION_METADATA_SCHEMA_VERSION),
+    selectionPolicyVersion: Schema.Literal(RESOLUTION_SELECTION_POLICY_VERSION),
+    items: Schema.Array(ResolutionMetadataItemSchema).check(Schema.isMinLength(1), Schema.isMaxLength(MAX_RESOLUTION_METADATA_ITEMS), Schema.makeFilter((items) => new Set(items.map((item) => item.key)).size === items.length
+        ? true
+        : "Caller keys must be unique within a batch")),
+}).annotate({ identifier: "ResolutionMetadataRequest" });
+const CurrentEvidenceFieldsSchema = {
+    publisherBindingId: Schema.NonEmptyString,
+    visibility: Schema.Literals(["public", "private"]),
+    archival: Schema.NullOr(ArchivalViewSchema),
+    deprecation: Schema.NullOr(DeprecationViewSchema),
+    revision: RevisionSchema,
+    observedAt: DateTimeUtcSchema,
+    validUntil: DateTimeUtcSchema,
+};
+const MetadataFieldsSchema = {
+    ...CurrentEvidenceFieldsSchema,
+    description: Schema.optional(Schema.String),
+    repository: Schema.optional(RepositorySchema),
+    bugs: Schema.optional(BugsSchema),
+    license: Schema.optional(Schema.String),
+    authors: Schema.optional(Schema.Array(AuthorSchema)),
+};
+const MetadataPageSchema = Schema.Struct({
+    ...MetadataFieldsSchema,
+    versions: Schema.Array(VersionEntrySchema).check(Schema.isMinLength(1), Schema.isMaxLength(MAX_RESOLUTION_METADATA_VERSIONS_PER_PAGE)),
+    continuation: Schema.NullOr(ContinuationSchema),
+}).annotate({ identifier: "ResolutionMetadataPage" });
+const MetadataOutcomeSchema = Schema.Struct({
+    key: CallerKeySchema,
+    outcome: Schema.Literal("metadata"),
+    page: MetadataPageSchema,
+});
+const UnchangedOutcomeSchema = Schema.Struct({
+    key: CallerKeySchema,
+    outcome: Schema.Literal("unchanged"),
+    ...CurrentEvidenceFieldsSchema,
+    exactVersion: Schema.optional(VersionSchema),
+});
+const UnavailableOutcomeSchema = Schema.Struct({
+    key: CallerKeySchema,
+    outcome: Schema.Literal("unavailable"),
+});
+const BindingConflictOutcomeSchema = Schema.Struct({
+    key: CallerKeySchema,
+    outcome: Schema.Literal("binding-conflict"),
+    publisherBindingId: Schema.NonEmptyString,
+});
+const ExactConflictOutcomeSchema = Schema.Struct({
+    key: CallerKeySchema,
+    outcome: Schema.Literal("exact-conflict"),
+    reason: Schema.Literals(["version-unavailable", "integrity-mismatch"]),
+});
+const RestartRequiredOutcomeSchema = Schema.Struct({
+    key: CallerKeySchema,
+    outcome: Schema.Literal("restart-required"),
+    revision: RevisionSchema,
+});
+export const ResolutionMetadataOutcomeSchema = Schema.Union([
+    MetadataOutcomeSchema,
+    UnchangedOutcomeSchema,
+    UnavailableOutcomeSchema,
+    BindingConflictOutcomeSchema,
+    ExactConflictOutcomeSchema,
+    RestartRequiredOutcomeSchema,
+]);
+export const ResolutionMetadataResponseSchema = Schema.Struct({
+    schemaVersion: Schema.Literal(RESOLUTION_METADATA_SCHEMA_VERSION),
+    selectionPolicyVersion: Schema.Literal(RESOLUTION_SELECTION_POLICY_VERSION),
+    observedAt: DateTimeUtcSchema,
+    results: Schema.Array(ResolutionMetadataOutcomeSchema).check(Schema.isMaxLength(MAX_RESOLUTION_METADATA_ITEMS)),
+}).annotate({ identifier: "ResolutionMetadataResponse" });
+/** Validate the response against the submitted keys before consuming any page. */
+export const resolutionMetadataResponseMatchesRequest = (request, response) => response.results.length === request.items.length &&
+    response.results.every((result, index) => {
+        const item = request.items[index];
+        if (item === undefined || result.key !== item.key)
+            return false;
+        if (item.continuation === undefined)
+            return result.outcome !== "restart-required";
+        return (result.outcome !== "unchanged" &&
+            (result.outcome !== "metadata" || result.page.revision === item.continuation.revision));
+    });
+export const ResolutionMetadataErrorSchema = Schema.Struct({
+    code: Schema.Literals([
+        "invalid-request",
+        "unsupported-schema-version",
+        "unsupported-selection-policy-version",
+        "request-too-large",
+        "response-too-large",
+        "backend-unavailable",
+    ]),
+    detail: Schema.String,
+});
+const decodeRequest = Schema.decodeUnknownResult(ResolutionMetadataRequestSchema);
+const strictUtf8 = new TextDecoder("utf-8", { fatal: true });
+/** Apply the encoded body limit before parsing an untrusted request. */
+export const decodeResolutionMetadataRequestBody = (body) => {
+    if (body.byteLength > MAX_RESOLUTION_METADATA_REQUEST_BYTES) {
+        return Result.fail({
+            code: "request-too-large",
+            detail: "Resolution metadata request exceeds the encoded body limit.",
+        });
+    }
+    let input;
+    try {
+        input = JSON.parse(strictUtf8.decode(body));
+    }
+    catch {
+        return Result.fail({
+            code: "invalid-request",
+            detail: "Resolution metadata request is not valid UTF-8 JSON.",
+        });
+    }
+    if (typeof input === "object" && input !== null) {
+        if ("schemaVersion" in input && input.schemaVersion !== RESOLUTION_METADATA_SCHEMA_VERSION) {
+            return Result.fail({
+                code: "unsupported-schema-version",
+                detail: "Resolution metadata schema version is unsupported.",
+            });
+        }
+        if ("selectionPolicyVersion" in input &&
+            input.selectionPolicyVersion !== RESOLUTION_SELECTION_POLICY_VERSION) {
+            return Result.fail({
+                code: "unsupported-selection-policy-version",
+                detail: "Resolution selection policy version is unsupported.",
+            });
+        }
+    }
+    const decoded = decodeRequest(input, { onExcessProperty: "error" });
+    return Result.isFailure(decoded)
+        ? Result.fail({ code: "invalid-request", detail: "Resolution metadata request is invalid." })
+        : Result.succeed(decoded.success);
+};
+//# sourceMappingURL=resolution-metadata.js.map

package/package.json

@@ -4,20 +4,21 @@
     "url": "https://github.com/agentxm/axm/issues"
   },
   "dependencies": {
-    "@agentxm/extension-model": "0.31.1-preview.35463507166.59e3bf3d74da",
-    "effect": "4.0.0-rc.115",
+    "@agentxm/extension-model": "^0.33.0",
+    "effect": "4.0.0-rc.117",
     "semver": "^7.8.5"
   },
   "description": "AgentXM Registry wire contracts: index, discovery, publication-set, visibility, authorization, and suggested-action schemas. Unstable and unsupported — use the axm.sh CLI.",
   "devDependencies": {
-    "@effect/vitest": "4.0.0-rc.115",
+    "@agentxm/specification-metadata": "0.33.0",
+    "@effect/vitest": "4.0.0-rc.117",
     "@types/semver": "^7.7.1",
     "@typescript/native": "npm:typescript@^7.0.2",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
     "vitest": "^5.0.0"
   },
   "engines": {
-    "node": ">=22.19.0"
+    "node": ">=24.19.0"
   },
   "exports": {
     "./unstable/publish": {
@@ -36,6 +37,12 @@
       "types": "./dist/src/unstable/registry/publication-set.d.ts",
       "default": "./dist/src/unstable/registry/publication-set.js"
     },
+    "./unstable/registry/resolution-metadata": {
+      "types": "./dist/src/unstable/registry/resolution-metadata.d.ts",
+      "default": "./dist/src/unstable/registry/resolution-metadata.js"
+    },
+    "./unstable/registry/publication-set.vectors.json": "./publication-set.vectors.json",
+    "./unstable/registry/resolution-metadata.vectors.json": "./resolution-metadata.vectors.json",
     "./unstable/registry/schema": {
       "types": "./dist/src/unstable/registry/schema.d.ts",
       "default": "./dist/src/unstable/registry/schema.js"
@@ -51,6 +58,8 @@
   },
   "files": [
     "dist/src/",
+    "publication-set.vectors.json",
+    "resolution-metadata.vectors.json",
     "!**/*.map"
   ],
   "homepage": "https://axm.sh",
@@ -68,5 +77,5 @@
     "url": "https://github.com/agentxm/axm.git"
   },
   "type": "module",
-  "version": "0.31.1-preview.35463507166.59e3bf3d74da"
+  "version": "0.33.0"
 }

package/publication-set.vectors.json

@@ -0,0 +1,212 @@
+{
+  "format": "agentxm-publication-set-digest-vectors-v1",
+  "contract": "publication-set-v2",
+  "canonicalization": {
+    "encoding": "Hash the UTF-8 bytes of JSON.stringify over the canonical object described by publication-set-v2.",
+    "objectKeys": "Reconstruct descriptor, target, visibility, intent, pack, dependency, and source objects in the contract's declared key order before hashing.",
+    "candidateOrder": "Sort candidates by owner, type, name, then version using ascending code-unit order.",
+    "dependencyOrder": "Sort pack dependencies by owner, type, name, range, then source URL using ascending code-unit order.",
+    "optionalFields": "Omit archiveSha256Hex and pack when absent. null is invalid for either optional field and must be rejected before hashing.",
+    "evolution": "A future digest algorithm must mint a new publication-set contract identifier and vector format; do not change these vectors in place."
+  },
+  "vectors": [
+    {
+      "name": "optional-fields-omitted",
+      "candidates": [
+        {
+          "descriptor": {
+            "target": {
+              "owner": "@acme",
+              "type": "skill",
+              "name": "existing",
+              "version": "1.0.0"
+            },
+            "participation": "verified-existing",
+            "visibility": {
+              "intent": null,
+              "request": null
+            }
+          },
+          "descriptorDigest": "b7aeb666fa2e467bbbf6e28e9b5299e3d3b5f3f9dce5f7a9dc7222df4aa6316a"
+        }
+      ],
+      "publicationSetDigest": "ef0e42506c66afc3d522df6179b3c6c4c12240f3a57c57f9d64ad2bffb19cef5"
+    },
+    {
+      "name": "visibility-input",
+      "candidates": [
+        {
+          "descriptor": {
+            "target": {
+              "owner": "@acme",
+              "type": "rule",
+              "name": "guard",
+              "version": "2.1.0"
+            },
+            "participation": "publish",
+            "visibility": {
+              "intent": {
+                "value": "private",
+                "source": "workspace",
+                "fingerprint": "2222222222222222222222222222222222222222222222222222222222222222"
+              },
+              "request": "public"
+            },
+            "archiveSha256Hex": "1111111111111111111111111111111111111111111111111111111111111111"
+          },
+          "descriptorDigest": "d6934f76c10be57d7ab7099e880ef28a5dfbecfe4eb706b1199e141901176a2b"
+        }
+      ],
+      "publicationSetDigest": "ad643e51e182bc14772ea42c8b6d3805a27d0657aac98ed45274bfa107581106"
+    },
+    {
+      "name": "pack-dependencies-and-candidate-order",
+      "candidates": [
+        {
+          "descriptor": {
+            "target": {
+              "owner": "@zeta",
+              "type": "pack",
+              "name": "team",
+              "version": "3.0.0"
+            },
+            "participation": "publish",
+            "visibility": {
+              "intent": null,
+              "request": null
+            },
+            "archiveSha256Hex": "3333333333333333333333333333333333333333333333333333333333333333",
+            "pack": {
+              "dependencies": [
+                {
+                  "owner": "@zeta",
+                  "type": "skill",
+                  "name": "last",
+                  "range": "^2.0.0"
+                },
+                {
+                  "owner": "@acme",
+                  "type": "rule",
+                  "name": "guard",
+                  "range": "^2.1.0"
+                }
+              ]
+            }
+          },
+          "descriptorDigest": "34ebd67ef59afc296b921716ca98bbdd48548466896ca636bd16499e333d7273"
+        },
+        {
+          "descriptor": {
+            "target": {
+              "owner": "@acme",
+              "type": "skill",
+              "name": "review",
+              "version": "1.2.0"
+            },
+            "participation": "publish",
+            "visibility": {
+              "intent": null,
+              "request": "public"
+            },
+            "archiveSha256Hex": "4444444444444444444444444444444444444444444444444444444444444444"
+          },
+          "descriptorDigest": "a480ea68a556dc3e00e8b037c43a97a2ea385a45ab0fad28262d555f1393133b"
+        }
+      ],
+      "publicationSetDigest": "2fd0aa0d5e79a03feceb16307aa87e79d0f8056e87a59678ec9675b638f6016e"
+    },
+    {
+      "name": "explicit-registry-pack-member-source",
+      "candidates": [
+        {
+          "descriptor": {
+            "target": {
+              "owner": "@acme",
+              "type": "pack",
+              "name": "sourced",
+              "version": "1.0.0"
+            },
+            "participation": "publish",
+            "visibility": {
+              "intent": null,
+              "request": null
+            },
+            "archiveSha256Hex": "5555555555555555555555555555555555555555555555555555555555555555",
+            "pack": {
+              "dependencies": [
+                {
+                  "owner": "@agentxm",
+                  "type": "skill",
+                  "name": "axm",
+                  "range": "^0.30.0",
+                  "source": {
+                    "type": "registry",
+                    "url": "https://registry.agentxm.ai/"
+                  }
+                }
+              ]
+            }
+          },
+          "descriptorDigest": "900b5e53eaa7dfb07e67d84d068c31219994ee5c26851a6953f438dbcdd0199d"
+        }
+      ],
+      "publicationSetDigest": "5ca9029cd0220ff349925a7872a6e7a9422fc2f0ab185f7c5d87fecd2e707828"
+    },
+    {
+      "name": "original-publication-set-v2-pins",
+      "candidates": [
+        {
+          "descriptor": {
+            "target": {
+              "owner": "@acme",
+              "type": "pack",
+              "name": "team",
+              "version": "2.0.0"
+            },
+            "participation": "publish",
+            "visibility": {
+              "intent": null,
+              "request": null
+            },
+            "archiveSha256Hex": "4862f447f2c7f272fa2f4aaf89dadb3b1ac09105bd5864f8d1a0c9452bb0a226",
+            "pack": {
+              "dependencies": [
+                {
+                  "owner": "@zeta",
+                  "type": "skill",
+                  "name": "last",
+                  "range": "^1.0.0"
+                },
+                {
+                  "owner": "@acme",
+                  "type": "skill",
+                  "name": "review",
+                  "range": "^1.2.0"
+                }
+              ]
+            }
+          },
+          "descriptorDigest": "f7ee37ff8488e6b4ef99514496ad85f40153fb6defee0e511f9d5342cb60f50d"
+        },
+        {
+          "descriptor": {
+            "target": {
+              "owner": "@acme",
+              "type": "skill",
+              "name": "review",
+              "version": "1.2.0"
+            },
+            "participation": "publish",
+            "visibility": {
+              "intent": null,
+              "request": "public"
+            },
+            "archiveSha256Hex": "9c53c074d7ac6a2728b638ac1f376c5fa9eb8f71603017c3ea638c2fd40548df"
+          },
+          "descriptorDigest": "7700a3c2b2ff0caffd0d3da12a4c5c13b338b0adb557979ce9cbceb899670c5b"
+        }
+      ],
+      "publicationSetDigest": "a7d28ff4005c1596cd373060c13279a58469573e49685fe17b8d767b4c210c6c"
+    }
+  ]
+}

package/resolution-metadata.vectors.json

@@ -0,0 +1,177 @@
+{
+  "format": "agentxm-resolution-metadata-vectors-v1",
+  "selectionPolicyVersion": "1",
+  "evaluatedAt": "2026-09-22T12:00:00Z",
+  "cases": [
+    {
+      "name": "ordinary-range-excludes-yanked-release",
+      "source": "direct",
+      "index": {
+        "owner": "@acme",
+        "type": "skill",
+        "name": "review",
+        "publisherBindingId": "hbnd_acme",
+        "archival": null,
+        "deprecation": null,
+        "versions": [
+          {
+            "version": "1.1.0",
+            "published": "2026-09-18T12:00:00Z",
+            "integrity": "sha512-yanked",
+            "yankedAt": "2026-09-19T12:00:00Z"
+          },
+          { "version": "1.0.0", "published": "2026-09-15T12:00:00Z", "integrity": "sha512-stable" }
+        ]
+      },
+      "request": { "purpose": "select", "range": "^1.0.0", "minimumReleaseAgeSeconds": 0 },
+      "expected": { "kind": "selected", "version": "1.0.0" }
+    },
+    {
+      "name": "exact-pin-retains-yank-warning",
+      "source": "direct",
+      "index": {
+        "owner": "@acme",
+        "type": "skill",
+        "name": "review",
+        "publisherBindingId": "hbnd_acme",
+        "archival": null,
+        "deprecation": null,
+        "versions": [
+          {
+            "version": "1.1.0",
+            "published": "2026-09-18T12:00:00Z",
+            "integrity": "sha512-yanked",
+            "yankedAt": "2026-09-19T12:00:00Z",
+            "yankedCategory": "superseded"
+          },
+          { "version": "1.0.0", "published": "2026-09-15T12:00:00Z", "integrity": "sha512-stable" }
+        ]
+      },
+      "request": {
+        "purpose": "restore-exact",
+        "range": "1.1.0",
+        "acceptedIntegrity": "sha512-yanked",
+        "minimumReleaseAgeSeconds": 0
+      },
+      "expected": { "kind": "selected", "version": "1.1.0", "warning": "yanked" }
+    },
+    {
+      "name": "minimum-release-age-holds-newer-release",
+      "source": "direct",
+      "index": {
+        "owner": "@acme",
+        "type": "skill",
+        "name": "review",
+        "publisherBindingId": "hbnd_acme",
+        "archival": null,
+        "deprecation": null,
+        "versions": [
+          { "version": "2.0.0", "published": "2026-09-22T00:00:00Z", "integrity": "sha512-new" },
+          { "version": "1.0.0", "published": "2026-09-15T12:00:00Z", "integrity": "sha512-stable" }
+        ]
+      },
+      "request": { "purpose": "select", "range": "*", "minimumReleaseAgeSeconds": 86400 },
+      "expected": { "kind": "selected", "version": "1.0.0", "newerHeld": "2.0.0" }
+    },
+    {
+      "name": "direct-constraint-selects-highest-satisfying-release",
+      "source": "direct",
+      "index": {
+        "owner": "@acme",
+        "type": "skill",
+        "name": "review",
+        "publisherBindingId": "hbnd_acme",
+        "archival": null,
+        "deprecation": null,
+        "versions": [
+          { "version": "2.0.0", "published": "2026-09-15T12:00:00Z", "integrity": "sha512-two" },
+          { "version": "1.2.0", "published": "2026-09-14T12:00:00Z", "integrity": "sha512-one-two" }
+        ]
+      },
+      "request": { "purpose": "select", "range": "^1.0.0", "minimumReleaseAgeSeconds": 0 },
+      "expected": { "kind": "selected", "version": "1.2.0" }
+    },
+    {
+      "name": "pack-member-constraint-keeps-member-range",
+      "source": "pack-member",
+      "index": {
+        "owner": "@acme",
+        "type": "skill",
+        "name": "review",
+        "publisherBindingId": "hbnd_acme",
+        "archival": null,
+        "deprecation": null,
+        "versions": [
+          {
+            "version": "1.1.0",
+            "published": "2026-09-15T12:00:00Z",
+            "integrity": "sha512-one-one"
+          },
+          {
+            "version": "1.0.5",
+            "published": "2026-09-14T12:00:00Z",
+            "integrity": "sha512-one-zero-five"
+          }
+        ]
+      },
+      "request": { "purpose": "select", "range": "~1.0.0", "minimumReleaseAgeSeconds": 0 },
+      "expected": { "kind": "selected", "version": "1.0.5" }
+    },
+    {
+      "name": "package-compatibility-remains-version-scoped",
+      "source": "direct",
+      "index": {
+        "owner": "@acme",
+        "type": "skill",
+        "name": "review",
+        "publisherBindingId": "hbnd_acme",
+        "archival": null,
+        "deprecation": null,
+        "versions": [
+          {
+            "version": "1.1.0",
+            "published": "2026-09-15T12:00:00Z",
+            "integrity": "sha512-one-one",
+            "packages": [{ "purl": "pkg:npm/%40acme/core", "versionRange": "vers:npm/>=2.0.0" }]
+          },
+          {
+            "version": "1.0.0",
+            "published": "2026-09-14T12:00:00Z",
+            "integrity": "sha512-one-zero",
+            "packages": [{ "purl": "pkg:npm/%40acme/core", "versionRange": "vers:npm/<2.0.0" }]
+          }
+        ]
+      },
+      "request": {
+        "purpose": "select",
+        "range": "^1.0.0",
+        "minimumReleaseAgeSeconds": 0,
+        "compatiblePackage": { "purl": "pkg:npm/%40acme/core", "version": "2.1.0" }
+      },
+      "expected": { "kind": "selected", "version": "1.1.0" }
+    },
+    {
+      "name": "publisher-binding-change-refuses-accepted-identity",
+      "source": "direct",
+      "index": {
+        "owner": "@acme",
+        "type": "skill",
+        "name": "review",
+        "publisherBindingId": "hbnd_current",
+        "archival": null,
+        "deprecation": null,
+        "versions": [
+          { "version": "1.0.0", "published": "2026-09-15T12:00:00Z", "integrity": "sha512-stable" }
+        ]
+      },
+      "request": {
+        "purpose": "restore-exact",
+        "range": "1.0.0",
+        "acceptedIntegrity": "sha512-stable",
+        "expectedPublisherBinding": "hbnd_previous",
+        "minimumReleaseAgeSeconds": 0
+      },
+      "expected": { "kind": "binding-conflict" }
+    }
+  ]
+}