@agentxm/registry-protocol 0.31.1 → 0.33.0

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/dist/src/unstable/registry/schema.d.ts

@@ -9,6 +9,29 @@
 import * as Schema from "effect/Schema";
 import * as Option from "effect/Option";
 import { type PackageUrlParts } from "@agentxm/extension-model/unstable/packaging/package-url";
+export declare const ArchivalRevisionSchema: Schema.NonEmptyString;
+export declare const ArchivalManagementViewSchema: Schema.Struct<{
+    readonly archival: Schema.NullOr<Schema.Struct<{
+        readonly archivedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+        readonly reason: Schema.optional<Schema.String>;
+    }>>;
+    readonly revision: Schema.NonEmptyString;
+}>;
+export declare const ArchivalTransitionSchema: Schema.Struct<{
+    readonly target: Schema.String;
+    readonly before: Schema.NullOr<Schema.Struct<{
+        readonly archivedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+        readonly reason: Schema.optional<Schema.String>;
+    }>>;
+    readonly after: Schema.NullOr<Schema.Struct<{
+        readonly archivedAt: Schema.decodeTo<Schema.DateTimeUtc, Schema.String, never, never>;
+        readonly reason: Schema.optional<Schema.String>;
+    }>>;
+    readonly disposition: Schema.Literals<readonly ["created", "edited", "restored", "unchanged"]>;
+    readonly revision: Schema.NonEmptyString;
+}>;
+export type ArchivalManagementView = typeof ArchivalManagementViewSchema.Type;
+export type ArchivalTransition = typeof ArchivalTransitionSchema.Type;
 export declare const DeprecationRevisionSchema: Schema.NonEmptyString;
 export declare const DeprecationReplacementIntentSchema: Schema.Union<readonly [Schema.Struct<{
     readonly kind: Schema.Literal<"clear">;
@@ -169,6 +192,10 @@ export declare const ExtensionIndexSchema: Schema.Struct<{
         readonly url: Schema.optional<Schema.String>;
     }>>>;
     readonly visibility: Schema.optional<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;

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

@@ -15,6 +15,22 @@ import { CompanionPackageSchema } from "@agentxm/extension-model/unstable/packag
 import { PackageUrlSchema, } from "@agentxm/extension-model/unstable/packaging/package-url";
 import { VersionSchema } from "@agentxm/extension-model/unstable/version-constraints";
 import { DeprecationViewSchema } from "@agentxm/extension-model/unstable/extensions/deprecation";
+import { ArchivalViewSchema } from "@agentxm/extension-model/unstable/extensions/archival";
+export const ArchivalRevisionSchema = Schema.NonEmptyString.annotate({
+    identifier: "ArchivalRevision",
+    description: "Opaque publisher lifecycle revision used for conditional archival writes.",
+});
+export const ArchivalManagementViewSchema = Schema.Struct({
+    archival: Schema.NullOr(ArchivalViewSchema),
+    revision: ArchivalRevisionSchema,
+}).annotate({ identifier: "ArchivalManagementView" });
+export const ArchivalTransitionSchema = Schema.Struct({
+    target: ExtensionFqnSchema,
+    before: Schema.NullOr(ArchivalViewSchema),
+    after: Schema.NullOr(ArchivalViewSchema),
+    disposition: Schema.Literals(["created", "edited", "restored", "unchanged"]),
+    revision: ArchivalRevisionSchema,
+}).annotate({ identifier: "ArchivalTransition" });
 export const DeprecationRevisionSchema = Schema.NonEmptyString.annotate({
     identifier: "DeprecationRevision",
     description: "Opaque publisher lifecycle revision used for conditional writes.",
@@ -104,6 +120,7 @@ export const ExtensionIndexSchema = Schema.Struct({
     license: Schema.optional(Schema.String),
     authors: Schema.optional(Schema.Array(AuthorSchema)),
     visibility: Schema.optional(Schema.Literals(["public", "private"])),
+    archival: Schema.NullOr(ArchivalViewSchema),
     deprecation: Schema.NullOr(DeprecationViewSchema),
     versions: Schema.Array(VersionEntrySchema),
 }).annotate({

package/package.json

@@ -4,20 +4,21 @@
     "url": "https://github.com/agentxm/axm/issues"
   },
   "dependencies": {
-    "@agentxm/extension-model": "^0.31.1",
-    "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"
@@ -47,14 +54,12 @@
     "./unstable/human-handoff": {
       "types": "./dist/src/unstable/human-handoff.d.ts",
       "default": "./dist/src/unstable/human-handoff.js"
-    },
-    "./unstable/publish-authorization": {
-      "types": "./dist/src/unstable/publish-authorization.d.ts",
-      "default": "./dist/src/unstable/publish-authorization.js"
     }
   },
   "files": [
     "dist/src/",
+    "publication-set.vectors.json",
+    "resolution-metadata.vectors.json",
     "!**/*.map"
   ],
   "homepage": "https://axm.sh",
@@ -72,5 +77,5 @@
     "url": "https://github.com/agentxm/axm.git"
   },
   "type": "module",
-  "version": "0.31.1"
+  "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"
+    }
+  ]
+}