@agentxm/extension-resolution 0.28.14-preview.1789139351.5cd4595aa

package/dist/src/update/targeted-update-context.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Ownership, authority, and blocker classification for a targeted update.
+ *
+ * A person naming one extension asks a question the workspace has to answer
+ * before any Registry is contacted: does this workspace desire the extension
+ * at all, who owns the declaration that would move (a direct entry, an owning
+ * Pack, or both), is the entry active, which version constraint actually
+ * governs it once every declared constraint is intersected, and is there a
+ * reason the advance may not be made — an authored or bundled source, an
+ * incomplete Pack graph, a constraint with no compatible intersection, or a
+ * Pack-owned member the request would fork into direct intent.
+ *
+ * The classification is pure over the desired-state graph plus the configured
+ * Pack rows; `resolveTargetedUpdateContext` reads those and adds the accepted
+ * Pack evidence the fingerprint covers. The fingerprint is the freshness
+ * witness a targeted update rechecks under the workspace transition, so a
+ * context that changed between planning and apply stops the operation instead
+ * of applying a decision the workspace no longer supports.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import type { InstallableExtensionType } from "@agentxm/extension-model/unstable/extensions/installable-types";
+import type { ConfiguredRecordRow, DesiredStateGraph, WorkspaceLockfileReadFailure, WorkspaceSettingsReadFailure, WorkspaceStateReadFailure } from "@agentxm/workspace-state";
+import { WorkspaceMutations } from "@agentxm/workspace-state";
+export type TargetedUpdateBlocker = "not-desired" | "disabled" | "pack-owned-constraint" | "incomplete-graph" | "constraint-conflict" | "bundled-source" | "source-authority" | "stale-plan";
+/** Every type a targeted update may name; a Pack is classified as a closure, not a member. */
+export type TargetedUpdateTargetType = Exclude<InstallableExtensionType, "pack">;
+export type TargetedUpdateAuthority = "direct" | "pack-aware" | "blocked";
+export type TargetedUpdateOwnership = "absent" | "direct-only" | "pack-only" | "combined";
+export type TargetedUpdateEffect = "unchanged" | "may-update";
+export interface TargetedUpdatePublicContext {
+    readonly target: {
+        readonly type: TargetedUpdateTargetType;
+        readonly name: string;
+        readonly fqn: string;
+    };
+    readonly ownership: TargetedUpdateOwnership;
+    readonly activation: "enabled" | "disabled";
+    readonly authority: TargetedUpdateAuthority;
+    readonly direct?: {
+        readonly source: "bundled" | "inline" | "registry" | "workspace";
+        readonly enabled: boolean;
+        readonly constraint?: string;
+    };
+    readonly packs: ReadonlyArray<{
+        readonly fqn: string;
+        readonly configuredName?: string;
+        readonly source?: "registry" | "workspace";
+        readonly memberSource: "registry" | "workspace";
+        readonly constraint: string;
+        readonly enabled: boolean;
+    }>;
+    readonly effectiveConstraint?: string;
+    readonly memberClosure: ReadonlyArray<{
+        readonly type: TargetedUpdateTargetType;
+        readonly name: string;
+        readonly fqn: string;
+    }>;
+    readonly effects: {
+        readonly settings: TargetedUpdateEffect;
+        readonly acceptedResolution: TargetedUpdateEffect;
+        readonly canonical: TargetedUpdateEffect;
+        readonly projection: TargetedUpdateEffect;
+        readonly packRoot: TargetedUpdateEffect;
+        readonly packManifest: TargetedUpdateEffect;
+    };
+    readonly relevantProblems: ReadonlyArray<string>;
+    readonly blocker?: TargetedUpdateBlocker;
+}
+export interface TargetedUpdateContext {
+    readonly public: TargetedUpdatePublicContext;
+    readonly fingerprint: string;
+    readonly packEvidenceFingerprint: string;
+}
+export interface TargetedUpdateTarget {
+    readonly type: TargetedUpdatePublicContext["target"]["type"];
+    readonly name: string;
+    readonly fqn: string;
+}
+export interface ClassifyTargetedUpdateArgs {
+    readonly target: TargetedUpdateTarget;
+    readonly explicitRange?: string;
+    readonly graph: DesiredStateGraph;
+    readonly configuredPacks: ReadonlyArray<ConfiguredRecordRow>;
+    readonly configuredOwner?: string;
+    readonly packEvidence?: ReadonlyArray<unknown>;
+}
+export declare const classifyTargetedUpdate: (args: ClassifyTargetedUpdateArgs) => TargetedUpdateContext;
+/** Everything the classifier reads before it can answer. */
+export type TargetedUpdateContextFailure = WorkspaceStateReadFailure | WorkspaceSettingsReadFailure | WorkspaceLockfileReadFailure;
+/**
+ * Read the workspace facts a targeted update is classified against, then
+ * classify twice: once to learn which Packs own the target, and once more
+ * with those Packs' accepted resolutions folded into the fingerprint.
+ */
+export declare const resolveTargetedUpdateContext: (args: {
+    readonly target: TargetedUpdateTarget;
+    readonly explicitRange?: string;
+}) => Effect.Effect<TargetedUpdateContext, TargetedUpdateContextFailure, WorkspaceMutations>;
+//# sourceMappingURL=targeted-update-context.d.ts.map

