dominus-cli 2.2.1 → 2.4.0

package/plugin/Dominus.rbxmx

@@ -256,10 +256,445 @@ return "__DOMINUS_BRIDGE_TOKEN__"
       </Properties>
     </Item>
     <Item class="ModuleScript" referent="2">
+      <Properties>
+        <string name="Name">Building</string>
+        <string name="Source"><![CDATA[local ChangeHistoryService = game:GetService("ChangeHistoryService")
+local Selection = game:GetService("Selection")
+
+local InstanceRegistry = require(script.Parent.InstanceRegistry)
+local ValueCodec = require(script.Parent.ValueCodec)
+
+local Building = {}
+
+local MAX_ITEMS = 200
+local MAX_PROPERTIES = 100
+
+local ALLOWED_PART_CLASSES = {
+	Part = true,
+	WedgePart = true,
+	CornerWedgePart = true,
+	TrussPart = true,
+	MeshPart = true,
+	SpawnLocation = true,
+	Seat = true,
+	VehicleSeat = true,
+}
+
+local function resolve(target, label)
+	local instance, err = InstanceRegistry.resolve(target)
+	if not instance then
+		error(label .. ": " .. tostring(err))
+	end
+	return instance
+end
+
+local function cleanup(instances)
+	for _, instance in instances do
+		pcall(function()
+			if instance.Parent == nil then
+				instance:Destroy()
+			end
+		end)
+	end
+end
+
+local function record(name, callback, created)
+	local recording = ChangeHistoryService:TryBeginRecording(name)
+	if not recording then
+		return { success = false, error = "Another plugin recording is already active" }
+	end
+
+	local ok, result = pcall(callback)
+	if not ok then
+		ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Cancel)
+		cleanup(created or {})
+		return { success = false, error = tostring(result), rolledBack = true }
+	end
+
+	ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
+	result.success = true
+	return result
+end
+
+local function finiteNumber(value, label)
+	assert(type(value) == "number" and value == value and math.abs(value) < math.huge, label .. " must be finite")
+	return value
+end
+
+local function vector3(value, label, default)
+	if value == nil then
+		return default
+	end
+	assert(type(value) == "table", label .. " must be a Vector3 object")
+	return Vector3.new(
+		finiteNumber(value.X or value.x or value[1], label .. ".x"),
+		finiteNumber(value.Y or value.y or value[2], label .. ".y"),
+		finiteNumber(value.Z or value.z or value[3], label .. ".z")
+	)
+end
+
+local function rotation(value, label)
+	local degrees = vector3(value, label, Vector3.zero)
+	return CFrame.fromOrientation(math.rad(degrees.X), math.rad(degrees.Y), math.rad(degrees.Z))
+end
+
+local function setProperties(instance, properties)
+	if properties == nil then
+		return {}
+	end
+	assert(type(properties) == "table", "properties must be an object")
+	local count = 0
+	local applied = {}
+	for propertyName, value in properties do
+		count += 1
+		if count > MAX_PROPERTIES then
+			error("At most " .. MAX_PROPERTIES .. " properties are allowed per item")
+		end
+		applied[propertyName] = ValueCodec.setProperty(instance, propertyName, value)
+	end
+	return applied
+end
+
+local function validateItemCount(items, label, maximum)
+	assert(type(items) == "table" and #items > 0, label .. " must contain at least one item")
+	assert(#items <= maximum, label .. " is limited to " .. maximum .. " items")
+end
+
+local function assertMovable(instance, label)
+	assert(instance ~= game and instance.Parent ~= game, label .. " cannot be a DataModel service")
+end
+
+function Building.createParts(spec)
+	validateItemCount(spec.parts, "parts", MAX_ITEMS)
+	local parent = spec.parent and resolve(spec.parent, "parent") or workspace
+	local group = nil
+	local created = {}
+
+	return record("Dominus 2: Build parts", function()
+		if spec.groupName ~= nil then
+			assert(type(spec.groupName) == "string" and #spec.groupName > 0, "groupName must be a non-empty string")
+			local groupClass = spec.groupClass or "Model"
+			assert(groupClass == "Model" or groupClass == "Folder", "groupClass must be Model or Folder")
+			group = Instance.new(groupClass)
+			group.Name = spec.groupName
+			table.insert(created, group)
+		end
+
+		local parts = {}
+		for index, item in spec.parts do
+			assert(type(item) == "table", "Part " .. index .. " must be an object")
+			assert(type(item.name) == "string" and #item.name > 0, "Part " .. index .. ".name must be a non-empty string")
+			local className = item.className or "Part"
+			if item.shape == "Wedge" then
+				className = "WedgePart"
+			elseif item.shape == "CornerWedge" then
+				className = "CornerWedgePart"
+			end
+			assert(ALLOWED_PART_CLASSES[className] == true, "Part " .. index .. " uses an unsupported class: " .. tostring(className))
+
+			local part = Instance.new(className)
+			table.insert(created, part)
+			part.Name = item.name
+			if part:IsA("BasePart") then
+				part.Anchored = item.anchored ~= false
+			end
+			if item.position then
+				part.Position = vector3(item.position, "Part " .. index .. ".position")
+			end
+			if item.orientation then
+				part.Orientation = vector3(item.orientation, "Part " .. index .. ".orientation")
+			end
+			if item.size then
+				part.Size = vector3(item.size, "Part " .. index .. ".size")
+			end
+			if item.color then
+				ValueCodec.setProperty(part, "Color", item.color)
+			end
+			if item.material then
+				ValueCodec.setProperty(part, "Material", item.material)
+			end
+			if item.transparency ~= nil then
+				part.Transparency = finiteNumber(item.transparency, "Part " .. index .. ".transparency")
+			end
+			if item.canCollide ~= nil then
+				assert(type(item.canCollide) == "boolean", "Part " .. index .. ".canCollide must be a boolean")
+				part.CanCollide = item.canCollide
+			end
+			if item.shape and className == "Part" then
+				ValueCodec.setProperty(part, "Shape", item.shape)
+			end
+			setProperties(part, item.properties)
+			part.Parent = group or parent
+			table.insert(parts, part)
+		end
+
+		if group then
+			group.Parent = parent
+		end
+
+		local refs = {}
+		for _, part in parts do
+			table.insert(refs, InstanceRegistry.toRef(part))
+		end
+		return {
+			created = refs,
+			group = group and InstanceRegistry.toRef(group) or nil,
+			count = #refs,
+		}
+	end, created)
+end
+
+function Building.cloneInstances(spec)
+	validateItemCount(spec.requests, "requests", 100)
+	local created = {}
+
+	return record("Dominus 2: Clone instances", function()
+		local clones = {}
+		local totalCopies = 0
+		for requestIndex, request in spec.requests do
+			assert(type(request) == "table", "Clone request " .. requestIndex .. " must be an object")
+			local source = resolve(request.target, "Clone request " .. requestIndex .. " target")
+			assertMovable(source, "Clone source")
+			local parent = request.parent and resolve(request.parent, "Clone request " .. requestIndex .. " parent") or source.Parent
+			assert(parent ~= nil, "Clone request " .. requestIndex .. " source has no parent")
+			local count = request.count or 1
+			assert(type(count) == "number" and count % 1 == 0 and count >= 1 and count <= 50, "count must be an integer from 1 to 50")
+			totalCopies += count
+			assert(totalCopies <= MAX_ITEMS, "A clone batch is limited to " .. MAX_ITEMS .. " copies")
+			local offset = vector3(request.offset, "Clone request " .. requestIndex .. ".offset", Vector3.zero)
+			local stepOffset = vector3(request.stepOffset, "Clone request " .. requestIndex .. ".stepOffset", Vector3.zero)
+
+			for copyIndex = 1, count do
+				local clone = source:Clone()
+				assert(clone ~= nil, "Clone request " .. requestIndex .. " target is not Archivable")
+				table.insert(created, clone)
+				if request.name then
+					clone.Name = count == 1 and request.name or (request.name .. " " .. copyIndex)
+				end
+				setProperties(clone, request.properties)
+				if clone:IsA("PVInstance") then
+					local totalOffset = offset + stepOffset * (copyIndex - 1)
+					clone:PivotTo(clone:GetPivot() + totalOffset)
+				elseif offset.Magnitude > 0 or stepOffset.Magnitude > 0 then
+					error("Clone request " .. requestIndex .. " cannot offset a non-PVInstance")
+				end
+				clone.Parent = parent
+				table.insert(clones, InstanceRegistry.toRef(clone))
+			end
+		end
+		return { clones = clones, count = #clones }
+	end, created)
+end
+
+local function validateIndependentTargets(targets)
+	for leftIndex, left in targets do
+		for rightIndex = leftIndex + 1, #targets do
+			local right = targets[rightIndex]
+			assert(not left:IsAncestorOf(right) and not right:IsAncestorOf(left), "Targets " .. leftIndex .. " and " .. rightIndex .. " overlap")
+		end
+	end
+end
+
+function Building.groupInstances(spec)
+	validateItemCount(spec.targets, "targets", 100)
+	assert(type(spec.name) == "string" and #spec.name > 0, "name must be a non-empty string")
+	local className = spec.className or "Model"
+	assert(className == "Model" or className == "Folder", "className must be Model or Folder")
+	local targets = {}
+	for index, targetRef in spec.targets do
+		local target = resolve(targetRef, "Target " .. index)
+		assertMovable(target, "Target " .. index)
+		table.insert(targets, target)
+	end
+	validateIndependentTargets(targets)
+	local parent = spec.parent and resolve(spec.parent, "parent") or targets[1].Parent
+	assert(parent ~= nil, "The first target has no parent")
+	local created = {}
+
+	return record("Dominus 2: Group instances", function()
+		local group = Instance.new(className)
+		table.insert(created, group)
+		group.Name = spec.name
+		group.Parent = parent
+		for _, target in targets do
+			assert(not target:IsAncestorOf(group), "Cannot group an ancestor into its descendant")
+			target.Parent = group
+		end
+		return { group = InstanceRegistry.toRef(group), count = #targets }
+	end, created)
+end
+
+function Building.ungroupInstances(spec)
+	assert(spec.confirm == true, "confirm must be true")
+	validateItemCount(spec.targets, "targets", 20)
+
+	return record("Dominus 2: Ungroup instances", function()
+		local moved = {}
+		local removed = {}
+		for index, targetRef in spec.targets do
+			local group = resolve(targetRef, "Group " .. index)
+			assert(group:IsA("Model") or group:IsA("Folder"), "Group " .. index .. " must be a Model or Folder")
+			assertMovable(group, "Group " .. index)
+			local parent = spec.parent and resolve(spec.parent, "parent") or group.Parent
+			assert(parent ~= nil, "Group " .. index .. " has no parent")
+			for _, child in group:GetChildren() do
+				child.Parent = parent
+				table.insert(moved, InstanceRegistry.toRef(child))
+			end
+			table.insert(removed, { name = group.Name, className = group.ClassName })
+			group:Destroy()
+		end
+		return { moved = moved, removedGroups = removed, count = #moved }
+	end)
+end
+
+local function absolutePivot(current, operation)
+	if operation.cframe then
+		return ValueCodec.decodeForCurrent(current, operation.cframe)
+	end
+	local position = vector3(operation.position, "position", current.Position)
+	local x, y, z = current:ToOrientation()
+	if operation.orientation then
+		local degrees = vector3(operation.orientation, "orientation")
+		x, y, z = math.rad(degrees.X), math.rad(degrees.Y), math.rad(degrees.Z)
+	end
+	return CFrame.new(position) * CFrame.fromOrientation(x, y, z)
+end
+
+function Building.transformInstances(spec)
+	validateItemCount(spec.operations, "operations", 100)
+
+	return record("Dominus 2: Transform instances", function()
+		local results = {}
+		for index, operation in spec.operations do
+			local target = resolve(operation.target, "Operation " .. index .. " target")
+			assert(target:IsA("PVInstance"), "Operation " .. index .. " target must be a Model or BasePart")
+			local current = target:GetPivot()
+			local mode = operation.mode or "absolute"
+			local nextPivot
+			if mode == "absolute" then
+				nextPivot = absolutePivot(current, operation)
+			elseif mode == "relative" then
+				local offset = vector3(operation.offset, "Operation " .. index .. ".offset", Vector3.zero)
+				local rotate = rotation(operation.rotationOffset, "Operation " .. index .. ".rotationOffset")
+				if operation.space == "local" then
+					nextPivot = current * CFrame.new(offset) * rotate
+				else
+					nextPivot = CFrame.new(offset) * current * rotate
+				end
+			else
+				error("Operation " .. index .. ".mode must be absolute or relative")
+			end
+			target:PivotTo(nextPivot)
+			table.insert(results, { target = InstanceRegistry.toRef(target), pivot = ValueCodec.encode(target:GetPivot()) })
+		end
+		return { transformed = results, count = #results }
+	end)
+end
+
+function Building.createWelds(spec)
+	validateItemCount(spec.welds, "welds", MAX_ITEMS)
+	local created = {}
+
+	return record("Dominus 2: Create welds", function()
+		local welds = {}
+		for index, item in spec.welds do
+			local part0 = resolve(item.part0, "Weld " .. index .. " part0")
+			local part1 = resolve(item.part1, "Weld " .. index .. " part1")
+			assert(part0:IsA("BasePart") and part1:IsA("BasePart"), "Weld " .. index .. " endpoints must be BaseParts")
+			assert(part0 ~= part1, "Weld " .. index .. " endpoints must be different")
+			local parent = item.parent and resolve(item.parent, "Weld " .. index .. " parent") or part0
+			local weld = Instance.new("WeldConstraint")
+			table.insert(created, weld)
+			weld.Name = item.name or (part0.Name .. "_to_" .. part1.Name)
+			weld.Part0 = part0
+			weld.Part1 = part1
+			weld.Parent = parent
+			table.insert(welds, InstanceRegistry.toRef(weld))
+		end
+		return { welds = welds, count = #welds }
+	end, created)
+end
+
+local function overlapParams(spec)
+	local params = OverlapParams.new()
+	local maxParts = spec.maxParts or 200
+	assert(type(maxParts) == "number" and maxParts % 1 == 0 and maxParts >= 1 and maxParts <= 500, "maxParts must be an integer from 1 to 500")
+	params.MaxParts = maxParts
+	params.RespectCanCollide = spec.respectCanCollide == true
+	if spec.filter and #spec.filter > 0 then
+		local instances = {}
+		for index, targetRef in spec.filter do
+			table.insert(instances, resolve(targetRef, "Filter " .. index))
+		end
+		params.FilterDescendantsInstances = instances
+		params.FilterType = spec.filterType == "Include" and Enum.RaycastFilterType.Include or Enum.RaycastFilterType.Exclude
+	end
+	return params
+end
+
+function Building.queryParts(spec)
+	local root = spec.root and resolve(spec.root, "root") or workspace
+	assert(root:IsA("WorldRoot"), "root must be Workspace or a WorldModel")
+	local mode = spec.mode or "box"
+	local found
+	if mode == "box" then
+		local position = vector3(spec.position, "position")
+		local size = vector3(spec.size, "size")
+		assert(size.X > 0 and size.Y > 0 and size.Z > 0, "size components must be greater than zero")
+		local box = CFrame.new(position) * rotation(spec.orientation, "orientation")
+		found = root:GetPartBoundsInBox(box, size, overlapParams(spec))
+	elseif mode == "radius" then
+		local position = vector3(spec.position, "position")
+		local radius = finiteNumber(spec.radius, "radius")
+		assert(radius > 0, "radius must be greater than zero")
+		found = root:GetPartBoundsInRadius(position, radius, overlapParams(spec))
+	else
+		error("mode must be box or radius")
+	end
+
+	table.sort(found, function(left, right)
+		return InstanceRegistry.getDisplayPath(left) < InstanceRegistry.getDisplayPath(right)
+	end)
+	local parts = {}
+	for _, part in found do
+		table.insert(parts, {
+			name = part.Name,
+			className = part.ClassName,
+			ref = InstanceRegistry.toRef(part),
+			position = ValueCodec.encode(part.Position),
+			size = ValueCodec.encode(part.Size),
+		})
+	end
+	return { success = true, parts = parts, count = #parts, mode = mode }
+end
+
+function Building.setSelection(spec)
+	assert(type(spec.targets) == "table", "targets must be an array")
+	assert(#spec.targets <= 200, "At most 200 instances can be selected")
+	local targets = {}
+	for index, targetRef in spec.targets do
+		table.insert(targets, resolve(targetRef, "Target " .. index))
+	end
+	Selection:Set(targets)
+	local selected = {}
+	for _, target in targets do
+		table.insert(selected, InstanceRegistry.toRef(target))
+	end
+	return { success = true, selection = selected, count = #selected }
+end
+
+return Building
+]]></string>
+      </Properties>
+    </Item>
+    <Item class="ModuleScript" referent="3">
       <Properties>
         <string name="Name">CommandRouter</string>
-        <string name="Source"><![CDATA[local Explorer = require(script.Parent.Explorer)
+        <string name="Source"><![CDATA[local Building = require(script.Parent.Building)
+local Explorer = require(script.Parent.Explorer)
 local InstanceRegistry = require(script.Parent.InstanceRegistry)
+local Metadata = require(script.Parent.Metadata)
 local Mutation = require(script.Parent.Mutation)
 local Properties = require(script.Parent.Properties)
 local Reflection = require(script.Parent.Reflection)
@@ -297,6 +732,45 @@ local handlers = {
 	["studio:v2:apply"] = function(payload)
 		return Mutation.apply(payload)
 	end,
+	["studio:v2:create_parts"] = function(payload)
+		return Building.createParts(payload)
+	end,
+	["studio:v2:clone_instances"] = function(payload)
+		return Building.cloneInstances(payload)
+	end,
+	["studio:v2:group_instances"] = function(payload)
+		return Building.groupInstances(payload)
+	end,
+	["studio:v2:ungroup_instances"] = function(payload)
+		return Building.ungroupInstances(payload)
+	end,
+	["studio:v2:transform_instances"] = function(payload)
+		return Building.transformInstances(payload)
+	end,
+	["studio:v2:create_welds"] = function(payload)
+		return Building.createWelds(payload)
+	end,
+	["studio:v2:query_parts"] = function(payload)
+		return Building.queryParts(payload)
+	end,
+	["studio:v2:set_selection"] = function(payload)
+		return Building.setSelection(payload)
+	end,
+	["studio:v2:get_metadata"] = function(payload)
+		return Metadata.get(payload)
+	end,
+	["studio:v2:set_attributes"] = function(payload)
+		return Metadata.setAttributes(payload)
+	end,
+	["studio:v2:update_tags"] = function(payload)
+		return Metadata.updateTags(payload)
+	end,
+	["studio:v2:list_callable_methods"] = function(payload)
+		return Metadata.listCallableMethods(payload)
+	end,
+	["studio:v2:invoke_methods"] = function(payload)
+		return Metadata.invoke(payload)
+	end,
 	["studio:v2:delete"] = function(payload)
 		return Mutation.delete(payload)
 	end,
@@ -355,7 +829,7 @@ return CommandRouter
 ]]></string>
       </Properties>
     </Item>
-    <Item class="ModuleScript" referent="3">
+    <Item class="ModuleScript" referent="4">
       <Properties>
         <string name="Name">Explorer</string>
         <string name="Source"><![CDATA[--[[
@@ -891,7 +1365,7 @@ return Explorer
 ]]></string>
       </Properties>
     </Item>
-    <Item class="ModuleScript" referent="4">
+    <Item class="ModuleScript" referent="5">
       <Properties>
         <string name="Name">InstanceRegistry</string>
         <string name="Source"><![CDATA[local HttpService = game:GetService("HttpService")
@@ -1019,12 +1493,430 @@ return InstanceRegistry
 ]]></string>
       </Properties>
     </Item>
-    <Item class="ModuleScript" referent="5">
+    <Item class="ModuleScript" referent="6">
+      <Properties>
+        <string name="Name">Metadata</string>
+        <string name="Source"><![CDATA[local ChangeHistoryService = game:GetService("ChangeHistoryService")
+
+local InstanceRegistry = require(script.Parent.InstanceRegistry)
+local ValueCodec = require(script.Parent.ValueCodec)
+
+local Metadata = {}
+
+local MAX_TARGETS = 100
+local MAX_ITEMS_PER_TARGET = 100
+local MAX_METHOD_CALLS = 50
+
+local ATTRIBUTE_TYPES = {
+	string = true,
+	boolean = true,
+	number = true,
+	UDim = true,
+	UDim2 = true,
+	BrickColor = true,
+	Color3 = true,
+	Vector2 = true,
+	Vector3 = true,
+	CFrame = true,
+	NumberSequence = true,
+	ColorSequence = true,
+	NumberRange = true,
+	Rect = true,
+	Font = true,
+}
+
+local METHOD_POLICY = {
+	GetAttribute = { kind = "read", className = "Instance", params = { { type = "string" } } },
+	GetAttributes = { kind = "read", className = "Instance", params = {} },
+	GetTags = { kind = "read", className = "Instance", params = {} },
+	HasTag = { kind = "read", className = "Instance", params = { { type = "string" } } },
+	GetFullName = { kind = "read", className = "Instance", params = {} },
+	IsA = { kind = "read", className = "Instance", params = { { type = "string" } } },
+	IsAncestorOf = { kind = "read", className = "Instance", params = { { type = "Instance" } } },
+	IsDescendantOf = { kind = "read", className = "Instance", params = { { type = "Instance" } } },
+	FindFirstChild = {
+		kind = "read",
+		className = "Instance",
+		params = { { type = "string" }, { type = "boolean", optional = true } },
+	},
+	FindFirstChildOfClass = { kind = "read", className = "Instance", params = { { type = "string" } } },
+	FindFirstChildWhichIsA = {
+		kind = "read",
+		className = "Instance",
+		params = { { type = "string" }, { type = "boolean", optional = true } },
+	},
+	FindFirstAncestor = { kind = "read", className = "Instance", params = { { type = "string" } } },
+	FindFirstAncestorOfClass = { kind = "read", className = "Instance", params = { { type = "string" } } },
+	FindFirstAncestorWhichIsA = { kind = "read", className = "Instance", params = { { type = "string" } } },
+	GetChildren = { kind = "read", className = "Instance", params = {} },
+	GetDescendants = { kind = "read", className = "Instance", params = {} },
+	GetPivot = { kind = "read", className = "PVInstance", params = {} },
+	GetScale = { kind = "read", className = "Model", params = {} },
+	GetBoundingBox = { kind = "read", className = "Model", params = {} },
+	AddTag = { kind = "write", className = "Instance", params = { { type = "string", tag = true } } },
+	RemoveTag = { kind = "write", className = "Instance", params = { { type = "string", tag = true } } },
+	SetAttribute = {
+		kind = "write",
+		className = "Instance",
+		params = { { type = "string", attributeName = true }, { type = "Attribute", allowNil = true } },
+	},
+	PivotTo = { kind = "write", className = "PVInstance", params = { { type = "CFrame" } } },
+	ScaleTo = { kind = "write", className = "Model", params = { { type = "number" } } },
+}
+
+local function resolve(ref, label)
+	local instance, err = InstanceRegistry.resolve(ref)
+	if not instance then
+		error(label .. ": " .. tostring(err))
+	end
+	return instance
+end
+
+local function validateName(value, label)
+	assert(type(value) == "string", label .. " must be a string")
+	assert(#value > 0 and #value <= 100, label .. " must contain 1 to 100 characters")
+	assert(not value:find("[%c]"), label .. " cannot contain control characters")
+	return value
+end
+
+local function validateTag(value)
+	return validateName(value, "Tag")
+end
+
+local function validateAttributeName(value)
+	return validateName(value, "Attribute name")
+end
+
+local function prepareAttributeChanges(set, remove, label)
+	set = set or {}
+	remove = remove or {}
+	assert(type(set) == "table" and type(remove) == "table", "set and remove must be arrays")
+	assert(#set + #remove > 0, label .. " has no attribute updates")
+	assert(#set + #remove <= MAX_ITEMS_PER_TARGET, "Too many attribute updates in " .. label)
+
+	local changes = {}
+	local seen = {}
+	for itemIndex, item in set do
+		assert(type(item) == "table" and type(item.value) == "table", "Set item " .. itemIndex .. " is invalid")
+		local name = validateAttributeName(item.name)
+		assert(not seen[name], "Attribute " .. name .. " appears more than once")
+		local typeName = item.value.type
+		assert(ATTRIBUTE_TYPES[typeName], "Unsupported attribute type: " .. tostring(typeName))
+		seen[name] = true
+		table.insert(changes, { name = name, value = ValueCodec.decodeTyped(typeName, item.value.value) })
+	end
+	for _, nameValue in remove do
+		local name = validateAttributeName(nameValue)
+		assert(not seen[name], "Attribute " .. name .. " cannot be set and removed together")
+		seen[name] = true
+		table.insert(changes, { name = name, remove = true })
+	end
+	return changes
+end
+
+local function applyPreparedAttributeChanges(target, changes)
+	for _, change in changes do
+		if change.remove then
+			target:SetAttribute(change.name, nil)
+		else
+			target:SetAttribute(change.name, change.value)
+		end
+	end
+end
+
+local function prepareTagChanges(add, remove, label)
+	add = add or {}
+	remove = remove or {}
+	assert(type(add) == "table" and type(remove) == "table", "add and remove must be arrays")
+	assert(#add + #remove > 0, label .. " has no tag updates")
+	assert(#add + #remove <= MAX_ITEMS_PER_TARGET, "Too many tag updates in " .. label)
+
+	local seen = {}
+	for _, tagValue in add do
+		local tag = validateTag(tagValue)
+		assert(not seen[tag], "Tag " .. tag .. " appears more than once")
+		seen[tag] = "add"
+	end
+	for _, tagValue in remove do
+		local tag = validateTag(tagValue)
+		assert(not seen[tag], "Tag " .. tag .. " cannot be added and removed together")
+		seen[tag] = "remove"
+	end
+	return add, remove
+end
+
+local function applyPreparedTagChanges(target, add, remove)
+	for _, tag in add do
+		target:AddTag(tag)
+	end
+	for _, tag in remove do
+		target:RemoveTag(tag)
+	end
+end
+
+local function sortedTags(instance)
+	local tags = instance:GetTags()
+	table.sort(tags)
+	return tags
+end
+
+local function encodedAttributes(instance)
+	local attributes = instance:GetAttributes()
+	local names = {}
+	for name in attributes do
+		table.insert(names, name)
+	end
+	table.sort(names)
+
+	local encoded = {}
+	for _, name in names do
+		table.insert(encoded, {
+			name = name,
+			value = ValueCodec.encodeTyped(attributes[name]),
+		})
+	end
+	return encoded
+end
+
+local function metadataFor(instance)
+	return {
+		ref = InstanceRegistry.toRef(instance),
+		name = instance.Name,
+		className = instance.ClassName,
+		tags = sortedTags(instance),
+		attributes = encodedAttributes(instance),
+	}
+end
+
+local function beginRecording(name)
+	local recording = ChangeHistoryService:TryBeginRecording(name)
+	if not recording then
+		error("Another plugin recording is already active")
+	end
+	return recording
+end
+
+function Metadata.get(spec)
+	assert(type(spec.targets) == "table" and #spec.targets > 0, "targets must contain at least one instance reference")
+	assert(#spec.targets <= MAX_TARGETS, "At most " .. MAX_TARGETS .. " instances can be inspected at once")
+	local results = {}
+	for index, targetRef in spec.targets do
+		table.insert(results, metadataFor(resolve(targetRef, "Target " .. index)))
+	end
+	return { success = true, results = results }
+end
+
+function Metadata.setAttributes(spec)
+	assert(type(spec.operations) == "table" and #spec.operations > 0, "operations must contain at least one attribute update")
+	assert(#spec.operations <= MAX_TARGETS, "At most " .. MAX_TARGETS .. " attribute operations are allowed")
+
+	local prepared = {}
+	for index, operation in spec.operations do
+		assert(type(operation) == "table", "Operation " .. index .. " must be an object")
+		table.insert(prepared, {
+			target = resolve(operation.target, "Operation " .. index .. " target"),
+			changes = prepareAttributeChanges(operation.set, operation.remove, "Operation " .. index),
+		})
+	end
+
+	local recording = beginRecording("Dominus 2: Update attributes")
+	local ok, err = pcall(function()
+		for _, operation in prepared do
+			applyPreparedAttributeChanges(operation.target, operation.changes)
+		end
+	end)
+	if not ok then
+		ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Cancel)
+		return { success = false, error = tostring(err), rolledBack = true }
+	end
+	ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
+
+	local results = {}
+	for _, operation in prepared do
+		table.insert(results, metadataFor(operation.target))
+	end
+	return { success = true, operationCount = #prepared, results = results }
+end
+
+function Metadata.updateTags(spec)
+	assert(type(spec.operations) == "table" and #spec.operations > 0, "operations must contain at least one tag update")
+	assert(#spec.operations <= MAX_TARGETS, "At most " .. MAX_TARGETS .. " tag operations are allowed")
+
+	local prepared = {}
+	for index, operation in spec.operations do
+		assert(type(operation) == "table", "Operation " .. index .. " must be an object")
+		local add, remove = prepareTagChanges(operation.add, operation.remove, "Operation " .. index)
+		table.insert(prepared, {
+			target = resolve(operation.target, "Operation " .. index .. " target"),
+			add = add,
+			remove = remove,
+		})
+	end
+
+	local recording = beginRecording("Dominus 2: Update tags")
+	local ok, err = pcall(function()
+		for _, operation in prepared do
+			applyPreparedTagChanges(operation.target, operation.add, operation.remove)
+		end
+	end)
+	if not ok then
+		ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Cancel)
+		return { success = false, error = tostring(err), rolledBack = true }
+	end
+	ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
+
+	local results = {}
+	for _, operation in prepared do
+		table.insert(results, metadataFor(operation.target))
+	end
+	return { success = true, operationCount = #prepared, results = results }
+end
+
+function Metadata.applyAttributeChangesWithinRecording(target, set, remove)
+	local changes = prepareAttributeChanges(set, remove, "Mutation operation")
+	applyPreparedAttributeChanges(target, changes)
+	return encodedAttributes(target)
+end
+
+function Metadata.applyTagChangesWithinRecording(target, add, remove)
+	local preparedAdd, preparedRemove = prepareTagChanges(add, remove, "Mutation operation")
+	applyPreparedTagChanges(target, preparedAdd, preparedRemove)
+	return sortedTags(target)
+end
+
+local function publicPolicy(methodName, policy)
+	local params = {}
+	for _, param in policy.params do
+		table.insert(params, {
+			type = param.type,
+			optional = param.optional or false,
+		})
+	end
+	return {
+		name = methodName,
+		kind = policy.kind,
+		className = policy.className,
+		parameters = params,
+	}
+end
+
+function Metadata.listCallableMethods(spec)
+	local target = resolve(spec.target, "Target")
+	local methods = {}
+	for methodName, policy in METHOD_POLICY do
+		if target:IsA(policy.className) then
+			table.insert(methods, publicPolicy(methodName, policy))
+		end
+	end
+	table.sort(methods, function(left, right)
+		return left.name < right.name
+	end)
+	return {
+		success = true,
+		target = InstanceRegistry.toRef(target),
+		methods = methods,
+		blockedByDefault = true,
+	}
+end
+
+local function decodeArgument(argument, parameter, label)
+	assert(type(argument) == "table" and type(argument.type) == "string", label .. " must be a typed value")
+	if parameter.type == "Attribute" then
+		if argument.type == "nil" and parameter.allowNil then
+			return nil
+		end
+		assert(ATTRIBUTE_TYPES[argument.type], label .. " must be a supported Roblox attribute type")
+		return ValueCodec.decodeTyped(argument.type, argument.value)
+	end
+	assert(argument.type == parameter.type, label .. " must have type " .. parameter.type)
+	local decoded = ValueCodec.decodeTyped(argument.type, argument.value)
+	if parameter.tag then
+		validateTag(decoded)
+	elseif parameter.attributeName then
+		validateAttributeName(decoded)
+	end
+	return decoded
+end
+
+function Metadata.invoke(spec)
+	assert(type(spec.calls) == "table" and #spec.calls > 0, "calls must contain at least one method call")
+	assert(#spec.calls <= MAX_METHOD_CALLS, "At most " .. MAX_METHOD_CALLS .. " method calls are allowed")
+
+	local prepared = {}
+	local hasWrites = false
+	for index, call in spec.calls do
+		assert(type(call) == "table", "Call " .. index .. " must be an object")
+		local methodName = call.method
+		local policy = METHOD_POLICY[methodName]
+		assert(policy, "Method is not allowed by Dominus: " .. tostring(methodName))
+		local target = resolve(call.target, "Call " .. index .. " target")
+		assert(target:IsA(policy.className), methodName .. " requires " .. policy.className .. ", got " .. target.ClassName)
+		local arguments = call.arguments or {}
+		assert(type(arguments) == "table", "Call " .. index .. " arguments must be an array")
+		local minimum = 0
+		for _, parameter in policy.params do
+			if not parameter.optional then
+				minimum += 1
+			end
+		end
+		assert(#arguments >= minimum and #arguments <= #policy.params, methodName .. " received the wrong number of arguments")
+
+		local decoded = {}
+		for argumentIndex, argument in arguments do
+			decoded[argumentIndex] = decodeArgument(argument, policy.params[argumentIndex], "Argument " .. argumentIndex)
+		end
+		table.insert(prepared, {
+			target = target,
+			method = methodName,
+			policy = policy,
+			arguments = decoded,
+			argumentCount = #arguments,
+		})
+		hasWrites = hasWrites or policy.kind == "write"
+	end
+
+	local recording = hasWrites and beginRecording("Dominus 2: Invoke safe instance methods") or nil
+	local results = {}
+	local ok, err = pcall(function()
+		for _, call in prepared do
+			local method = call.target[call.method]
+			assert(type(method) == "function", call.method .. " is unavailable on " .. call.target.ClassName)
+			local returned = table.pack(method(call.target, table.unpack(call.arguments, 1, call.argumentCount)))
+			local values = {}
+			for resultIndex = 1, returned.n do
+				table.insert(values, ValueCodec.encodeTyped(returned[resultIndex]))
+			end
+			table.insert(results, {
+				target = InstanceRegistry.toRef(call.target),
+				method = call.method,
+				kind = call.policy.kind,
+				results = values,
+			})
+		end
+	end)
+	if not ok then
+		if recording then
+			ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Cancel)
+		end
+		return { success = false, error = tostring(err), rolledBack = recording ~= nil }
+	end
+	if recording then
+		ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Commit)
+	end
+	return { success = true, callCount = #results, mutationRecorded = recording ~= nil, results = results }
+end
+
+return Metadata
+]]></string>
+      </Properties>
+    </Item>
+    <Item class="ModuleScript" referent="7">
       <Properties>
         <string name="Name">Mutation</string>
         <string name="Source"><![CDATA[local ChangeHistoryService = game:GetService("ChangeHistoryService")
 
 local InstanceRegistry = require(script.Parent.InstanceRegistry)
+local Metadata = require(script.Parent.Metadata)
 local ValueCodec = require(script.Parent.ValueCodec)
 
 local Mutation = {}
@@ -1068,6 +1960,7 @@ function Mutation.apply(spec)
 	end
 
 	local results = {}
+	local created = {}
 	local ok, err = pcall(function()
 		for index, operation in operations do
 			assert(type(operation) == "table", "Operation " .. index .. " must be an object")
@@ -1078,17 +1971,53 @@ function Mutation.apply(spec)
 					target = InstanceRegistry.toRef(target),
 					properties = setProperties(target, operation.properties),
 				})
+			elseif operation.op == "setAttributes" then
+				local target = resolve(operation.target, "Operation " .. index .. " target")
+				table.insert(results, {
+					op = operation.op,
+					target = InstanceRegistry.toRef(target),
+					attributes = Metadata.applyAttributeChangesWithinRecording(target, operation.set, operation.remove),
+				})
+			elseif operation.op == "updateTags" then
+				local target = resolve(operation.target, "Operation " .. index .. " target")
+				table.insert(results, {
+					op = operation.op,
+					target = InstanceRegistry.toRef(target),
+					tags = Metadata.applyTagChangesWithinRecording(target, operation.add, operation.remove),
+				})
 			elseif operation.op == "create" then
 				local parent = resolve(operation.parent, "Operation " .. index .. " parent")
 				assert(type(operation.className) == "string", "create.className must be a string")
 				assert(type(operation.name) == "string", "create.name must be a string")
 				local instance = Instance.new(operation.className)
+				table.insert(created, instance)
 				instance.Name = operation.name
 				if operation.properties then
 					setProperties(instance, operation.properties)
 				end
 				instance.Parent = parent
 				table.insert(results, { op = operation.op, created = InstanceRegistry.toRef(instance) })
+			elseif operation.op == "clone" then
+				local target = resolve(operation.target, "Operation " .. index .. " target")
+				assert(target ~= game and target.Parent ~= game, "Services cannot be cloned")
+				local parent = operation.parent and resolve(operation.parent, "Operation " .. index .. " parent") or target.Parent
+				assert(parent ~= nil, "Clone target has no parent")
+				local clone = target:Clone()
+				assert(clone ~= nil, "Clone target is not Archivable")
+				table.insert(created, clone)
+				if operation.name then
+					clone.Name = operation.name
+				end
+				if operation.properties then
+					setProperties(clone, operation.properties)
+				end
+				if operation.offset then
+					assert(clone:IsA("PVInstance"), "Only Models and BaseParts can be spatially offset")
+					local offset = ValueCodec.decodeForCurrent(Vector3.zero, operation.offset)
+					clone:PivotTo(clone:GetPivot() + offset)
+				end
+				clone.Parent = parent
+				table.insert(results, { op = operation.op, created = InstanceRegistry.toRef(clone) })
 			elseif operation.op == "move" then
 				local target = resolve(operation.target, "Operation " .. index .. " target")
 				local parent = resolve(operation.parent, "Operation " .. index .. " parent")
@@ -1103,6 +2032,13 @@ function Mutation.apply(spec)
 
 	if not ok then
 		ChangeHistoryService:FinishRecording(recording, Enum.FinishRecordingOperation.Cancel)
+		for _, instance in created do
+			pcall(function()
+				if instance.Parent == nil then
+					instance:Destroy()
+				end
+			end)
+		end
 		return { success = false, error = tostring(err), rolledBack = true }
 	end
 
@@ -1160,7 +2096,7 @@ return Mutation
 ]]></string>
       </Properties>
     </Item>
-    <Item class="ModuleScript" referent="6">
+    <Item class="ModuleScript" referent="8">
       <Properties>
         <string name="Name">Properties</string>
         <string name="Source"><![CDATA[--[[
@@ -2025,7 +2961,7 @@ return Properties
 ]]></string>
       </Properties>
     </Item>
-    <Item class="ModuleScript" referent="7">
+    <Item class="ModuleScript" referent="9">
       <Properties>
         <string name="Name">Protocol</string>
         <string name="Source"><![CDATA[--[[
@@ -2061,7 +2997,7 @@ return Protocol
 ]]></string>
       </Properties>
     </Item>
-    <Item class="ModuleScript" referent="8">
+    <Item class="ModuleScript" referent="10">
       <Properties>
         <string name="Name">Reflection</string>
         <string name="Source"><![CDATA[local ReflectionService = game:GetService("ReflectionService")
@@ -2236,7 +3172,7 @@ return Reflection
 ]]></string>
       </Properties>
     </Item>
-    <Item class="ModuleScript" referent="9">
+    <Item class="ModuleScript" referent="11">
       <Properties>
         <string name="Name">TestRunner</string>
         <string name="Source"><![CDATA[local StudioTestService = game:GetService("StudioTestService")
@@ -2311,7 +3247,7 @@ return TestRunner
 ]]></string>
       </Properties>
     </Item>
-    <Item class="ModuleScript" referent="10">
+    <Item class="ModuleScript" referent="12">
       <Properties>
         <string name="Name">UIBuilder</string>
         <string name="Source"><![CDATA[--[[
@@ -3174,7 +4110,7 @@ return UIBuilder
 ]]></string>
       </Properties>
     </Item>
-    <Item class="ModuleScript" referent="11">
+    <Item class="ModuleScript" referent="13">
       <Properties>
         <string name="Name">ValueCodec</string>
         <string name="Source"><![CDATA[local InstanceRegistry = require(script.Parent.InstanceRegistry)
@@ -3387,6 +4323,122 @@ function ValueCodec.encode(value)
 	return tostring(value)
 end
 
+local TYPED_DEFAULTS = {
+	UDim = function()
+		return UDim.new()
+	end,
+	UDim2 = function()
+		return UDim2.new()
+	end,
+	Vector2 = function()
+		return Vector2.zero
+	end,
+	Vector3 = function()
+		return Vector3.zero
+	end,
+	Color3 = function()
+		return Color3.new()
+	end,
+	BrickColor = function()
+		return BrickColor.new("Medium stone grey")
+	end,
+	Rect = function()
+		return Rect.new()
+	end,
+	NumberRange = function()
+		return NumberRange.new(0)
+	end,
+	CFrame = function()
+		return CFrame.new()
+	end,
+	NumberSequence = function()
+		return NumberSequence.new(0)
+	end,
+	ColorSequence = function()
+		return ColorSequence.new(Color3.new())
+	end,
+	Font = function()
+		return Font.new("rbxasset://fonts/families/SourceSansPro.json")
+	end,
+}
+
+function ValueCodec.decodeTyped(typeName, value)
+	assert(type(typeName) == "string", "Typed value requires a type")
+	if typeName == "nil" then
+		return nil
+	end
+	if typeName == "string" or typeName == "number" or typeName == "boolean" then
+		return ValueCodec.decodeForCurrent(typeName == "string" and "" or typeName == "number" and 0 or false, value)
+	end
+	if typeName == "Instance" then
+		local resolved, err = InstanceRegistry.resolve(value)
+		if not resolved then
+			error(err)
+		end
+		return resolved
+	end
+	local createDefault = TYPED_DEFAULTS[typeName]
+	if not createDefault then
+		error("Unsupported typed value: " .. typeName)
+	end
+	return ValueCodec.decodeForCurrent(createDefault(), value)
+end
+
+local function encodeSerializable(value, depth, state, seen)
+	if depth > 5 then
+		return "<maximum depth reached>"
+	end
+	if type(value) ~= "table" then
+		return ValueCodec.encode(value)
+	end
+	if seen[value] then
+		return "<cycle>"
+	end
+	seen[value] = true
+
+	local count = 0
+	local maxIndex = 0
+	local isArray = true
+	for key in value do
+		count += 1
+		state.count += 1
+		if state.count > state.limit then
+			seen[value] = nil
+			return "<result truncated>"
+		end
+		if type(key) ~= "number" or key < 1 or key % 1 ~= 0 then
+			isArray = false
+		else
+			maxIndex = math.max(maxIndex, key)
+		end
+	end
+
+	local result = {}
+	if isArray and maxIndex == count then
+		for index = 1, maxIndex do
+			result[index] = encodeSerializable(value[index], depth + 1, state, seen)
+		end
+	else
+		for key, child in value do
+			result[tostring(key)] = encodeSerializable(child, depth + 1, state, seen)
+		end
+	end
+	seen[value] = nil
+	return result
+end
+
+function ValueCodec.encodeSerializable(value, limit)
+	return encodeSerializable(value, 0, { count = 0, limit = limit or 500 }, {})
+end
+
+function ValueCodec.encodeTyped(value, limit)
+	local encoded = { type = typeof(value) }
+	if value ~= nil then
+		encoded.value = ValueCodec.encodeSerializable(value, limit)
+	end
+	return encoded
+end
+
 function ValueCodec.setProperty(instance, propertyName, value)
 	if propertyName == "Parent" or propertyName == "ClassName" or propertyName == "Source" then
 		error("Property cannot be changed through setProperties: " .. propertyName)
@@ -3411,7 +4463,7 @@ return ValueCodec
 ]]></string>
       </Properties>
     </Item>
-    <Item class="ModuleScript" referent="12">
+    <Item class="ModuleScript" referent="14">
       <Properties>
         <string name="Name">Watcher</string>
         <string name="Source"><![CDATA[--[[
@@ -3502,7 +4554,7 @@ return Watcher
 ]]></string>
       </Properties>
     </Item>
-    <Item class="ModuleScript" referent="13">
+    <Item class="ModuleScript" referent="15">
       <Properties>
         <string name="Name">WsClient</string>
         <string name="Source"><![CDATA[local HttpService = game:GetService("HttpService")