package/dist/src/update/targeted-update-context.js

@@ -0,0 +1,217 @@
+/**
+ * Ownership, authority, and blocker classification for a targeted update.
+ *
+ * A person naming one extension asks a question the workspace has to answer
+ * before any Registry is contacted: does this workspace desire the extension
+ * at all, who owns the declaration that would move (a direct entry, an owning
+ * Pack, or both), is the entry active, which version constraint actually
+ * governs it once every declared constraint is intersected, and is there a
+ * reason the advance may not be made — an authored or bundled source, an
+ * incomplete Pack graph, a constraint with no compatible intersection, or a
+ * Pack-owned member the request would fork into direct intent.
+ *
+ * The classification is pure over the desired-state graph plus the configured
+ * Pack rows; `resolveTargetedUpdateContext` reads those and adds the accepted
+ * Pack evidence the fingerprint covers. The fingerprint is the freshness
+ * witness a targeted update rechecks under the workspace transition, so a
+ * context that changed between planning and apply stops the operation instead
+ * of applying a decision the workspace no longer supports.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as crypto from "node:crypto";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { isWorkspaceSourceLocator } from "@agentxm/extension-model/unstable/sources/workspace";
+import { parseSourceQualifiedRegistrySourcePatternParts } from "@agentxm/extension-model/unstable/extensions";
+import { intersectVersionConstraints } from "@agentxm/extension-model/unstable/version-constraints";
+import { WorkspaceMutations, configuredRowsByName, desiredStateProblemText, } from "@agentxm/workspace-state";
+const normalizedIdentity = (identity) => {
+    for (const prefix of ["workspace:", "bundled:"]) {
+        if (identity.startsWith(prefix))
+            return identity.slice(prefix.length);
+    }
+    return identity;
+};
+const registryFqnFromSource = (source) => {
+    if (source === undefined)
+        return undefined;
+    const parsed = parseSourceQualifiedRegistrySourcePatternParts(source);
+    return parsed?.name === undefined ? undefined : `${parsed.owner}/${parsed.type}/${parsed.name}`;
+};
+const sourceAuthority = (source) => isWorkspaceSourceLocator(source) ? "workspace" : "registry";
+const configuredPackFqn = (entry, configuredOwner) => {
+    if (entry.source === undefined)
+        return undefined;
+    if (entry.source === "registry" || isWorkspaceSourceLocator(entry.source)) {
+        return configuredOwner === undefined ? undefined : `${configuredOwner}/packs/${entry.name}`;
+    }
+    const source = normalizedIdentity(entry.source);
+    const parsed = parseSourceQualifiedRegistrySourcePatternParts(source);
+    return parsed?.type === "packs" && parsed.name !== undefined
+        ? `${parsed.owner}/packs/${parsed.name}`
+        : undefined;
+};
+const originConstraint = (origin) => origin.type === "settings" && origin.authority === "inline" ? undefined : origin.constraint;
+const blockedEffects = {
+    settings: "unchanged",
+    acceptedResolution: "unchanged",
+    canonical: "unchanged",
+    projection: "unchanged",
+    packRoot: "unchanged",
+    packManifest: "unchanged",
+};
+const plannedEffects = (authority, explicitRange) => ({
+    settings: authority === "direct" && explicitRange !== undefined ? "may-update" : "unchanged",
+    acceptedResolution: "may-update",
+    canonical: "may-update",
+    projection: "may-update",
+    packRoot: "unchanged",
+    packManifest: "unchanged",
+});
+const publicFingerprint = (value) => crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex");
+export const classifyTargetedUpdate = (args) => {
+    const node = args.graph.nodes.find((candidate) => candidate.type === args.target.type &&
+        (normalizedIdentity(candidate.identity) === args.target.fqn ||
+            (candidate.type === "mcp-server" &&
+                registryFqnFromSource(candidate.source) === args.target.fqn)));
+    const targetProblems = args.graph.problems.filter((problem) => (problem.type === "projection-collision" || problem.type === "constraint-conflict") &&
+        problem.extensionType === args.target.type &&
+        problem.name === args.target.name);
+    const relevantProblems = args.graph.problems.filter((problem) => problem.type.startsWith("pack-") ||
+        problem.type === "constraint-conflict" ||
+        targetProblems.includes(problem));
+    const directOrigin = node?.origins.find((origin) => origin.type === "settings");
+    const bundled = node?.identity.startsWith("bundled:") === true;
+    const packOrigins = (node?.origins ?? [])
+        .filter((origin) => origin.type === "pack")
+        .sort((left, right) => left.pack.localeCompare(right.pack));
+    const ownership = directOrigin === undefined
+        ? packOrigins.length === 0
+            ? "absent"
+            : "pack-only"
+        : packOrigins.length === 0
+            ? "direct-only"
+            : "combined";
+    const packs = packOrigins.map((origin) => {
+        const configured = args.configuredPacks.find((entry) => configuredPackFqn(entry, args.configuredOwner) === normalizedIdentity(origin.pack));
+        return {
+            fqn: normalizedIdentity(origin.pack),
+            ...(configured === undefined ? {} : { configuredName: configured.name }),
+            ...(configured?.source === undefined
+                ? {}
+                : {
+                    source: sourceAuthority(configured.source),
+                }),
+            memberSource: sourceAuthority(origin.source),
+            constraint: origin.constraint,
+            enabled: origin.enabled,
+        };
+    });
+    const direct = directOrigin === undefined
+        ? undefined
+        : {
+            source: directOrigin.source === undefined
+                ? "inline"
+                : bundled
+                    ? "bundled"
+                    : sourceAuthority(directOrigin.source),
+            enabled: directOrigin.enabled,
+            ...(directOrigin.constraint === undefined ? {} : { constraint: directOrigin.constraint }),
+        };
+    const constraints = [
+        ...(directOrigin === undefined
+            ? []
+            : [args.explicitRange ?? originConstraint(directOrigin)].filter((constraint) => constraint !== undefined)),
+        ...packOrigins.map((origin) => origin.constraint),
+    ];
+    const intersection = intersectVersionConstraints(constraints);
+    const activation = node?.enabled === true ? "enabled" : "disabled";
+    let blocker;
+    if (relevantProblems.length > 0) {
+        blocker = targetProblems.some((problem) => problem.type === "constraint-conflict")
+            ? "constraint-conflict"
+            : "incomplete-graph";
+    }
+    else if (node === undefined) {
+        blocker = "not-desired";
+    }
+    else if (!node.enabled) {
+        blocker = "disabled";
+    }
+    else if (direct?.source === "bundled") {
+        blocker = "bundled-source";
+    }
+    else if (direct?.source === "inline" ||
+        direct?.source === "workspace" ||
+        packOrigins.some((origin) => isWorkspaceSourceLocator(origin.source))) {
+        blocker = "source-authority";
+    }
+    else if (ownership === "pack-only" && args.explicitRange !== undefined) {
+        blocker = "pack-owned-constraint";
+    }
+    else if (intersection === undefined) {
+        blocker = "constraint-conflict";
+    }
+    const authority = blocker !== undefined ? "blocked" : directOrigin === undefined ? "pack-aware" : "direct";
+    const publicContext = {
+        target: args.target,
+        ownership,
+        activation,
+        authority,
+        ...(direct === undefined ? {} : { direct }),
+        packs,
+        ...(intersection === undefined || intersection.length === 0
+            ? {}
+            : { effectiveConstraint: intersection }),
+        memberClosure: node === undefined ? [] : [args.target],
+        effects: authority === "blocked" ? blockedEffects : plannedEffects(authority, args.explicitRange),
+        relevantProblems: relevantProblems
+            .map((problem) => `${problem.type}: ${desiredStateProblemText(problem)}`)
+            .sort((left, right) => left.localeCompare(right)),
+        ...(blocker === undefined ? {} : { blocker }),
+    };
+    return {
+        public: publicContext,
+        fingerprint: publicFingerprint({
+            publicContext,
+            directSource: directOrigin?.source,
+            packSources: packOrigins.map((origin) => origin.source),
+            packEvidence: args.packEvidence ?? [],
+        }),
+        packEvidenceFingerprint: publicFingerprint(args.packEvidence ?? []),
+    };
+};
+/**
+ * Read the workspace facts a targeted update is classified against, then
+ * classify twice: once to learn which Packs own the target, and once more
+ * with those Packs' accepted resolutions folded into the fingerprint.
+ */
+export const resolveTargetedUpdateContext = Effect.fn("TargetedUpdate.resolveContext")(function* (args) {
+    const workspace = yield* WorkspaceMutations;
+    const graph = yield* workspace.getDesiredStateGraph();
+    const configuredPacks = yield* workspace.records
+        .rows("pack")
+        .pipe(Effect.map((rows) => Object.values(configuredRowsByName(rows))));
+    const configuredOwner = yield* workspace.getConfiguredOwner();
+    const baseArgs = {
+        target: args.target,
+        ...(args.explicitRange === undefined ? {} : { explicitRange: args.explicitRange }),
+        graph,
+        configuredPacks,
+        ...(Option.isNone(configuredOwner) ? {} : { configuredOwner: configuredOwner.value }),
+    };
+    const preliminary = classifyTargetedUpdate(baseArgs);
+    const packEvidence = yield* Effect.all(preliminary.public.packs.map((pack) => Effect.gen(function* () {
+        const packNode = graph.nodes.find((candidate) => candidate.type === "pack" && normalizedIdentity(candidate.identity) === pack.fqn);
+        if (packNode === undefined)
+            return { fqn: pack.fqn, accepted: "absent" };
+        const accepted = yield* workspace.getLockedPack(packNode.name);
+        return {
+            fqn: pack.fqn,
+            accepted: Option.getOrUndefined(accepted) ?? "absent",
+        };
+    })));
+    return classifyTargetedUpdate({ ...baseArgs, packEvidence });
+});
+//# sourceMappingURL=targeted-update-context.js.map

package/dist/src/version-resolution.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Version selection under the minimum-release-age policy.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import type { ReleaseAgeEvaluation, ReleaseAgeEvidence, ReleaseAgeExemption } from "@agentxm/extension-model/unstable/extensions/release-age";
+import type { VersionEntry } from "@agentxm/registry-protocol/unstable/registry/schema";
+/**
+ * Resolve a version request against the versions that have reached the
+ * minimum release age, reading the clock through the Effect environment.
+ */
+export declare const resolveVersionEntryWithReleaseAge: (versions: ReadonlyArray<VersionEntry>, versionRange: Option.Option<string>, minimumReleaseAge: Option.Option<Duration.Duration>) => Effect.Effect<Option.Option<VersionEntry>>;
+export type ReleaseAgeVersionResolution = {
+    readonly kind: "selected";
+    readonly version: VersionEntry;
+    readonly newerHeld?: ReleaseAgeEvidence;
+} | {
+    readonly kind: "exempted";
+    readonly version: VersionEntry;
+    readonly bypassed: ReleaseAgeEvidence;
+    readonly exemption: ReleaseAgeExemption;
+} | {
+    readonly kind: "version_unsatisfied";
+} | {
+    readonly kind: "policy_held";
+    readonly candidate: ReleaseAgeEvidence;
+};
+/**
+ * Resolve one visible Registry index under one caller-supplied release-age
+ * evaluation. The supplied timestamp makes a complete operation deterministic.
+ * An accepted version that satisfies the requested range is a lower bound for
+ * unattended selection, even while that version is itself under age.
+ */
+export declare const resolveVersionEntryForReleaseAge: (versions: ReadonlyArray<VersionEntry>, versionRange: Option.Option<string>, evaluation: ReleaseAgeEvaluation, exemption?: ReleaseAgeExemption, acceptedVersion?: string) => ReleaseAgeVersionResolution;
+//# sourceMappingURL=version-resolution.d.ts.map

package/dist/src/version-resolution.js

@@ -0,0 +1,76 @@
+/**
+ * Version selection under the minimum-release-age policy.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as semver from "semver";
+import { resolveVersionEntry } from "@agentxm/registry-protocol/unstable/registry/version-selection";
+import { filterMatureVersions, isVersionEntryEligibleAt, releaseAgeEvidence, } from "./release-age-policy.js";
+/**
+ * Resolve a version request against the versions that have reached the
+ * minimum release age, reading the clock through the Effect environment.
+ */
+export const resolveVersionEntryWithReleaseAge = (versions, versionRange, minimumReleaseAge) => {
+    if (Option.isNone(minimumReleaseAge)) {
+        return Effect.succeed(resolveVersionEntry(versions, versionRange));
+    }
+    return filterMatureVersions(versions, minimumReleaseAge.value).pipe(Effect.map((mature) => resolveVersionEntry(mature, versionRange)));
+};
+/**
+ * Resolve one visible Registry index under one caller-supplied release-age
+ * evaluation. The supplied timestamp makes a complete operation deterministic.
+ * An accepted version that satisfies the requested range is a lower bound for
+ * unattended selection, even while that version is itself under age.
+ */
+export const resolveVersionEntryForReleaseAge = (versions, versionRange, evaluation, exemption, acceptedVersion) => {
+    const otherwiseSelected = resolveVersionEntry(versions, versionRange);
+    if (Option.isNone(otherwiseSelected)) {
+        return { kind: "version_unsatisfied" };
+    }
+    const candidate = otherwiseSelected.value;
+    const candidateEligible = isVersionEntryEligibleAt(candidate, evaluation);
+    if (!candidateEligible && exemption !== undefined) {
+        return {
+            kind: "exempted",
+            version: candidate,
+            bypassed: releaseAgeEvidence(candidate, evaluation),
+            exemption,
+        };
+    }
+    const eligible = versions.filter((entry) => isVersionEntryEligibleAt(entry, evaluation));
+    const eligibleSelection = resolveVersionEntry(eligible, versionRange);
+    const accepted = versions.find((entry) => {
+        if (entry.version !== acceptedVersion)
+            return false;
+        if (Option.isNone(versionRange))
+            return true;
+        return semver.valid(versionRange.value) === versionRange.value
+            ? entry.version === versionRange.value
+            : semver.satisfies(entry.version, versionRange.value);
+    });
+    const selected = accepted !== undefined &&
+        (Option.isNone(eligibleSelection) ||
+            semver.compareBuild(accepted.version, eligibleSelection.value.version) > 0)
+        ? Option.some(accepted)
+        : eligibleSelection;
+    if (Option.isNone(selected)) {
+        return {
+            kind: "policy_held",
+            candidate: releaseAgeEvidence(candidate, evaluation),
+        };
+    }
+    const selectedAcceptedFloor = accepted?.version === selected.value.version && !candidateEligible;
+    return {
+        kind: "selected",
+        version: selected.value,
+        ...(candidateEligible ||
+            (candidate.version === selected.value.version && !selectedAcceptedFloor)
+            ? {}
+            : { newerHeld: releaseAgeEvidence(candidate, evaluation) }),
+    };
+};
+//# sourceMappingURL=version-resolution.js.map

package/package.json

@@ -0,0 +1,66 @@
+{
+  "author": "AgentXM <hello@agentxm.ai> (https://agentxm.ai)",
+  "bugs": {
+    "url": "https://github.com/agentxm/axm/issues"
+  },
+  "dependencies": {
+    "@agentxm/extension-content": "^0.28.14-preview.1789139351.5cd4595aa",
+    "@agentxm/extension-model": "^0.28.14-preview.1789139351.5cd4595aa",
+    "@agentxm/extension-sources": "^0.28.14-preview.1789139351.5cd4595aa",
+    "@agentxm/registry-protocol": "^0.28.14-preview.1789139351.5cd4595aa",
+    "@agentxm/workspace-state": "^0.28.14-preview.1789139351.5cd4595aa",
+    "effect": "4.0.0-rc.112",
+    "semver": "^7.8.5"
+  },
+  "description": "AXM extension resolution policy: what a configured or requested extension resolves to and whether that resolution may be accepted — release-age policy, version selection, configured-entry and Pack dependency resolution, workspace source authority, publisher-binding trust, and official AXM skill compatibility. Unstable and unsupported — use the axm.sh CLI.",
+  "devDependencies": {
+    "@agentxm/specification-metadata": "^0.28.14-preview.1789139351.5cd4595aa",
+    "@effect/platform-node": "4.0.0-rc.112",
+    "@effect/vitest": "4.0.0-rc.112",
+    "@types/semver": "^7.7.1",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "exports": {
+    ".": {
+      "axm-source": "./src/index.ts",
+      "default": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    },
+    "./live": {
+      "axm-source": "./src/live.ts",
+      "default": "./dist/src/live.js",
+      "types": "./dist/src/live.d.ts"
+    },
+    "./testing": {
+      "axm-source": "./src/testing.ts",
+      "default": "./dist/src/testing.js",
+      "types": "./dist/src/testing.d.ts"
+    }
+  },
+  "files": [
+    "dist/src/",
+    "!**/*.map"
+  ],
+  "homepage": "https://axm.sh",
+  "license": "FSL-1.1-MIT",
+  "name": "@agentxm/extension-resolution",
+  "nx": {
+    "includedScripts": []
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "packages/core/extension-resolution",
+    "type": "git",
+    "url": "https://github.com/agentxm/axm.git"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "version": "0.28.14-preview.1789139351.5cd4595aa"
+}