feat(studio): deliver asset authoring and automation workflows
Test / Tests and coverage occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/pr-master There was a failure building this commit

Add shared human/task asset batches with reviewed atomic publication, explicit
reference rebinds, ownership inspection and qualified glyph/scene budgets.
Expose the same authoring and capacity results through Assets and MCP.

Deliver isolated guest test targets, retained visual evidence and immutable
runtime lifecycle/control observations. Preserve provider qualification and
installed authoring examples alongside the completed discussion lessons.

Close AGD-106 coordination and the delivered discussion workflows through
housekeeping, updating lesson references and preserving qualification limits.
Sound remains outside the asset delivery wave.

Validation: 579 module tests and 31 additional desktop, process and installed
checks passed; native glyph/scene 16/17 boundaries qualified. Discussion
validation passed after housekeeping.
This commit is contained in:
2026-11-11 01:21:25 +00:00
parent b351f2e582
commit 1471b427f1
325 changed files with 61179 additions and 323 deletions
@@ -111,13 +111,27 @@ public class StudioApplicationConfiguration {
}
@Bean
AssetPacking assetPacking(PackerWorkspaceService packer, OperationExecutor operations, p.studio.api.automation.ProjectAccess access) {
return new PackerAssetPacking(packer, operations, access);
p.studio.app.assets.AssetBudgetInspection assetBudgetInspection(ObjectMapper mapper,PackerWorkspaceService packer,ProjectLocalStudioSetupStore setup) {
return new p.studio.app.assets.AssetBudgetInspection(mapper,packer,setup::load);
}
@Bean
p.studio.core.assets.AssetBatchWorkspace assetBatchWorkspace(ObjectMapper mapper,PackerWorkspaceService packer,p.studio.app.assets.AssetBudgetInspection budgets) {
return new p.studio.app.assets.FileAssetBatchWorkspace(mapper,packer,budgets::inspect);
}
@Bean
p.studio.api.assets.AssetAuthoringService assetAuthoringService(p.studio.core.project.ProjectAccessRegistry projects,ProjectCatalog catalog,
p.studio.core.assets.AssetBatchWorkspace workspace,OperationExecutor operations) {
return new p.studio.core.assets.DefaultAssetAuthoringService(projects,catalog,workspace,operations);
}
@Bean
AssetPacking assetPacking(PackerWorkspaceService packer, OperationExecutor operations, p.studio.api.automation.ProjectAccess access,p.studio.app.assets.AssetBudgetInspection budgets) {
return new PackerAssetPacking(packer, operations, access).withAssetPreflight(budgets);
}
@Bean
AssetDetails assetDetails(PackerWorkspaceService packer) {
return new PackerAssetDetails(packer);
return new PackerAssetDetails(packer,false);
}
@Bean
@@ -146,8 +160,8 @@ public class StudioApplicationConfiguration {
}
@Bean
AssetMetadataService assetMetadataService(ObjectMapper mapper, p.studio.api.automation.ProjectAccess access) {
return new AssetStudioMetadataService(mapper, access);
AssetMetadataService assetMetadataService(ObjectMapper mapper, p.studio.api.automation.ProjectAccess access,PackerWorkspaceService packer) {
return new AssetStudioMetadataService(mapper, access,packer);
}
@Bean
@@ -197,8 +211,8 @@ public class StudioApplicationConfiguration {
@Bean
StudioShipperService shipper(CompilerBuildGateway compiler, PackerWorkspaceService packer, ObjectMapper mapper,
OperationExecutor operations, p.studio.api.automation.ProjectAccess access) {
return new StudioShipperService(compiler, packer, mapper, operations, access);
OperationExecutor operations, p.studio.api.automation.ProjectAccess access,p.studio.app.assets.AssetBudgetInspection budgets) {
return new StudioShipperService(compiler, packer, mapper, operations, access).withAssetPreflight(budgets);
}
@Bean(destroyMethod = "shutdown")
@@ -252,8 +266,13 @@ public class StudioApplicationConfiguration {
ProjectLocalStudioSetupStore setupStore, LspLifecyclePort lsp,
p.studio.core.project.ProjectAccessRegistry access, OperationExecutor operations,
p.studio.api.automation.AutomationConnectionLifecycle connections,
p.studio.api.automation.AgentIntegrationPreparation preparation) {
return new DefaultProjectSessionFactory(stateStore, setupStore, lsp, access, operations, connections, preparation);
p.studio.api.automation.AgentIntegrationPreparation preparation, p.studio.api.automation.EvidenceTools evidence,
p.studio.api.automation.GuestTestTools tests,p.studio.api.assets.AssetAuthoringService authoring) {
var factory = new DefaultProjectSessionFactory(stateStore, setupStore, lsp, access, operations, connections, preparation);
factory.setEvidenceTools(evidence);
factory.setGuestTestTools(tests);
factory.setAssetAuthoring(authoring);
return factory;
}
@Bean
@@ -350,14 +369,35 @@ public class StudioApplicationConfiguration {
return new p.studio.core.session.DefaultTaskTools(projects, catalog, shipper, headless);
}
@Bean
p.studio.api.automation.EvidenceTools evidenceTools(p.studio.core.project.ProjectAccessRegistry projects,
p.studio.api.automation.TaskTools tasks, ObjectMapper mapper) {
return new p.studio.core.session.DefaultEvidenceTools(projects, tasks,
new p.studio.app.evidence.FileEvidenceStore(mapper), new p.studio.app.evidence.PngEvidenceCodec());
}
@Bean(destroyMethod = "close")
p.studio.core.session.DefaultGuestTestTools guestTestTools(p.studio.core.project.ProjectAccessRegistry projects,
ProjectCatalog catalog, p.studio.core.shipper.SavedProjectPreparation shipper,
p.studio.core.runtime.HeadlessGateway gateway, ObjectMapper mapper, OperationExecutor operations) {
var support = new p.studio.app.runtime.GuestTestSupportAdapter(mapper,
new p.studio.app.evidence.FileEvidenceStore(mapper),new p.studio.app.evidence.PngEvidenceCodec());
return new p.studio.core.session.DefaultGuestTestTools(projects,catalog,shipper,gateway,support,
new p.studio.app.runtime.GuestEventDecoder(mapper),operations);
}
@Bean
p.studio.app.mcp.McpToolRegistry mcpToolRegistry(p.studio.app.mcp.McpToolCatalog catalog, ObjectMapper mapper,
p.studio.api.automation.ProjectKnowledge knowledge, p.studio.api.automation.LanguageQueries language,
p.studio.api.automation.TaskTools tasks, p.studio.api.assets.animation.AnimationTasks animations, java.util.Optional<p.studio.core.runtime.HeadlessGateway> headless) {
p.studio.api.automation.TaskTools tasks, p.studio.api.assets.animation.AnimationTasks animations,
p.studio.api.automation.EvidenceTools evidence, p.studio.api.automation.GuestTestTools tests,p.studio.api.assets.AssetAuthoringService assets, java.util.Optional<p.studio.core.runtime.HeadlessGateway> headless) {
var handlers = new java.util.LinkedHashMap<>(p.studio.app.mcp.McpProjectKnowledgeTools.handlers(knowledge, mapper));
handlers.putAll(p.studio.app.mcp.McpLanguageTools.handlers(language, mapper));
handlers.putAll(p.studio.app.mcp.McpTaskTools.handlers(tasks, mapper, headless.isPresent()));
handlers.putAll(p.studio.app.mcp.McpAnimationTools.handlers(animations, mapper));
handlers.putAll(p.studio.app.mcp.McpEvidenceTools.handlers(evidence, mapper));
if(headless.isPresent())handlers.putAll(p.studio.app.mcp.McpGuestTestTools.handlers(tests,mapper));
handlers.putAll(p.studio.app.mcp.McpAssetAuthoringTools.handlers(assets,mapper));
return new p.studio.app.mcp.McpToolRegistry(catalog, mapper, handlers);
}
@@ -0,0 +1,23 @@
package p.studio.app.assets;
import p.packer.dtos.PackerDiagnosticDTO;
import p.studio.api.assets.AssetBatches;
import p.studio.api.assets.AssetFamily;
import java.nio.file.Path;
import java.util.*;
/** Projects only emitted producer facts. No text parsing or inferred missing indices. */
final class AssetBatchDiagnostics {
static AssetBatches.Diagnostic from(PackerDiagnosticDTO source,Path staged,Path published) {
var context=new LinkedHashMap<String,Object>(source.context());
String root=context.get("assetRoot") instanceof String value?translate(value,staged,published):null;
String path=source.evidencePath()==null?null:translate(source.evidencePath().toString(),staged,published);
if(root!=null)context.put("assetRoot",root);
AssetFamily family=null;if(context.get("family") instanceof String value)try{family=AssetFamily.valueOf(value);}catch(IllegalArgumentException ignored){}
return new AssetBatches.Diagnostic("packer",Objects.requireNonNullElse(source.code(),"PACKER_DIAGNOSTIC"),source.severity().name(),source.message(),source.blocking(),root,path,family,
indices(context.get("missingIndices")),indices(context.get("duplicateIndices")),List.of(),number(context.get("used")),number(context.get("required")),number(context.get("limit")),context);
}
private static List<Integer> indices(Object value){return value instanceof List<?> list?list.stream().filter(Number.class::isInstance).map(n->((Number)n).intValue()).toList():List.of();}
private static Long number(Object value){return value instanceof Number n?n.longValue():null;}
private static String translate(String value,Path from,Path to){Path path=Path.of(value);return path.startsWith(from)?to.resolve(from.relativize(path)).toString():value;}
}
@@ -0,0 +1,36 @@
package p.studio.app.assets;
import com.fasterxml.jackson.annotation.*;
import com.fasterxml.jackson.databind.ObjectMapper;
import p.studio.api.assets.AssetBatches;
/** Persistence/transport tagging belongs to the adapter, not the neutral asset API. */
public final class AssetBatchJson {
private AssetBatchJson(){}
@JsonTypeInfo(use=JsonTypeInfo.Id.NAME,property="kind")
@JsonSubTypes({@JsonSubTypes.Type(value=AssetBatches.CreateBank.class,name="create_bank"),
@JsonSubTypes.Type(value=AssetBatches.RegisterBank.class,name="register_bank"),
@JsonSubTypes.Type(value=AssetBatches.ImportPng.class,name="import_png"),
@JsonSubTypes.Type(value=AssetBatches.ComposeBank.class,name="compose_bank"),
@JsonSubTypes.Type(value=AssetBatches.ComposeScene.class,name="compose_scene"),
@JsonSubTypes.Type(value=AssetBatches.ComposePalettes.class,name="compose_palettes"),
@JsonSubTypes.Type(value=AssetBatches.UpdateContract.class,name="update_contract"),
@JsonSubTypes.Type(value=AssetBatches.BuildParticipation.class,name="build_participation")})
private interface Mutation {}
private interface Reference {
@JsonIgnore boolean isAssetIdReference();
@JsonIgnore boolean isAssetRootReference();
}
public static ObjectMapper mapper(ObjectMapper source){
var module=new com.fasterxml.jackson.databind.module.SimpleModule();
module.addSerializer(p.studio.api.assets.AssetReference.class,new com.fasterxml.jackson.databind.JsonSerializer<>(){
@Override public void serialize(p.studio.api.assets.AssetReference value,com.fasterxml.jackson.core.JsonGenerator out,com.fasterxml.jackson.databind.SerializerProvider provider)throws java.io.IOException{out.writeString(value.value());}
});
module.addDeserializer(p.studio.api.assets.AssetReference.class,new com.fasterxml.jackson.databind.JsonDeserializer<>(){
@Override public p.studio.api.assets.AssetReference deserialize(com.fasterxml.jackson.core.JsonParser parser,com.fasterxml.jackson.databind.DeserializationContext context)throws java.io.IOException {
com.fasterxml.jackson.databind.JsonNode node=parser.readValueAsTree();return p.studio.api.assets.AssetReference.of(node.isTextual()?node.textValue():node.path("value").asText());
}
});
return source.copy().addMixIn(AssetBatches.Mutation.class,Mutation.class).addMixIn(p.studio.api.assets.AssetReference.class,Reference.class).registerModule(module);
}
}
@@ -0,0 +1,77 @@
package p.studio.app.assets;
import com.fasterxml.jackson.databind.ObjectMapper;
import p.studio.api.assets.*;
import p.studio.api.assets.AssetBatches.*;
import p.studio.api.assets.metadata.*;
import p.studio.api.project.ProjectReference;
import p.studio.core.assets.scene.SceneBankWorkflowService;
import java.nio.file.*;
import java.util.*;
/** Calls the existing asset commands and canonical scene emitter on the candidate workspace. */
final class AssetBatchMutations {
private final AssetCommands commands;private final AssetCatalog catalog;private final AssetMetadataService metadata;
private final ObjectMapper json;private final AssetPngSources sources;
private final p.packer.PackerWorkspaceService packer;
AssetBatchMutations(AssetCommands commands,AssetCatalog catalog,AssetMetadataService metadata,ObjectMapper json,AssetPngSources sources,p.packer.PackerWorkspaceService packer) {
this.commands=commands;this.catalog=catalog;this.metadata=metadata;this.json=json;this.sources=sources;this.packer=packer;
}
AssetSummary asset(ProjectReference project,AssetReference reference) {
return catalog.list(project,false).stream().filter(a->a.reference().equals(reference)
||reference.isAssetRootReference()&&project.rootPath().resolve("assets").resolve(reference.rawValue()).normalize().equals(a.root()))
.findFirst().orElseThrow(()->new IllegalArgumentException("Unknown asset: "+reference.value()));
}
void apply(ProjectReference original,ProjectReference stage,Mutation mutation)throws Exception {
switch(mutation) {
case CreateBank c -> {
if(c.family()!=AssetFamily.GLYPH_BANK&&c.family()!=AssetFamily.SCENE_BANK)throw new IllegalArgumentException("This wave supports glyph and scene authoring");
check(commands.create(stage,c.relativeRoot(),c.name(),c.family(),c.outputFormat(),c.outputCodec(),c.preload()));
}
case RegisterBank r -> check(commands.register(stage,r.bank()));
case ImportPng i -> {
var bank=asset(stage,i.bank());if(bank.family()!=AssetFamily.GLYPH_BANK)throw new IllegalArgumentException("PNG import requires a glyph bank");
String relative=stage.rootPath().relativize(bank.root()).resolve(i.destination()).toString();
Path destination=AssetWorkspaceFiles.path(stage.rootPath(),relative);byte[] bytes=sources.bytes(original.rootPath(),i.source());
Files.createDirectories(destination.getParent());Files.write(destination,bytes);
var declaration=json.readTree(bank.root().resolve("asset.json").toFile());var selected=new ArrayList<String>();
declaration.path("artifacts").forEach(a->selected.add(a.path("file").asText()));
if(selected.contains(i.destination()))check(commands.applyBankComposition(stage,bank.reference(),selected));
}
case ComposeBank c -> {
var bank=asset(stage,c.bank());if(bank.family()!=AssetFamily.GLYPH_BANK)throw new IllegalArgumentException("PNG composition requires a glyph bank");
for(String path:c.selectedPaths())AssetWorkspaceFiles.path(stage.rootPath(),stage.rootPath().relativize(bank.root()).resolve(path).toString());
check(commands.applyBankComposition(stage,bank.reference(),c.selectedPaths()));
}
case ComposePalettes p -> {
var bank=asset(stage,p.bank());if(bank.family()!=AssetFamily.GLYPH_BANK)throw new IllegalArgumentException("Palette composition requires a glyph bank");
check(commands.applyPaletteOverhauling(stage,bank.reference(),p.palettes().stream().map(palette->Map.<String,Object>of("index",palette.index(),"rgba8888",palette.rgba8888())).toList()));
}
case ComposeScene c -> {
var bank=asset(stage,c.bank());if(bank.family()!=AssetFamily.SCENE_BANK)throw new IllegalArgumentException("Scene composition requires a scene bank");
var layers=new ArrayList<AssetStudioSceneLayerBinding>();int index=1;
for(var layer:c.layers()) {
String glyph="";if(layer.glyphBank()!=null){var source=asset(stage,layer.glyphBank());if(source.family()!=AssetFamily.GLYPH_BANK)throw new IllegalArgumentException("Scene source must be a glyph bank");glyph=stage.rootPath().resolve("assets").relativize(source.root()).toString();}
var tiles=new ArrayList<AssetStudioSceneTile>();
for(var tile:layer.tiles()) {
if(!tile.active()){tiles.add(AssetStudioSceneTile.inactive(tile.paletteId()));continue;}
var source=asset(stage,tile.artifact().bank());var layerSource=asset(stage,layer.glyphBank());
if(!source.reference().equals(layerSource.reference()))throw new IllegalArgumentException("Tile artifact does not belong to its declared layer bank");
var layout=packer.getGlyphBankLayout(new p.packer.messages.GetGlyphBankLayoutRequest(new p.packer.messages.PackerProjectContext(stage.name(),stage.rootPath()),UUID.fromString(source.assetUuid())));
var selected=layout.glyphs().stream().filter(g->g.artifactId().equals(tile.artifact().artifactId())).findFirst().orElseThrow(()->new IllegalArgumentException("Unknown scene tile artifact"));
if(layer.tileSize()!=0&&layer.tileSize()!=selected.width())throw new IllegalArgumentException("Tile geometry differs from the declared layer size");
tiles.add(new AssetStudioSceneTile(true,selected.glyphId(),tile.paletteId(),tile.flipX(),tile.flipY()));
}
layers.add(new AssetStudioSceneLayerBinding(layer.active(),index,"Layer "+index,layer.width(),layer.height(),"scene.tmx",glyph,layer.parallaxFactorX(),layer.parallaxFactorY(),0,tiles));index++;
}
var value=new AssetStudioSceneBankMetadata(layers.getFirst().width(),layers.getFirst().height(),4,layers,bank.root().resolve("scene-bank.studio.json"));
var written=metadata.writeSceneBankMetadata(bank.root(),value);if(!written.successful())throw new IllegalArgumentException(written.message());
new SceneBankWorkflowService(catalog,json).writeComposition(stage,bank.root(),value);
}
case UpdateContract c -> {var bank=asset(stage,c.bank());check(commands.updateContract(stage,bank.reference(),c.preload(),c.outputCodec(),c.codecFields(),c.metadataFields()));}
case BuildParticipation b -> check(commands.updateBuildParticipation(stage,b.bank(),b.included()));
}
}
private static void check(AssetMutationResult result){if(result.status()!=AssetOperationStatus.SUCCESS)throw new IllegalArgumentException(result.summary());}
private static void check(AssetUpdateResult result){if(!result.success())throw new IllegalArgumentException(result.errorMessage());}
}
@@ -0,0 +1,105 @@
package p.studio.app.assets;
import com.fasterxml.jackson.databind.*;
import com.fasterxml.jackson.databind.node.ObjectNode;
import p.studio.api.assets.*;
import p.studio.api.assets.AssetBatches.*;
import p.studio.api.assets.metadata.AssetMetadataService;
import p.studio.api.project.ProjectReference;
import p.studio.core.assets.scene.SceneBankWorkflowService;
import p.packer.PackerWorkspaceService;
import java.nio.file.*;
import java.util.*;
/** Actual animation/material/scene references are enumerated before any incompatible publication. */
final class AssetBatchReferences {
record Glyph(Artifact identity,int index,String fingerprint,String content){}
private final AssetCatalog catalog;private final AssetMetadataService metadata;private final PackerWorkspaceService packer;private final ObjectMapper json;
AssetBatchReferences(AssetCatalog catalog,AssetMetadataService metadata,PackerWorkspaceService packer,ObjectMapper json) {
this.catalog=catalog;this.metadata=metadata;this.packer=packer;this.json=json;
}
Map<Artifact,Glyph> glyphs(ProjectReference project)throws Exception {
var result=new LinkedHashMap<Artifact,Glyph>();
for(var bank:catalog.list(project,false))if(bank.family()==AssetFamily.GLYPH_BANK) {
var manifest=json.readTree(bank.root().resolve("asset.json").toFile());String contract=manifest.path("output").toString();
for(var artifact:manifest.path("artifacts")) {
String id=artifact.path("artifact_id").asText();if(id.isEmpty())continue;
Path file=AssetWorkspaceFiles.path(project.rootPath(),project.rootPath().relativize(bank.root()).resolve(artifact.path("file").asText()).toString());
String content=AssetWorkspaceFiles.hash((contract+":"+artifact.path("file").asText()+":"+(Files.isRegularFile(file)?AssetWorkspaceFiles.hash(Files.readAllBytes(file)):"missing")).getBytes(java.nio.charset.StandardCharsets.UTF_8));
var identity=new Artifact(bank.reference(),id);result.put(identity,new Glyph(identity,artifact.path("index").asInt(),artifact.path("fingerprint").asText(),content));
}
}return result;
}
List<ReferenceUse> uses(ProjectReference project,Map<Artifact,Glyph> glyphs)throws Exception {
var assets=catalog.list(project,false);var result=new ArrayList<ReferenceUse>();
for(var owner:assets) {
for(String file:List.of("animations.studio.json","glyph-material.json","studio.asset.json")) {
Path path=owner.root().resolve(file);if(!Files.exists(path))continue;
scan(json.readTree(path.toFile()),"",project.rootPath().relativize(path).toString(),owner.reference(),file.startsWith("animations")?ReferenceKind.animation:ReferenceKind.metadata,result);
}
Path scene=owner.root().resolve("scene-bank.studio.json");if(!Files.exists(scene))continue;
var layers=json.readTree(scene.toFile()).path("layers");int layer=0;
for(var node:layers) {
String target=node.path("tileset_asset_root").asText();
var source=assets.stream().filter(a->a.root().equals(project.rootPath().resolve("assets").resolve(target).normalize())).findFirst().orElse(null);
if(source!=null&&node.path("enabled").asBoolean()) {
int tile=0;for(var value:node.path("tiles")) {
int index=value.path("glyph_id").asInt();
if(value.path("active").asBoolean()) {
var glyph=glyphs.values().stream().filter(g->g.identity().bank().equals(source.reference())&&g.index()==index).findFirst().orElse(null);
if(glyph!=null)result.add(new ReferenceUse(owner.reference(),ReferenceKind.scene,project.rootPath().relativize(scene)+"#/layers/"+layer+"/tiles/"+tile,glyph.identity()));
}tile++;
}
}layer++;
}
}return result;
}
private void scan(JsonNode node,String pointer,String file,AssetReference owner,ReferenceKind kind,List<ReferenceUse> uses) {
if(node.isObject()) {
if(node.path("artifact_id").isTextual())uses.add(new ReferenceUse(owner,kind,file+"#"+pointer,new Artifact(owner,node.path("artifact_id").asText())));
var fields=node.fields();while(fields.hasNext()){var field=fields.next();scan(field.getValue(),pointer+"/"+field.getKey().replace("~","~0").replace("/","~1"),file,owner,kind,uses);}
}else if(node.isArray())for(int i=0;i<node.size();i++)scan(node.get(i),pointer+"/"+i,file,owner,kind,uses);
}
List<ReferenceUse> apply(ProjectReference original,ProjectReference stage,List<Rebind> rebinds)throws Exception {
var before=glyphs(original);var after=glyphs(stage);
var affected=uses(original,before).stream().filter(use->{var a=before.get(use.target());var b=after.get(use.target());return b==null||a.index()!=b.index()||!a.content().equals(b.content());}).toList();
var explicit=new HashMap<ReferenceUse,Artifact>();
for(var rebind:rebinds)for(var reference:rebind.references()) {
if(!affected.contains(reference))throw new IllegalArgumentException("Rebind names a reference not affected by this candidate: "+reference.location());
if(explicit.put(reference,rebind.to())!=null)throw new IllegalArgumentException("Duplicate reference rebind");
if(!after.containsKey(rebind.to()))throw new IllegalArgumentException("Replacement artifact is unavailable: "+rebind.to());
}
if(!explicit.keySet().containsAll(affected))return affected;
var modified=new LinkedHashMap<Path,JsonNode>();var scenes=new HashSet<AssetReference>();
for(var use:affected) {
var replacement=after.get(explicit.get(use));String[] location=use.location().split("#",2);
Path path=AssetWorkspaceFiles.path(stage.rootPath(),location[0]);
JsonNode document=modified.computeIfAbsent(path,p->{try{return json.readTree(p.toFile());}catch(Exception error){throw new IllegalStateException(error);}});
var node=(ObjectNode)document.at(location[1]);
if(use.kind()==ReferenceKind.scene) {
node.put("glyph_id",replacement.index());String layerPointer=location[1].substring(0,location[1].indexOf("/tiles/"));
var bank=catalog.list(stage,false).stream().filter(a->a.reference().equals(replacement.identity().bank())).findFirst().orElseThrow();
((ObjectNode)document.at(layerPointer)).put("tileset_asset_root",stage.rootPath().resolve("assets").relativize(bank.root()).toString());scenes.add(use.owner());
}else {
if(!use.owner().equals(replacement.identity().bank()))throw new IllegalArgumentException("Animation/material artifacts belong to their containing bank");
node.put("artifact_id",replacement.identity().artifactId());
if(node.has("glyph_id"))node.put("glyph_id",replacement.index());
if(node.has("fingerprint"))node.put("fingerprint",replacement.fingerprint());
}
}
for(var entry:modified.entrySet())AssetWorkspaceFiles.write(json,entry.getKey(),entry.getValue());
for(var reference:scenes) {
var bank=catalog.list(stage,false).stream().filter(a->a.reference().equals(reference)).findFirst().orElseThrow();
new SceneBankWorkflowService(catalog,json).writeComposition(stage,bank.root(),metadata.read(bank.root(),bank.family()).sceneBankMetadata());
}
validateAnimations(stage);return List.of();
}
private void validateAnimations(ProjectReference project)throws Exception {
var layouts=new PackerGlyphBankLayouts(packer,json);
for(var bank:catalog.list(project,false)) {
Path file=bank.root().resolve(p.animation.AnimationDocument.FILE_NAME);if(!Files.exists(file))continue;
var document=new p.animation.AnimationCodec().decode(Files.readString(file));
layouts.withLayout(project.rootPath(),UUID.fromString(bank.assetUuid()),layout->{new p.animation.AnimationValidator().requireValid(document,layout);return null;});
}
}
}
@@ -0,0 +1,24 @@
package p.studio.app.assets;
import com.fasterxml.jackson.databind.ObjectMapper;
import p.packer.PackerWorkspaceService;
import p.packer.messages.PackerProjectContext;
import p.studio.api.assets.AssetBudgets;
import p.studio.api.project.*;
import p.studio.core.assets.*;
import java.util.function.Function;
/** One pack-plan snapshot feeds Core policy, UI/MCP queries and build admission. */
public final class AssetBudgetInspection implements AssetBuildPreflight {
private final PackerWorkspaceService packer;private final AssetCapacityProfiles profiles;
private final Function<ProjectReference,ProjectLocalStudioSetup> setup;
public AssetBudgetInspection(ObjectMapper json,PackerWorkspaceService packer,Function<ProjectReference,ProjectLocalStudioSetup> setup){this.packer=packer;this.profiles=new AssetCapacityProfiles(json);this.setup=setup;}
@Override public AssetBudgets.Snapshot inspect(ProjectReference project) {
var context=new PackerProjectContext(project.name(),project.rootPath());
return packer.withProject(context,()->{
var plan=packer.planPackWorkspace(context);
return new AssetBudgetPolicy().evaluate(AssetWorkspaceFiles.revision(project.rootPath()),profiles.select(setup.apply(project)),plan,
plan.diagnostics().stream().map(d->AssetBatchDiagnostics.from(d,project.rootPath(),project.rootPath())).toList());
});
}
}
@@ -0,0 +1,39 @@
package p.studio.app.assets;
import com.fasterxml.jackson.databind.ObjectMapper;
import p.studio.api.assets.AssetBudgets.*;
import p.studio.api.project.ProjectLocalStudioSetup;
import java.nio.file.*;
import java.util.*;
/** Installed resource profiles only. Ordinary builds never inspect a sibling runtime checkout. */
public final class AssetCapacityProfiles {
public record Bundle(Profile profile,Map<String,String> executables){}
public record Catalog(int schemaVersion,List<Bundle> profiles){}
private final ObjectMapper json;
public AssetCapacityProfiles(ObjectMapper json){this.json=json;}
public ProfileSelection select(ProjectLocalStudioSetup setup) {
if(setup==null||setup.prometeuRuntimePath()==null)return ProfileSelection.unknown(null,"No runtime installation selected");
String selected=null;
try {
Path root=Path.of(setup.prometeuRuntimePath()).toRealPath();String dispatcher=System.getProperty("os.name").startsWith("Windows")?"prometeu.exe":"prometeu";
selected=AssetWorkspaceFiles.hash(Files.readAllBytes(root.resolve(dispatcher)));
try(var stream=getClass().getResourceAsStream("/asset-capacity/catalog.json")) {
if(stream==null)return ProfileSelection.unknown(selected,"No distributed capacity profiles");
var catalog=json.readValue(stream,Catalog.class);if(catalog.schemaVersion()!=1)throw new IllegalArgumentException("Unsupported profile catalog");
for(var bundle:catalog.profiles())if(bundle.profile().executableSha256().equals(selected)) {
if(!bundle.executables().keySet().containsAll(Set.of("prometeu","prometeu-headless","prometeu-runtime")))throw new IllegalArgumentException("Incomplete executable identity");
for(var entry:bundle.executables().entrySet()) {
if(!Set.of("prometeu","prometeu-headless","prometeu-runtime").contains(entry.getKey()))throw new IllegalArgumentException("Unsupported executable identity");
if(!AssetWorkspaceFiles.hash(Files.readAllBytes(root.resolve(entry.getKey()))).equals(entry.getValue()))return ProfileSelection.unknown(selected,"Runtime component changed: "+entry.getKey());
}
for(var evidence:bundle.profile().evidence())try(var record=getClass().getClassLoader().getResourceAsStream(evidence.evidencePath())) {
if(record==null||!AssetWorkspaceFiles.hash(record.readAllBytes()).equals(evidence.evidenceSha256()))throw new IllegalArgumentException("Capacity evidence integrity mismatch");
}
return new ProfileSelection(QualificationState.known,selected,bundle.profile(),"Exact qualified dispatcher and runtime components match");
}
}
return ProfileSelection.unknown(selected,"Selected executable has no qualified capacity profile");
}catch(Exception invalid){return ProfileSelection.unknown(selected,"Capacity profile unavailable or invalid: "+Objects.requireNonNullElse(invalid.getMessage(),invalid.getClass().getSimpleName()));}
}
}
@@ -0,0 +1,54 @@
package p.studio.app.assets;
import com.fasterxml.jackson.databind.ObjectMapper;
import p.studio.api.assets.*;
import p.studio.api.assets.AssetBatches.Ownership;
import p.studio.api.project.ProjectReference;
import java.nio.file.*;
import java.util.*;
/** Descriptive generation graph. No edge executes a producer or a dependent operation. */
final class AssetOwnershipGraph {
record Record(Ownership ownership,Map<String,String> dependencyInputs,String outputHash){}
private final ObjectMapper json;private final AssetCatalog catalog;
AssetOwnershipGraph(ObjectMapper json,AssetCatalog catalog){this.json=json;this.catalog=catalog;}
private List<Record> records(ProjectReference project)throws Exception {
Path file=AssetWorkspaceFiles.path(project.rootPath(),AssetWorkspaceFiles.OWNERSHIP);
return Files.exists(file)?List.of(json.readValue(file.toFile(),Record[].class)):List.of();
}
AssetReference resolve(ProjectReference project,AssetReference reference) {
return catalog.list(project,false).stream().filter(a->a.reference().equals(reference)||reference.isAssetRootReference()&&project.rootPath().resolve("assets").resolve(reference.rawValue()).normalize().equals(a.root())).findFirst().orElseThrow(()->new IllegalArgumentException("Unknown ownership bank: "+reference.value())).reference();
}
private Map<String,String> inputs(ProjectReference project,List<AssetReference> references)throws Exception {
var banks=catalog.list(project,false);var revisions=AssetWorkspaceFiles.inputs(project.rootPath());var result=new TreeMap<String,String>();
for(var reference:references) {
var bank=banks.stream().filter(a->a.reference().equals(reference)).findFirst().orElseThrow(()->new IllegalArgumentException("Unknown ownership dependency: "+reference.value()));
String prefix=project.rootPath().relativize(bank.root())+"/";
revisions.forEach((path,hash)->{if(path.startsWith(prefix))result.put(path,hash);});
}return result;
}
List<Ownership> list(ProjectReference project)throws Exception {
var result=new ArrayList<Ownership>();for(var record:records(project)) {
var value=record.ownership();Path output=AssetWorkspaceFiles.path(project.rootPath(),value.outputPath());
boolean missingDependency=false;Map<String,String> current;try{current=inputs(project,value.dependencies());}catch(IllegalArgumentException missing){missingDependency=true;current=Map.of();}
boolean stale=value.stale()||missingDependency||!record.dependencyInputs().equals(current)
||!Files.isRegularFile(output)||!Objects.equals(record.outputHash(),AssetWorkspaceFiles.hash(Files.readAllBytes(output)));
result.add(new Ownership(value.owner(),value.outputPath(),value.producer(),value.dependencies(),stale));
}return result;
}
void update(ProjectReference project,List<Ownership> declarations)throws Exception {
if(declarations.isEmpty())return;
var records=new LinkedHashMap<String,Record>();records(project).forEach(r->records.put(r.ownership().outputPath(),r));
var banks=catalog.list(project,false);
for(var requested:declarations) {
var declaration=new Ownership(resolve(project,requested.owner()),requested.outputPath(),requested.producer(),requested.dependencies().stream().map(r->resolve(project,r)).toList(),requested.stale());
Path output=AssetWorkspaceFiles.path(project.rootPath(),declaration.outputPath());
if(!Files.isRegularFile(output))throw new IllegalArgumentException("Declared generated output does not exist: "+declaration.outputPath());
var dependencies=inputs(project,declaration.dependencies());String hash=AssetWorkspaceFiles.hash(Files.readAllBytes(output));
var prior=records.get(declaration.outputPath());
if(prior!=null&&Objects.equals(prior.outputHash(),hash)&&!prior.dependencyInputs().equals(dependencies))dependencies=prior.dependencyInputs();
records.put(declaration.outputPath(),new Record(declaration,dependencies,hash));
}
AssetWorkspaceFiles.write(json,AssetWorkspaceFiles.path(project.rootPath(),AssetWorkspaceFiles.OWNERSHIP),records.values());
}
}
@@ -0,0 +1,38 @@
package p.studio.app.assets;
import p.studio.api.assets.AssetBatches.*;
import p.studio.app.evidence.PngEvidenceCodec;
import java.nio.file.*;
import java.util.*;
import java.util.concurrent.ConcurrentHashMap;
/** Exact human-selected external source grants. Agent supplied strings cannot create grants. */
final class AssetPngSources {
record Grant(Path project,Path source,AuthorizedPng value){}
private final Map<String,Grant> grants=new ConcurrentHashMap<>();
private final PngEvidenceCodec png=new PngEvidenceCodec();
AuthorizedPng authorize(Path root,Path source)throws Exception {
Path canonical=source.toRealPath();byte[] bytes=read(canonical);var pixels=png.decode(bytes);
var value=new AuthorizedPng(UUID.randomUUID().toString(),AssetWorkspaceFiles.hash(bytes),bytes.length,pixels.width(),pixels.height());
grants.put(value.grantId(),new Grant(root.toRealPath(),canonical,value));return value;
}
Path resolve(Path root,PngInput input)throws Exception {
if(input.projectRelativePath()!=null)return AssetWorkspaceFiles.path(root,input.projectRelativePath());
Grant grant=grants.get(input.externalGrantId());
if(grant==null||!grant.project().equals(root.toRealPath()))throw new IllegalArgumentException("PNG source has no matching project-bound human grant");
if(!grant.source().toRealPath().equals(grant.source()))throw new IllegalArgumentException("Selected PNG source was redirected");
return grant.source();
}
byte[] bytes(Path root,PngInput input)throws Exception {
byte[] bytes=read(resolve(root,input));png.decode(bytes);
if(!AssetWorkspaceFiles.hash(bytes).equals(input.sha256()))throw new IllegalArgumentException("PNG source bytes changed");
return bytes;
}
private static byte[] read(Path path)throws Exception {
if(!Files.isRegularFile(path)||Files.size(path)>32*1024*1024)throw new IllegalArgumentException("PNG source must be a bounded regular file");
try(var stream=Files.newInputStream(path)) {
byte[] bytes=stream.readNBytes(32*1024*1024+1);
if(bytes.length>32*1024*1024)throw new IllegalArgumentException("PNG source exceeds 32 MiB");return bytes;
}
}
}
@@ -0,0 +1,68 @@
package p.studio.app.assets;
import com.fasterxml.jackson.databind.ObjectMapper;
import p.studio.api.assets.AssetBatches.*;
import java.nio.file.*;
import java.security.MessageDigest;
import java.util.*;
/** Revision/staging over the actual project inputs, excluding derived packer caches. */
final class AssetWorkspaceFiles {
static final String OWNERSHIP=".studio/asset-ownership.json";
static final List<String> REQUIRED=List.of("prometeu.json","assets/.prometeu/index.json",OWNERSHIP);
static String hash(byte[] data) {
try{return HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(data));}
catch(java.security.NoSuchAlgorithmException impossible){throw new AssertionError(impossible);}
}
static Path path(Path root,String relative)throws Exception {
Path normalized=root.toAbsolutePath().normalize(),result=normalized.resolve(relative).normalize();
if(!result.startsWith(normalized)||result.equals(normalized))throw new IllegalArgumentException("Asset path escapes project");
Path part=normalized;for(Path element:normalized.relativize(result)){part=part.resolve(element);if(Files.isSymbolicLink(part))throw new IllegalArgumentException("Asset path contains a symbolic link: "+relative);}
return result;
}
static SortedMap<String,String> inputs(Path root)throws Exception {
var inputs=new TreeMap<String,String>();Path assets=path(root,"assets");
if(Files.exists(assets))try(var files=Files.walk(assets)) {
for(Path file:files.toList()) {
if(Files.isSymbolicLink(file))throw new IllegalArgumentException("Asset symlink is not a transactional input: "+file);
String relative=root.relativize(file).toString();
if(Files.isRegularFile(file)&&!relative.equals("assets/.prometeu/cache.json")&&!file.getFileName().toString().startsWith(".asset-publish-"))inputs.put(relative,hash(Files.readAllBytes(file)));
}
}
for(String relative:REQUIRED){Path file=path(root,relative);if(Files.isRegularFile(file))inputs.put(relative,hash(Files.readAllBytes(file)));}
return inputs;
}
static Revision revision(Path root)throws Exception {
var inputs=inputs(root);var absent=new TreeSet<String>(REQUIRED);absent.removeAll(inputs.keySet());
StringBuilder canonical=new StringBuilder("asset-revision:1\n");inputs.forEach((p,h)->canonical.append(p).append('\0').append(h).append('\n'));
absent.forEach(p->canonical.append(p).append("\0absent\n"));
return new Revision(1,hash(canonical.toString().getBytes(java.nio.charset.StandardCharsets.UTF_8)),inputs,absent);
}
static void copy(Path from,Path to)throws Exception {
Files.createDirectories(to);
for(String relative:inputs(from).keySet()){Path target=path(to,relative);Files.createDirectories(target.getParent());Files.copy(path(from,relative),target,StandardCopyOption.REPLACE_EXISTING);}
}
static List<FileChange> changes(Path before,Path after,ObjectMapper json)throws Exception {
var a=inputs(before);var b=inputs(after);var paths=new TreeSet<>(a.keySet());paths.addAll(b.keySet());var result=new ArrayList<FileChange>();
for(String relative:paths) {
String old=a.get(relative),next=b.get(relative);if(Objects.equals(old,next))continue;
if(old!=null&&next!=null&&relative.endsWith(".json")) {
var left=json.readTree(path(before,relative).toFile());var right=json.readTree(path(after,relative).toFile());
if(Objects.equals(left,right)){Files.copy(path(before,relative),path(after,relative),StandardCopyOption.REPLACE_EXISTING);continue;}
}
result.add(new FileChange(relative,old==null?FileAction.create:next==null?FileAction.delete:FileAction.replace,old,next));
}
return result;
}
static List<Conflict> conflicts(Revision expected,Revision actual) {
var paths=new TreeSet<>(expected.inputSha256().keySet());paths.addAll(actual.inputSha256().keySet());
var conflicts=new ArrayList<Conflict>();for(String p:paths)if(!Objects.equals(expected.inputSha256().get(p),actual.inputSha256().get(p)))
conflicts.add(new Conflict(p,expected.inputSha256().get(p),actual.inputSha256().get(p),"Project input changed since preview"));
if(conflicts.isEmpty()&&!expected.equals(actual))conflicts.add(new Conflict("prometeu.json",expected.inputSha256().get("prometeu.json"),actual.inputSha256().get("prometeu.json"),"Revision identity mismatch; obtain a fresh canonical project revision"));
return conflicts;
}
static void write(ObjectMapper json,Path path,Object value)throws Exception {
Files.createDirectories(path.getParent());Path temporary=Files.createTempFile(path.getParent(),".record-",".tmp");
try{Files.write(temporary,json.writeValueAsBytes(value));Files.move(temporary,path,StandardCopyOption.ATOMIC_MOVE,StandardCopyOption.REPLACE_EXISTING);}finally{Files.deleteIfExists(temporary);}
}
}
@@ -0,0 +1,156 @@
package p.studio.app.assets;
import com.fasterxml.jackson.databind.ObjectMapper;
import p.packer.PackerWorkspaceService;
import p.packer.messages.PackerProjectContext;
import p.packer.messages.PublishWorkspaceFilesRequest;
import p.studio.api.assets.*;
import p.studio.api.assets.AssetBatches.*;
import p.studio.api.automation.*;
import p.studio.api.project.ProjectReference;
import p.studio.core.assets.*;
import p.studio.core.assets.metadata.AssetStudioMetadataService;
import java.nio.file.*;
import java.util.*;
import java.util.concurrent.Callable;
import java.util.function.Function;
/** Durable request correlation over the packer's shared transactional project boundary. */
public final class FileAssetBatchWorkspace implements AssetBatchWorkspace {
record Scope(String task,String request,Request parameters){}
record Commit(String task,String request,String batch,Revision expected){}
private final ObjectMapper json;private final PackerWorkspaceService packer;
private final AssetCatalog catalog;private final AssetPngSources sources=new AssetPngSources();
private final Function<ProjectReference,AssetBudgets.Snapshot> budgets;
public FileAssetBatchWorkspace(ObjectMapper mapper,PackerWorkspaceService packer,Function<ProjectReference,AssetBudgets.Snapshot> budgets) {
this.json=AssetBatchJson.mapper(mapper);this.packer=packer;this.catalog=new PackerAssetCatalog(packer);this.budgets=budgets;
}
private PackerProjectContext context(ProjectReference p){return new PackerProjectContext(p.name(),p.rootPath());}
private <T>T exclusive(ProjectReference p,Callable<T> work){return packer.withProject(context(p),work);}
private Path home(ProjectReference p)throws Exception{return AssetWorkspaceFiles.path(p.rootPath(),".studio/asset-batches");}
private Path batch(ProjectReference p,String id)throws Exception{UUID.fromString(id);return AssetWorkspaceFiles.path(p.rootPath(),".studio/asset-batches/"+id);}
private List<Path> batches(ProjectReference p)throws Exception {
Path home=home(p);if(!Files.exists(home))return List.of();
try(var dirs=Files.list(home)){return dirs.filter(d->{if(Files.isSymbolicLink(d))throw new IllegalArgumentException("Batch directory cannot be a symbolic link");return Files.isDirectory(d);}).filter(d->d.getFileName().toString().matches("[0-9a-f-]{36}")).sorted().toList();}
}
private <T>T read(Path path,Class<T> type)throws Exception {if(Files.isSymbolicLink(path)||!Files.isRegularFile(path))throw new IllegalArgumentException("Batch record not found or unsafe");return json.readValue(path.toFile(),type);}
@Override public List<AssetSummary> catalog(ProjectReference p){return exclusive(p,()->catalog.list(p,false));}
@Override public List<ArtifactInfo> artifacts(ProjectReference p,AssetReference reference){return exclusive(p,()->{
var asset=catalog.list(p,false).stream().filter(a->a.reference().equals(reference)||reference.isAssetRootReference()&&p.rootPath().resolve("assets").resolve(reference.rawValue()).normalize().equals(a.root())).findFirst().orElseThrow(()->new IllegalArgumentException("Unknown glyph bank"));
if(asset.family()!=AssetFamily.GLYPH_BANK)throw new IllegalArgumentException("Artifact catalog requires a glyph bank");
var layout=packer.getGlyphBankLayout(new p.packer.messages.GetGlyphBankLayoutRequest(context(p),UUID.fromString(asset.assetUuid())));
return layout.glyphs().stream().map(g->new ArtifactInfo(new Artifact(asset.reference(),g.artifactId()),g.glyphId(),g.fingerprint(),g.imagePath().toString(),g.width(),g.height())).toList();
});}
@Override public Revision revision(ProjectReference p){return exclusive(p,()->AssetWorkspaceFiles.revision(p.rootPath()));}
@Override public AssetDetailsSnapshot inspect(ProjectReference p,AssetReference bank){return exclusive(p,()->new PackerAssetDetails(packer,false).get(p,bank));}
@Override public List<ArtifactInfo> previewArtifacts(ProjectReference p,String id,AssetReference bank){return exclusive(p,()->{
Path root=batch(p,id).resolve("candidate");read(batch(p,id).resolve("preview.json"),Preview.class);
return artifacts(new ProjectReference(p.name(),p.version(),p.languageId(),p.stdlibVersion(),p.target(),root,p.appId(),p.memcardSlots()),bank);
});}
@Override public List<Ownership> dependencies(ProjectReference p,AssetReference asset){return exclusive(p,()->{var graph=new AssetOwnershipGraph(json,catalog);var reference=graph.resolve(p,asset);return graph.list(p).stream().filter(o->o.owner().equals(reference)||o.dependencies().contains(reference)).toList();});}
@Override public AssetBudgets.Snapshot budget(ProjectReference p){return exclusive(p,()->budgets.apply(p));}
@Override public AuthorizedPng authorize(ProjectReference p,Path source){return exclusive(p,()->sources.authorize(p.rootPath(),source));}
@Override public Preview preview(ProjectReference p,String task,String id){return exclusive(p,()->read(batch(p,id).resolve("preview.json"),Preview.class));}
@Override public Preview preview(ProjectReference p,String task,String request,Request changes) {
return exclusive(p,()->{
for(Path directory:batches(p))if(Files.exists(directory.resolve("scope.json"))) {
var scope=read(directory.resolve("scope.json"),Scope.class);
if(Objects.equals(scope.task(),task)&&scope.request().equals(request)) {
if(!scope.parameters().equals(changes))throw conflict("Preview request parameters changed");
return read(directory.resolve("preview.json"),Preview.class);
}
}
String id=UUID.randomUUID().toString();Path directory=batch(p,id);Files.createDirectories(directory);
var actual=AssetWorkspaceFiles.revision(p.rootPath());var conflicts=AssetWorkspaceFiles.conflicts(changes.expectedRevision(),actual);
var diagnostics=new ArrayList<Diagnostic>();var affected=List.<ReferenceUse>of();var files=List.<FileChange>of();var assets=List.<AssetReference>of();var ownership=List.<Ownership>of();
PreviewState state=PreviewState.conflict;
if(conflicts.isEmpty()) {
Path stageRoot=directory.resolve("candidate");AssetWorkspaceFiles.copy(p.rootPath(),stageRoot);
var stage=new ProjectReference(p.name(),p.version(),p.languageId(),p.stdlibVersion(),p.target(),stageRoot,p.appId(),p.memcardSlots());
var stagedCatalog=new PackerAssetCatalog(packer);var stagedMetadata=new AssetStudioMetadataService(json);
var stagedCommands=new PackerAssetCommands(packer,path->{if(!path.toAbsolutePath().normalize().equals(stageRoot))throw new IllegalArgumentException("Staged asset command escaped its workspace");return ()->{};});
var edits=new AssetBatchMutations(stagedCommands,stagedCatalog,stagedMetadata,json,sources,packer);
try {
for(var mutation:changes.mutations()) {
if(Thread.currentThread().isInterrupted())throw new java.util.concurrent.CancellationException("Cancelled asset preview");
edits.apply(p,stage,mutation);
}
var references=new AssetBatchReferences(stagedCatalog,stagedMetadata,packer,json);
affected=references.apply(p,stage,changes.rebinds());
if(!affected.isEmpty())diagnostics.add(diagnostic("REFERENCE_REBIND_REQUIRED","Explicit rebind is required for affected references",affected));
var graph=new AssetOwnershipGraph(json,stagedCatalog);graph.update(stage,changes.ownership());ownership=graph.list(stage);
// Asset drafts may coexist with other unfinished banks. Cartridge validation
// still sees the original blocking producer fact for every included bank.
var candidateChanges=AssetWorkspaceFiles.changes(p.rootPath(),stageRoot,json);
var validation=packer.validatePackWorkspace(new p.packer.messages.ValidatePackWorkspaceRequest(context(stage)));
for(var asset:validation.assets())for(var diagnostic:asset.diagnostics())if(diagnostic.blocking()) {
var fact=AssetBatchDiagnostics.from(diagnostic,stageRoot,p.rootPath());
boolean changed=candidateChanges.stream().anyMatch(file->stageRoot.resolve(file.path()).startsWith(asset.assetPath()));
if(!changed||"SCENE_REQUEST_MISSING".equals(fact.code())) {
var details=new LinkedHashMap<>(fact.context());details.put("cartridgeBlocking",true);details.put("publicationScope","asset_draft");
fact=new Diagnostic(fact.producer(),fact.code(),fact.severity(),fact.message(),false,fact.assetRoot(),fact.path(),fact.family(),fact.missingIndices(),fact.duplicateIndices(),fact.references(),fact.used(),fact.required(),fact.limit(),details);
}
diagnostics.add(fact);
}
}catch(java.util.concurrent.CancellationException stop){throw stop;}
catch(Exception invalid){diagnostics.add(diagnostic("ASSET_MUTATION_REJECTED",Objects.requireNonNullElse(invalid.getMessage(),invalid.getClass().getSimpleName()),List.of()));}
files=AssetWorkspaceFiles.changes(p.rootPath(),stageRoot,json);
var changedFiles=files;
assets=stagedCatalog.list(stage,false).stream().filter(asset->changedFiles.stream().anyMatch(file->stageRoot.resolve(file.path()).startsWith(asset.root()))).map(AssetSummary::reference).toList();
conflicts=AssetWorkspaceFiles.conflicts(actual,AssetWorkspaceFiles.revision(p.rootPath()));
state=!conflicts.isEmpty()?PreviewState.conflict:diagnostics.stream().anyMatch(Diagnostic::blocking)?PreviewState.rejected:files.isEmpty()?PreviewState.no_op:PreviewState.ready;
}
var preview=new Preview(id,request,changes.expectedRevision(),changes,state,files,assets,affected,ownership,conflicts,diagnostics);
AssetWorkspaceFiles.write(json,directory.resolve("preview.json"),preview);
AssetWorkspaceFiles.write(json,directory.resolve("scope.json"),new Scope(task,request,changes));return preview;
});
}
@Override public Result commit(ProjectReference p,String task,String request,String id,Revision expected) {
return exclusive(p,()->{
Commit parameters=new Commit(task,request,id,expected);
for(Path directory:batches(p))if(Files.exists(directory.resolve("commit-request.json"))) {
var prior=read(directory.resolve("commit-request.json"),Commit.class);
if(Objects.equals(prior.task(),task)&&prior.request().equals(request)) {
if(!prior.equals(parameters))throw conflict("Commit request parameters changed");
if(Files.exists(directory.resolve("result.json")))return resultInLane(p,directory.getFileName().toString());
}
}
Path directory=batch(p,id);var scope=read(directory.resolve("scope.json"),Scope.class);
if(!Objects.equals(scope.task(),task))throw new IllegalArgumentException("Commit requires the preview's current task authority");
var preview=read(directory.resolve("preview.json"),Preview.class);
if(Files.exists(directory.resolve("result.json")))throw conflict("Batch already has a different commit request");
if(!expected.equals(preview.revision()))throw conflict("Commit revision does not match the reviewed preview");
AssetWorkspaceFiles.write(json,directory.resolve("commit-request.json"),parameters);
var before=AssetWorkspaceFiles.revision(p.rootPath());var conflicts=AssetWorkspaceFiles.conflicts(expected,before);
var diagnostics=new ArrayList<>(preview.diagnostics());
try{for(var mutation:preview.request().mutations())if(mutation instanceof ImportPng png)sources.bytes(p.rootPath(),png.source());}
catch(Exception changed){diagnostics.add(diagnostic("PNG_SOURCE_CHANGED",Objects.requireNonNullElse(changed.getMessage(),"Source no longer authorized"),List.of()));}
CommitState state=!conflicts.isEmpty()?CommitState.conflict:!preview.canCommit()||diagnostics.stream().anyMatch(Diagnostic::blocking)?CommitState.rejected:preview.files().isEmpty()?CommitState.no_op:CommitState.committed;
if(Thread.currentThread().isInterrupted())state=CommitState.cancelled;
if(state!=CommitState.committed) {
var result=new Result(id,request,state,before,before,List.of(),preview.assets(),conflicts,diagnostics);
boolean stop=Thread.interrupted();try{AssetWorkspaceFiles.write(json,directory.resolve("result.json"),result);}finally{if(stop)Thread.currentThread().interrupt();}return result;
}
Path candidate=directory.resolve("candidate");
var current=AssetWorkspaceFiles.inputs(candidate);
var reviewed=new java.util.TreeMap<>(expected.inputSha256());
for(var file:preview.files())if(file.afterSha256()==null)reviewed.remove(file.path());else reviewed.put(file.path(),file.afterSha256());
if(!reviewed.equals(current))throw new IllegalStateException("Staged candidate differs from the reviewed file set");
for(var file:preview.files())if(!Objects.equals(current.get(file.path()),file.afterSha256()))throw new IllegalStateException("Staged candidate was modified after preview");
var after=AssetWorkspaceFiles.revision(candidate);var result=new Result(id,request,state,before,after,preview.files(),preview.assets(),List.of(),diagnostics);
var publication=new ArrayList<PublishWorkspaceFilesRequest.Edit>();
for(var file:preview.files())publication.add(new PublishWorkspaceFilesRequest.Edit(file.path(),file.beforeSha256(),file.afterSha256()==null?null:Files.readAllBytes(AssetWorkspaceFiles.path(candidate,file.path()))));
publication.add(new PublishWorkspaceFilesRequest.Edit(p.rootPath().relativize(directory.resolve("result.json")).toString(),null,json.writeValueAsBytes(result)));
packer.publishWorkspaceFiles(new PublishWorkspaceFilesRequest(context(p),id,publication));return result;
});
}
@Override public Result result(ProjectReference p,String task,String id){return exclusive(p,()->resultInLane(p,id));}
private Result resultInLane(ProjectReference p,String id)throws Exception {
var result=read(batch(p,id).resolve("result.json"),Result.class);
if(result.applied()&&Files.exists(AssetWorkspaceFiles.path(p.rootPath(),".studio/asset-transactions/"+id+"/recovered")))
return new Result(result.batchId(),result.requestId(),CommitState.recovered,result.before(),result.after(),result.files(),result.assets(),result.conflicts(),result.diagnostics());
return result;
}
private static AutomationException conflict(String message){return new AutomationException(AutomationFailure.Code.CLIENT_REQUEST_CONFLICT,message);}
private static Diagnostic diagnostic(String code,String message,List<ReferenceUse> references){return new Diagnostic("studio",code,"ERROR",message,true,null,null,null,List.of(),List.of(),references,null,null,null,Map.of());}
}
@@ -0,0 +1,67 @@
package p.studio.app.assets;
import com.fasterxml.jackson.databind.*;
import p.studio.api.assets.AssetBudgets;
import p.studio.api.automation.*;
import p.studio.api.project.ProjectLocalStudioSetup;
import java.nio.*;
import java.nio.channels.FileChannel;
import java.nio.file.*;
import java.util.*;
/** Same admission for headless and desktop: verify qualification, actual cartridge bytes and serialized preload. */
public final class ManagedAssetGuard {
private final ObjectMapper json;private final AssetCapacityProfiles profiles;
public ManagedAssetGuard(ObjectMapper json){this.json=json;profiles=new AssetCapacityProfiles(json);}
public Map<String,Object> require(Path project,Path cartridge,ProjectLocalStudioSetup setup)throws Exception {
var selected=profiles.select(setup);
if(selected.state()!=AssetBudgets.QualificationState.known)throw failure("ASSET_PROFILE_UNKNOWN",selected.reason());
Path root=cartridge.toRealPath();if(!root.startsWith(project.toRealPath()))throw failure("BUILD_OUTSIDE_PROJECT","Cartridge is outside its project");
Path file=AssetWorkspaceFiles.path(root,"asset-capacity.json");
if(!Files.isRegularFile(file)||Files.size(file)>32*1024*1024)throw failure("ASSET_BUILD_UNQUALIFIED","Rebuild with a compatible selected runtime before managed execution");
var record=json.readTree(file.toFile());var qualification=record.path("snapshot").path("qualification");var profile=qualification.path("profile");
if(record.path("contractVersion").asInt()!=1||!qualification.path("state").asText().equals("known")
||!profile.path("profileId").asText().equals(selected.profile().profileId())
||!profile.path("executableSha256").asText().equals(selected.selectedExecutableSha256()))
throw failure("ASSET_BUILD_PROFILE_CHANGED","Build capacity qualification does not match the selected runtime; rebuild required");
if (!profile.equals(json.valueToTree(selected.profile())))
throw failure("ASSET_BUILD_PROFILE_CHANGED", "Build capacity evidence changed; rebuild required");
if(!record.path("snapshot").path("revision").equals(json.valueToTree(AssetWorkspaceFiles.revision(project))))
throw failure("ASSET_BUILD_INPUTS_CHANGED", "Asset inputs changed since qualification; rebuild required");
var hashes=record.path("files");
for(String name:List.of("manifest.json","program.pbx","assets.pa","asset_table.json","preload.json")) {
Path input=AssetWorkspaceFiles.path(root,name);
if(!Files.isRegularFile(input)||!AssetWorkspaceFiles.hash(Files.readAllBytes(input)).equals(hashes.path(name).asText()))
throw failure("ASSET_BUILD_BYTES_CHANGED","Qualified cartridge bytes changed: "+name);
}
JsonNode packed=header(root.resolve("assets.pa"));var banks=new HashMap<Integer,String>();
for(var bank:packed.path("asset_table")) {
int id=integer(bank.path("asset_id"));String type=bank.path("bank_type").asText();
if(banks.put(id,type)!=null)throw failure("ASSET_TOPOLOGY_INVALID","Duplicate cold AssetId");
}
var claimed=new HashSet<String>();var required=new TreeMap<String,Integer>();
for(var preload:packed.path("preload")) {
int id=integer(preload.path("asset_id")),slot=integer(preload.path("slot"));String type=banks.get(id);
if(type==null||!claimed.add(type+":"+slot))throw failure("ASSET_TOPOLOGY_INVALID","Unknown preload bank or duplicate runtime slot");
Integer limit=null;for(var entry:selected.profile().limits().entrySet())if(entry.getKey().runtimeTag().equals(type))limit=entry.getValue();
if(limit==null||slot>=limit)throw new AutomationException(new AutomationFailure(AutomationFailure.Code.LIMIT_EXCEEDED,"Managed preload is outside the qualified capacity",Map.of(),
p.studio.api.values.ValueMaps.fields("code","PRELOAD_CAPACITY_EXCEEDED","bankType",type,"slot",slot,"assetId",id,"limit",limit,"profileId",selected.profile().profileId())));
required.merge(type,slot+1,Math::max);
}
return Map.of("profileId",selected.profile().profileId(),"selectedExecutableSha256",selected.selectedExecutableSha256(),"requiredSlots",required,"inputRevision",record.path("snapshot").path("revision").path("sha256").asText());
}
private JsonNode header(Path path)throws Exception {
try(var file=FileChannel.open(path,StandardOpenOption.READ)) {
var prelude=ByteBuffer.allocate(32).order(ByteOrder.LITTLE_ENDIAN);read(file,prelude);prelude.flip();
if(prelude.get()!='A'||prelude.get()!='S'||prelude.get()!='P'||prelude.get()!='A'||prelude.getInt()!=1)throw failure("ASSET_HEADER_INVALID","Unsupported packed asset header");
int size=prelude.getInt();long payload=prelude.getLong();
if(size<2||size>32*1024*1024||payload!=32L+size||payload>file.size())throw failure("ASSET_HEADER_INVALID","Invalid packed asset header bounds");
var bytes=ByteBuffer.allocate(size);read(file,bytes);var header=json.readTree(bytes.array());
if(!header.path("asset_table").isArray()||!header.path("preload").isArray())throw failure("ASSET_HEADER_INVALID","Expected asset table and preload arrays");
return header;
}
}
private static void read(FileChannel source,ByteBuffer target)throws Exception{while(target.hasRemaining())if(source.read(target)<0)throw new java.io.EOFException("Truncated assets.pa header");}
private static int integer(JsonNode node){if(!node.isIntegralNumber()||!node.canConvertToInt()||node.intValue()<0)throw failure("ASSET_TOPOLOGY_INVALID","Expected a nonnegative lossless cold ID or slot");return node.intValue();}
private static AutomationException failure(String code,String message){return new AutomationException(new AutomationFailure(AutomationFailure.Code.RUNTIME_INCOMPATIBLE,message,Map.of(),Map.of("code",code)));}
}
@@ -24,7 +24,12 @@ public final class CompilerBuildGatewayAdapter implements CompilerBuildGateway {
public CompilerBuildGatewayAdapter(p.animation.GlyphBankLayoutSource layouts){this.layouts=layouts;}
@Override
public CompilerBuildOutput compile(ProjectReference project, Consumer<String> logSink) {
final var config = new BuilderPipelineConfig(false, project.rootPath().toString());
return compile(project, p.studio.api.automation.BuildSelection.productionBuild(), project.rootPath().resolve("build"), logSink);
}
@Override public CompilerBuildOutput compile(ProjectReference project, p.studio.api.automation.BuildSelection selection,
java.nio.file.Path outputDirectory, Consumer<String> logSink) {
final var config = new BuilderPipelineConfig(false, project.rootPath().toString(), "core-v1",
p.studio.compiler.utilities.SourceProviderFactory.filesystem(), selection.targetId(), outputDirectory);
var context=BuilderPipelineContext.fromConfig(config);context.glyphBankLayoutSource=layouts;
var analysisId = UUID.randomUUID().toString();
try {
@@ -53,14 +58,24 @@ public final class CompilerBuildGatewayAdapter implements CompilerBuildGateway {
private Map<String, Object> inputContext(BuilderPipelineContext context, java.nio.file.Path root, String analysisId,
Map<Integer, SourceReference> sources) {
var workspace = context.resolvedWorkspace;
return ImmutableJson.fields("projectRoot", root.toString(), "analysisId", analysisId,
var sourceHashes = new java.util.TreeMap<String, String>();
var diskHashes = new java.util.TreeMap<String, String>();
var configurationHashes = new java.util.TreeMap<String, String>();
if (workspace != null) for (var descriptor : workspace.graph().projectTable().values())
if (descriptor.getManifestSha256() != null) configurationHashes.put(descriptor.getRootPath().resolve("prometeu.json").toString(), descriptor.getManifestSha256());
sources.values().forEach(source -> { if (source.sha256() != null && !source.mixedRevisions()) sourceHashes.put(source.canonicalPath(), source.sha256()); });
sourceHashes.forEach((path, hash) -> { if (java.nio.file.Files.isRegularFile(java.nio.file.Path.of(path))) diskHashes.put(path, hash); });
var limitations = new java.util.ArrayList<Map<String, Object>>();
limitations.add(ImmutableJson.fields("code", "PACK_INPUT_REVISIONS_NOT_CAPTURED", "message", "Compiler source revisions do not identify all pack/assets inputs"));
if (configurationHashes.isEmpty()) limitations.add(ImmutableJson.fields("code", "CONFIGURATION_REVISION_NOT_RECORDED", "message", "Configuration values are recorded without a manifest-byte revision"));
return ImmutableJson.fields("projectRoot", root.toString(), "analysisId", analysisId, "targetId", context.config.buildTargetId(),
"sourceSha256", sourceHashes, "diskSourceSha256", diskHashes, "configurationSha256", configurationHashes,
"entrypoint", workspace == null || workspace.mainProject().getEntrypoint() == null ? null : workspace.mainProject().getEntrypoint().toString(),
"taskId", null, "operationId", null, "clientRequestId", null, "buildId", null, "queryId", null, "document", null,
"inputs", CompilerDiagnosticProjection.inputs(sources, root), "inputCoverage", "compiler-inputs",
"configuration", ImmutableJson.fields("languageId", workspace == null || workspace.frontendSpec() == null ? null : workspace.frontendSpec().getLanguageId(),
"sdkVersion", workspace == null ? null : workspace.stdlib(), "target", workspace == null ? null : workspace.target().name(),
"vmProfile", context.config.vmProfile(), "revisionAvailability", "not-recorded"),
"coverage", "partial", "limitations", java.util.List.of(ImmutableJson.fields("code", "PACK_INPUT_REVISIONS_NOT_CAPTURED",
"message", "Compiler source revisions do not identify all pack/assets inputs"),
ImmutableJson.fields("code", "CONFIGURATION_REVISION_NOT_RECORDED", "message", "Configuration values are recorded without a manifest-byte revision")));
"vmProfile", context.config.vmProfile(), "revisionAvailability", configurationHashes.isEmpty() ? "not-recorded" : "recorded"),
"coverage", "partial", "limitations", limitations);
}
}
@@ -165,8 +165,11 @@ public final class CompilerProjectKnowledge implements ProjectKnowledge {
return new Reference(ref.id(), ref.title(), owned.owner(), ReferenceKind.valueOf(ref.kind().name()),
new Version(ref.version(), ref.versionSource()));
}).toList();
var automation = openProjects.findAutomation(root).map(p.studio.api.automation.AutomationSession::snapshot).orElse(null);
if (automation == null) limitations.add("Automation state is unavailable in this project context");
return new Discovery(new Context(root, discovered.get(root).name(), languages, libraries,
List.of(root), List.copyOf(readOnly), descriptors, limitations.stream().distinct().toList()), Map.copyOf(references));
List.of(root), List.copyOf(readOnly), descriptors, limitations.stream().distinct().toList(),
automation == null ? null : automation.controlObservation(), automation == null ? null : automation.runtimeObservation()), Map.copyOf(references));
}
private Language language(String id, List<ProjectReference> projects, boolean primary,
@@ -0,0 +1,177 @@
package p.studio.app.evidence;
import com.fasterxml.jackson.databind.ObjectMapper;
import p.studio.api.automation.*;
import java.nio.file.*;
import java.nio.channels.FileChannel;
import java.io.IOException;
import java.security.MessageDigest;
import java.util.*;
import java.util.concurrent.ConcurrentHashMap;
import java.util.function.Supplier;
/** Immutable transaction directories; the atomic directory move is the only publication point. */
public final class FileEvidenceStore implements EvidenceStore {
private static final Map<Path,Object> MONITORS=new ConcurrentHashMap<>();
private record Grant(Path project,Path source) {}
private final Map<String,Grant> grants=new ConcurrentHashMap<>();
private final ObjectMapper mapper;
private final long quota;
public FileEvidenceStore(ObjectMapper mapper) {this(mapper,Long.getLong("prometeu.evidence.quotaBytes",Evidence.DEFAULT_QUOTA));}
public FileEvidenceStore(ObjectMapper mapper,long quota) {
if(quota<0)throw new IllegalArgumentException("Negative evidence quota");this.mapper=mapper;this.quota=quota;
}
public static String sha(byte[] bytes) {
try {return HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(bytes));}
catch(java.security.NoSuchAlgorithmException e){throw new IllegalStateException(e);}
}
private Path directory(Path root) throws IOException {
Path canonical=root.toRealPath();Path studio=canonical.resolve(".studio");
Files.createDirectories(studio);
if(Files.isSymbolicLink(studio)||!studio.toRealPath().startsWith(canonical))throw denied("Studio state path escapes project");
Path evidence=studio.resolve("evidence");Files.createDirectories(evidence);
if(Files.isSymbolicLink(evidence)||!evidence.toRealPath().startsWith(canonical))throw denied("Evidence path escapes project");
return evidence;
}
private <T>T locked(Path root,Work<T> work) {
try {
Path dir=directory(root);
synchronized(MONITORS.computeIfAbsent(dir,k->new Object())) {
Path lock=dir.resolve("store.lock");
if(Files.isSymbolicLink(lock))throw denied("Invalid evidence lock");
try(var channel=FileChannel.open(lock,StandardOpenOption.CREATE,StandardOpenOption.WRITE);var held=channel.lock()) {
try(var entries=Files.list(dir)) {
for(var stage:entries.filter(p->p.getFileName().toString().startsWith("staging-")).toList()) {
if(Files.isSymbolicLink(stage)||!Files.isDirectory(stage))throw denied("Invalid evidence staging");
removeStage(stage);
}
}
return work.run(dir);
}
}
} catch(IOException e){throw storage("Evidence storage unavailable",e);}
}
@FunctionalInterface private interface Work<T>{T run(Path directory)throws IOException;}
public List<Evidence.Publication> list(Path root) {return locked(root,dir->scan(root,dir));}
private List<Evidence.Publication> scan(Path root,Path dir)throws IOException {
var result=new ArrayList<Evidence.Publication>();
try(var entries=Files.list(dir)) {
for(Path p:entries.filter(f->f.getFileName().toString().startsWith("pub-")).sorted().toList()) {
if(Files.isSymbolicLink(p)||!Files.isDirectory(p))throw denied("Invalid evidence publication");
var publication=mapper.readValue(boundedFile(p.resolve("publication.json"),4*1024*1024),Evidence.Publication.class);
if(!publication.projectRoot().equals(root.toRealPath().toString())||!p.getFileName().toString().equals("pub-"+id(publication.id())))
throw denied("Publication belongs to another project");
result.add(publication);
}
}
return List.copyOf(result);
}
public Evidence.Publication publish(Path root,Evidence.Publication publication,List<Evidence.Blob> objects) {
return locked(root,dir->{
var all=scan(root,dir);
for(var prior:all)if(prior.requestId().equals(publication.requestId())) {
if(!prior.parameterKey().equals(publication.parameterKey()))throw new AutomationException(AutomationFailure.Code.CLIENT_REQUEST_CONFLICT,"Evidence request parameters changed");
return prior;
}
if(!publication.projectRoot().equals(root.toRealPath().toString()))throw denied("Wrong evidence project");
byte[] metadata=mapper.writeValueAsBytes(publication);long required=metadata.length;
if(publication.artifacts().size()!=objects.size())throw new IllegalArgumentException("Incomplete publication");
var ids=new HashSet<String>();
for(var object:objects) {
var artifact=object.artifact();var bytes=object.bytes();id(artifact.id());
if(!ids.add(artifact.id())||!artifact.publicationId().equals(publication.id())||!publication.artifacts().contains(artifact)
||artifact.byteSize()!=bytes.length||!artifact.sha256().equals(sha(bytes)))throw new IllegalArgumentException("Invalid evidence object");
required=Math.addExact(required,bytes.length);
}
validateReferences(publication,all);
long used=0;
for(var p:all) {
used=Math.addExact(used,Files.size(dir.resolve("pub-"+p.id()).resolve("publication.json")));
for(var a:p.artifacts())used=Math.addExact(used,a.byteSize());
}
if(required>quota-used)throw new AutomationException(new AutomationFailure(AutomationFailure.Code.LIMIT_EXCEEDED,
"Evidence quota exceeded",Map.of(),Map.of("used",used,"required",required,"limit",quota)));
Path stage=Files.createTempDirectory(dir,"staging-");
try {
for(var object:objects)writeDurable(stage.resolve(id(object.artifact().id())+".png"),object.bytes());
writeDurable(stage.resolve("publication.json"),metadata);
if(Thread.currentThread().isInterrupted())throw new java.util.concurrent.CancellationException("Evidence publication cancelled");
Files.move(stage,dir.resolve("pub-"+id(publication.id())),StandardCopyOption.ATOMIC_MOVE);
return publication;
} finally {if(Files.exists(stage))removeStage(stage);}
});
}
private void validateReferences(Evidence.Publication p,List<Evidence.Publication> all) {
var artifacts=new HashSet<String>();all.forEach(v->v.artifacts().forEach(a->artifacts.add(a.id())));p.artifacts().forEach(a->artifacts.add(a.id()));
if(p.report()!=null&&(!artifacts.contains(p.report().expectedId())||!artifacts.contains(p.report().actualId())||!artifacts.contains(p.report().diffId())))throw missing();
if(p.baseline()!=null) {
if(!artifacts.contains(p.baseline().artifactId()))throw missing();
// Creation timestamps, not UUID directory ordering, define revision order.
String current=all.stream().filter(v->v.baseline()!=null).max(Comparator.comparing(Evidence.Publication::createdAt)).map(v->v.baseline().id()).orElse(null);
if(!Objects.equals(current,p.baseline().previousRevision()))throw new AutomationException(AutomationFailure.Code.CLIENT_REQUEST_CONFLICT,"Baseline revision changed");
}
}
private record Located(Evidence.Artifact artifact,Path file){}
private Located locate(Path root,Path dir,String artifactId)throws IOException {
id(artifactId);
for(var p:scan(root,dir))for(var a:p.artifacts())if(a.id().equals(artifactId))return new Located(a,dir.resolve("pub-"+id(p.id())).resolve(artifactId+".png"));
throw missing();
}
public Evidence.Read read(Path root,String artifactId,long offset,int length) {
if(offset<0||length<0||length>Evidence.MAX_READ)throw new IllegalArgumentException("Invalid bounded evidence range");
return locked(root,dir->{
var item=locate(root,dir,artifactId);byte[] bytes=verified(item);
if(offset>bytes.length||length>bytes.length-offset)throw new IllegalArgumentException("Evidence range exceeds object");
return new Evidence.Read(artifactId,offset,bytes.length,Arrays.copyOfRange(bytes,(int)offset,(int)offset+length));
});
}
public byte[] image(Path root,String artifactId) {return locked(root,dir->verified(locate(root,dir,artifactId)));}
private byte[] verified(Located item)throws IOException {
byte[] bytes=boundedFile(item.file,32*1024*1024);
if(bytes.length!=item.artifact.byteSize()||!sha(bytes).equals(item.artifact.sha256()))throw storage("Evidence integrity check failed",null);
return bytes;
}
public Evidence.ImportedReference importReference(Path root,Path source,String humanGrant) {
try {
Path canonical=source.toRealPath();
boolean authorized=new Grant(root.toRealPath(),canonical).equals(grants.get(humanGrant==null?"":humanGrant));
if(!canonical.startsWith(root.toRealPath())&&!authorized)throw denied("Reference requires project scope or explicit human selection");
return new Evidence.ImportedReference(boundedFile(canonical,32*1024*1024),canonical.toString(),authorized);
}catch(IOException e){throw storage("Reference unavailable",e);}
}
public String authorizeReference(Path root,Path source) {
try {String grant=UUID.randomUUID().toString();grants.put(grant,new Grant(root.toRealPath(),source.toRealPath()));return grant;}
catch(IOException e){throw storage("Reference unavailable",e);}
}
public void delete(Path root,String publicationId) {
locked(root,dir->{
id(publicationId);var all=scan(root,dir);var target=all.stream().filter(p->p.id().equals(publicationId)).findFirst().orElseThrow(FileEvidenceStore::missing);
var ids=new HashSet<String>();target.artifacts().forEach(a->ids.add(a.id()));
for(var p:all)if(!p.id().equals(publicationId)) {
boolean referenced=p.report()!=null&&(ids.contains(p.report().expectedId())||ids.contains(p.report().actualId())||ids.contains(p.report().diffId()));
referenced|=p.baseline()!=null&&(ids.contains(p.baseline().artifactId())||target.baseline()!=null&&Objects.equals(p.baseline().previousRevision(),target.baseline().id()));
if(referenced)throw new AutomationException(AutomationFailure.Code.BUSY,"Evidence is referenced by a report or baseline");
}
Path targetDir=dir.resolve("pub-"+publicationId);Path trash=dir.resolve("staging-delete-"+UUID.randomUUID());
Files.move(targetDir,trash,StandardCopyOption.ATOMIC_MOVE);removeStage(trash);return null;
});
}
private static byte[] boundedFile(Path path,int max)throws IOException {
if(Files.isSymbolicLink(path)||!Files.isRegularFile(path)||Files.size(path)>max)throw denied("Invalid or oversized evidence file");
try(var in=Files.newInputStream(path)) {byte[] bytes=in.readNBytes(max+1);if(bytes.length>max)throw denied("Evidence file exceeds bound");return bytes;}
}
private static void writeDurable(Path path,byte[] bytes)throws IOException {
try(var ch=FileChannel.open(path,StandardOpenOption.CREATE_NEW,StandardOpenOption.WRITE)) {
var buffer=java.nio.ByteBuffer.wrap(bytes);while(buffer.hasRemaining())ch.write(buffer);ch.force(true);
}
}
private static void removeStage(Path stage)throws IOException {
try(var entries=Files.list(stage)){for(var p:entries.toList())Files.delete(p);}Files.delete(stage);
}
private static String id(String value) {
if(value==null||!value.matches("[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"))throw new IllegalArgumentException("Invalid opaque evidence ID");return value;
}
private static AutomationException missing(){return new AutomationException(AutomationFailure.Code.REFERENCE_NOT_FOUND,"Evidence not found in this project");}
private static AutomationException denied(String message){return new AutomationException(AutomationFailure.Code.OUTSIDE_PROJECT_SCOPE,message);}
private static AutomationException storage(String message,Throwable cause){return new AutomationException(AutomationFailure.Code.INFRASTRUCTURE_FAILURE,message);}
}
@@ -0,0 +1,57 @@
package p.studio.app.evidence;
import p.studio.api.automation.*;
import javax.imageio.ImageIO;
import java.awt.image.BufferedImage;
import java.io.*;
/** PNG sample expansion only: no resize, gamma, perceptual or color-profile transform. */
public final class PngEvidenceCodec implements EvidenceStore.Codec {
public Evidence.Pixels decode(byte[] png) {
try {
if (png.length < 33 || png.length > 32*1024*1024 || png[0]!=(byte)137 || png[1]!=80 || png[2]!=78 || png[3]!=71)
throw new IllegalArgumentException("Expected bounded PNG bytes");
int depth=Byte.toUnsignedInt(png[24]),type=Byte.toUnsignedInt(png[25]);
if (depth!=8 && !(type==3 && (depth==1||depth==2||depth==4)))
throw new IllegalArgumentException("PNG must expand losslessly to RGBA8");
try (var in=ImageIO.createImageInputStream(new ByteArrayInputStream(png))) {
var readers=ImageIO.getImageReaders(in);
if (!readers.hasNext()) throw new IllegalArgumentException("Unsupported PNG");
var reader=readers.next();
try {
reader.setInput(in,true,true);
int w=reader.getWidth(0),h=reader.getHeight(0);
if (w<=0||h<=0||(long)w*h>16_777_216) throw new IllegalArgumentException("Image exceeds pixel bound");
var image=reader.read(0);var raster=image.getRaster();var model=image.getColorModel();
var rgba=new byte[Math.multiplyExact(Math.multiplyExact(w,h),4)];
for(int y=0;y<h;y++)for(int x=0;x<w;x++) {
int at=(y*w+x)*4;
if(type==3) {
int argb=model.getRGB(raster.getDataElements(x,y,null));
rgba[at]=(byte)(argb>>>16);rgba[at+1]=(byte)(argb>>>8);rgba[at+2]=(byte)argb;rgba[at+3]=(byte)(argb>>>24);
} else {
boolean gray=type==0||type==4;
rgba[at]=(byte)raster.getSample(x,y,0);
rgba[at+1]=(byte)raster.getSample(x,y,gray?0:1);
rgba[at+2]=(byte)raster.getSample(x,y,gray?0:2);
rgba[at+3]=(byte)(model.hasAlpha()?raster.getSample(x,y,raster.getNumBands()-1):255);
}
}
return new Evidence.Pixels(w,h,rgba);
} finally {reader.dispose();}
}
} catch (IOException e) {throw new IllegalArgumentException("PNG decode failed",e);}
}
public byte[] encode(Evidence.Pixels pixels) {
try {
var image=new BufferedImage(pixels.width(),pixels.height(),BufferedImage.TYPE_INT_ARGB);
var rgba=pixels.rgba();
for(int y=0;y<pixels.height();y++)for(int x=0;x<pixels.width();x++) {
int at=(y*pixels.width()+x)*4;
int argb=Byte.toUnsignedInt(rgba[at+3])<<24|Byte.toUnsignedInt(rgba[at])<<16|Byte.toUnsignedInt(rgba[at+1])<<8|Byte.toUnsignedInt(rgba[at+2]);
image.setRGB(x,y,argb);
}
var out=new ByteArrayOutputStream();ImageIO.write(image,"png",out);return out.toByteArray();
} catch(IOException e) {throw new IllegalStateException("PNG encode failed",e);}
}
}
@@ -16,6 +16,10 @@ final class ContractSchema {
}
if (schema.has("not") && matches(schema.get("not"), value)) fail();
if (schema.has("const") && !schema.get("const").equals(value)) fail();
if (schema.has("enum")) {
boolean found=false;for(var option:schema.get("enum"))if(option.equals(value))found=true;
if(!found)fail();
}
if (schema.has("type")) {
boolean valid = switch (schema.get("type").asText()) {
case "null" -> value.isNull();
@@ -23,6 +27,7 @@ final class ContractSchema {
case "array" -> value.isArray();
case "string" -> value.isTextual();
case "integer" -> value.isIntegralNumber() && value.canConvertToLong();
case "number" -> value.isNumber() && Double.isFinite(value.doubleValue());
case "boolean" -> value.isBoolean();
default -> throw new IllegalStateException("Unsupported packaged schema type");
};
@@ -30,9 +35,11 @@ final class ContractSchema {
}
if(schema.has("pattern")&&!value.textValue().matches(schema.get("pattern").textValue()))fail();
if(schema.has("minItems")&&value.size()<schema.get("minItems").intValue())fail();
if(schema.has("maxItems")&&value.size()>schema.get("maxItems").intValue())fail();
if(schema.path("uniqueItems").asBoolean(false)) {var items=new HashSet<JsonNode>();for(var item:value)if(!items.add(item))fail();}
if (schema.has("minLength") && value.textValue().codePointCount(0, value.textValue().length()) < schema.get("minLength").intValue()) fail();
if (schema.has("minimum") && value.longValue() < schema.get("minimum").longValue()) fail();
if (schema.has("maximum") && value.longValue() > schema.get("maximum").longValue()) fail();
if (schema.has("minimum") && value.decimalValue().compareTo(schema.get("minimum").decimalValue()) < 0) fail();
if (schema.has("maximum") && value.decimalValue().compareTo(schema.get("maximum").decimalValue()) > 0) fail();
if (schema.has("required")) for (var key : schema.get("required")) if (!value.has(key.asText())) fail();
if (schema.has("properties")) {
var allowed = new HashSet<String>();
@@ -0,0 +1,36 @@
package p.studio.app.mcp;
import com.fasterxml.jackson.databind.*;
import com.fasterxml.jackson.databind.node.ObjectNode;
import p.studio.api.assets.*;
import p.studio.app.assets.AssetBatchJson;
import java.nio.file.Path;
import java.util.*;
import java.util.function.Function;
/** Thin current-task transport; no file mutation, packer validation or budget counting here. */
public final class McpAssetAuthoringTools {
private McpAssetAuthoringTools(){}
public static Map<String,Function<JsonNode,McpToolResult>> handlers(AssetAuthoringService service,ObjectMapper original) {
ObjectMapper json=AssetBatchJson.mapper(original);var handlers=new LinkedHashMap<String,Function<JsonNode,McpToolResult>>();
handlers.put("studio_assets_catalog",a->{
var assets=service.catalog(root(a),task(a));int offset=a.path("offset").asInt(0),limit=a.path("limit").asInt(128);
if(offset<0||offset>assets.size()||limit<1||limit>1024)throw new IllegalArgumentException("Invalid bounded catalog page");
int end=Math.min(assets.size(),offset+limit);return ok(json,Map.of("assets",assets.subList(offset,end),"offset",offset,"total",assets.size(),"hasMore",end<assets.size()));
});
handlers.put("studio_assets_revision",a->ok(json,Map.of("revision",service.revision(root(a),task(a)))));
handlers.put("studio_assets_artifacts",a->ok(json,Map.of("artifacts",a.hasNonNull("batchId")?service.previewArtifacts(root(a),task(a),a.path("batchId").asText(),AssetReference.of(a.path("assetReference").asText())):service.artifacts(root(a),task(a),AssetReference.of(a.path("assetReference").asText())))));
handlers.put("studio_assets_inspect",a->ok(json,Map.of("details",service.inspect(root(a),task(a),AssetReference.of(a.path("assetReference").asText())))));
handlers.put("studio_assets_dependencies",a->ok(json,Map.of("ownership",service.dependencies(root(a),task(a),AssetReference.of(a.path("assetReference").asText())))));
handlers.put("studio_assets_budget",a->ok(json,service.budget(root(a),task(a))));
handlers.put("studio_assets_preview",a->ok(json,service.preview(root(a),task(a),a.path("clientRequestId").asText(),decode(json,a.path("request"),AssetBatches.Request.class))));
handlers.put("studio_assets_preview_get",a->ok(json,service.preview(root(a),task(a),a.path("batchId").asText())));
handlers.put("studio_assets_commit",a->ok(json,service.commit(root(a),task(a),a.path("clientRequestId").asText(),a.path("batchId").asText(),decode(json,a.path("expectedRevision"),AssetBatches.Revision.class))));
handlers.put("studio_assets_result",a->ok(json,service.result(root(a),task(a),a.path("batchId").asText())));
return handlers;
}
private static <T>T decode(ObjectMapper mapper,JsonNode value,Class<T> type){try{return mapper.treeToValue(value,type);}catch(com.fasterxml.jackson.core.JsonProcessingException invalid){throw new IllegalArgumentException("Invalid asset request",invalid);}}
private static McpToolResult ok(ObjectMapper mapper,Object value){return McpToolResult.success(mapper,(ObjectNode)mapper.valueToTree(value));}
private static Path root(JsonNode a){return Path.of(a.path("projectRoot").asText());}
private static String task(JsonNode a){String task=a.path("taskId").asText();if(task.isBlank())throw new IllegalArgumentException("Current taskId required");return task;}
}
@@ -22,6 +22,48 @@ public final class McpConnectionGuide implements AgentConnectionGuide {
Supply a unique clientRequestId per intended build/advance. Recover lost responses by lookup using
clientRequestId; do not blindly repeat frame advancement with a new ID. Cancellation acknowledgement
is not worker termination. Use only tools/capabilities actually advertised by this running Studio.
For headless recovery, inspect observation and currentObservation separately: the former preserves
the original operation conclusion; later session queries cannot change its frame or native cause.
Read nativeDetails and unavailable inspections, not diagnostic prose. Unknown completedFrames is null;
zero completed frames does not prove an unsuccessful advance had no internal effects. Recovery actions
describe preconditions and never execute automatically. Reset is not reboot: studio_headless_reset,
then studio_headless_boot with the same buildId, then a new intentional studio_headless_advance.
A memcard cartridge requires an explicit memcardChoice. Use memory_fresh for a disposable RAM-only run,
or an explicitly selected disposable test image with memcard action create/open; never silently use,
replace or discard the user's card. Native dirty/read-only/pending-write refusals are not success.
For declared guest test targets, use studio_tests_targets and studio_tests_start with explicit target,
frame/block/time limits, media and discardUnsaved policy. Poll studio_tests_get by the original
operationId/clientRequestId; studio_tests_transcript reads bounded retained events without execution.
Cancellation uses studio_tests_cancel and is final only after workerTerminated. Historical overflow
alone is not unread loss; preserve gap, native and producer continuity. A native failed advance,
including one with zero completed frames, is never automatically replayed. Inspect its original cause.
Use disposable_create then disposable_reopen with the first runId to prove save readback in a new
process. Commit acknowledgement alone is not readback. Recover a retained cleanup refusal with an
explicit studio_tests_shutdown policy; do not infer consent to discard pending/unsaved data.
Release errors retain final authority and cleanup in details.control: taskRevoked means the old task
cannot be reused even when cleanup failed. The authenticated studio_project_context exposes current
control/runtime observations when the connection is available; otherwise inspect DEV and obtain a
fresh human grant. Never treat the need to inspect cleanup as permission to reuse a revoked identity.
For asset authoring, inspect studio_assets_catalog, studio_assets_artifacts, studio_assets_inspect,
studio_assets_dependencies and studio_assets_budget. Freeze studio_assets_revision before
studio_assets_preview. Review changed files/hashes, producer diagnostics and affected references;
supply every explicit rebind before studio_assets_commit with the reviewed expectedRevision.
Resolve a lost commit response through studio_assets_result; never infer rollback from cancellation.
PNG inputs inside the project require their SHA-256; external PNGs need prior human source selection.
Scene tiles use stable artifact identities. Generated ownership is descriptive and never runs a generator.
Budgets separate content, existing/build banks, final preloads and potential dynamic loads.
Sound is deferred. Unknown capacity is explicit; managed start requires the exact qualified profile.
For visual checkpoints, studio_evidence_persist takes the ORIGINAL terminated operationId or
sourceClientRequestId plus a publication clientRequestId. It never advances or recaptures.
Import a project PNG with studio_evidence_import; an external path requires prior explicit human
selection/authorization. Import does not approve a baseline. Call studio_evidence_compare with
expectedId, actualId and parameters including explicit alpha compare/ignore; omitted tolerances
are exact. Read the verdict, metrics, normalized ROI/masks, hashes and expected/actual/diff IDs.
Use studio_evidence_image for direct PNG content and studio_evidence_read for bounded bytes.
Recover a lost publication response via studio_evidence_list requestId or identical request parameters;
never replay guest work. Evidence survives release/rebuild/reopen, but a fresh task grant is required.
Quota refusal includes used/required/limit; deletion is explicit and reference-aware. Baseline approval
is a human manual-control action in the DEV inspector; never promote a failed comparison automatically.
Observe headless images/state when those tools are available, and explicitly studio_control_release
when finished. On revocation stop external edits too: Studio cannot stop your native file writes.
Existing edits are preserved. Git/review/recovery remain the developer's responsibility.
@@ -0,0 +1,40 @@
package p.studio.app.mcp;
import com.fasterxml.jackson.databind.*;
import com.fasterxml.jackson.databind.node.ObjectNode;
import p.studio.api.automation.*;
import java.nio.file.Path;
import java.util.*;
import java.util.function.Function;
/** Existing authenticated MCP transport; all evidence authority remains in shared Core. */
public final class McpEvidenceTools {
private McpEvidenceTools(){}
public static Map<String,Function<JsonNode,McpToolResult>> handlers(EvidenceTools tools,ObjectMapper mapper) {
var result=new LinkedHashMap<String,Function<JsonNode,McpToolResult>>();
result.put("studio_evidence_persist",a->ok(mapper,tools.persist(root(a),task(a),request(a),new OperationLookup(a.path("operationId").asText(null),a.path("sourceClientRequestId").asText(null)))));
result.put("studio_evidence_import",a->ok(mapper,tools.importReference(root(a),task(a),request(a),Path.of(a.path("path").asText()),a.path("humanGrant").asText(null))));
result.put("studio_evidence_compare",a->ok(mapper,tools.compare(root(a),task(a),request(a),a.path("expectedId").asText(),a.path("actualId").asText(),mapper.convertValue(a.path("parameters"),Evidence.Parameters.class))));
result.put("studio_evidence_list",a->{
var all=tools.list(root(a),task(a));int offset=a.path("offset").asInt(0),limit=a.path("limit").asInt(50);
if(offset>all.size())throw new IllegalArgumentException("Offset exceeds evidence history");
int end=(int)Math.min((long)offset+limit,all.size());
return ok(mapper,Map.of("publications",all.subList(offset,end),"offset",offset,"nextOffset",end,"total",all.size()));
});
result.put("studio_evidence_metadata",a->ok(mapper,tools.metadata(root(a),task(a),a.path("artifactId").asText())));
result.put("studio_evidence_read",a->{
var read=tools.read(root(a),task(a),a.path("artifactId").asText(),a.path("offset").longValue(),a.path("length").intValue());
return ok(mapper,Map.of("artifactId",read.artifactId(),"offset",read.offset(),"totalBytes",read.totalBytes(),"base64",Base64.getEncoder().encodeToString(read.bytes())));
});
result.put("studio_evidence_image",a->{
String id=a.path("artifactId").asText();var metadata=tools.metadata(root(a),task(a),id);
return McpToolResult.image(mapper,mapper.valueToTree(metadata),tools.image(root(a),task(a),id));
});
result.put("studio_evidence_delete",a->{tools.delete(root(a),task(a),a.path("publicationId").asText());return ok(mapper,Map.of("deleted",true));});
return result;
}
private static McpToolResult ok(ObjectMapper mapper,Object value){return McpToolResult.success(mapper,(ObjectNode)mapper.valueToTree(value));}
private static Path root(JsonNode a){return Path.of(a.path("projectRoot").asText());}
private static String task(JsonNode a){return a.path("taskId").asText();}
private static String request(JsonNode a){return a.path("clientRequestId").asText();}
}
@@ -0,0 +1,45 @@
package p.studio.app.mcp;
import com.fasterxml.jackson.databind.*;
import com.fasterxml.jackson.databind.node.ObjectNode;
import p.studio.api.automation.*;
import java.nio.file.Path;
import java.util.*;
import java.util.function.Function;
/** Transport projection over the same guarded service used by the project Tests workspace. */
public final class McpGuestTestTools {
private McpGuestTestTools() { }
public static Map<String,Function<JsonNode,McpToolResult>> handlers(GuestTestTools tools,ObjectMapper mapper) {
var handlers=new LinkedHashMap<String,Function<JsonNode,McpToolResult>>();
handlers.put("studio_tests_targets",a->ok(mapper,Map.of("catalog",tools.targets(root(a),task(a)))));
handlers.put("studio_tests_start",a->{
final GuestTestTools.Request request;
try{request=mapper.treeToValue(a.path("request"),GuestTestTools.Request.class);}
catch(com.fasterxml.jackson.core.JsonProcessingException bad){throw new IllegalArgumentException("Invalid test request",bad);}
return view(mapper,tools.start(root(a),task(a),a.path("clientRequestId").asText(),request));
});
handlers.put("studio_tests_get",a->view(mapper,tools.get(root(a),task(a),lookup(a))));
handlers.put("studio_tests_cancel",a->ok(mapper,Map.of("cancellationRequested",tools.cancel(root(a),task(a),a.path("operationId").asText()))));
handlers.put("studio_tests_transcript",a->ok(mapper,tools.transcript(root(a),task(a),lookup(a),a.path("offset").asInt(0),a.path("limit").asInt(128))));
handlers.put("studio_tests_shutdown",a->{tools.shutdown(root(a),task(a),a.path("operationId").asText(),a.path("discardUnsaved").booleanValue());return ok(mapper,Map.of("runtimeClosed",true));});
return handlers;
}
public static McpToolResult view(ObjectMapper mapper,GuestTestTools.View value) {
var result=mapper.createObjectNode().put("operationId",value.operation().id().value()).put("clientRequestId",value.clientRequestId())
.put("runId",value.runId()).put("state",value.operation().state().name()).put("workerTerminated",value.workerTerminated()).put("runtimeRetained",value.runtimeRetained());
result.set("progress",mapper.valueToTree(value.progress()));
if(value.result()==null)result.putNull("result");
else {
ObjectNode summary=mapper.valueToTree(value.result());summary.remove("transcript");result.set("result",summary);
}
result.put("transcriptTotal",value.result()==null?0:value.result().transcript().size());
result.put("transcriptTool","studio_tests_transcript");
result.set("currentObservation",mapper.valueToTree(value.currentObservation()));
return McpToolResult.success(mapper,result);
}
private static McpToolResult ok(ObjectMapper mapper,Object value){return McpToolResult.success(mapper,(ObjectNode)mapper.valueToTree(value));}
private static Path root(JsonNode value){return Path.of(value.path("projectRoot").asText());}
private static String task(JsonNode value){return value.path("taskId").asText();}
private static OperationLookup lookup(JsonNode value){return new OperationLookup(value.path("operationId").asText(null),value.path("clientRequestId").asText(null));}
}
@@ -15,7 +15,7 @@ public final class McpTaskTools {
var handlers = new LinkedHashMap<String, Function<JsonNode, McpToolResult>>();
handlers.put("studio_control_acquire", args -> control(mapper, tools.acquire(root(args))));
handlers.put("studio_control_release", args -> control(mapper, tools.release(root(args), task(args)).toCompletableFuture().join()));
handlers.put("studio_build_start", args -> receipt(mapper, tools.build(root(args), task(args), args.path("clientRequestId").asText())));
handlers.put("studio_build_start", args -> receipt(mapper, tools.build(root(args), task(args), args.path("clientRequestId").asText(), args.path("targetId").asText(GuestTests.PRODUCTION))));
handlers.put("studio_operation_get", args -> operation(mapper, tools.operation(root(args), task(args),
new OperationLookup(args.path("operationId").asText(null), args.path("clientRequestId").asText(null)))));
handlers.put("studio_operation_cancel", args -> McpToolResult.success(mapper, mapper.createObjectNode()
@@ -36,7 +36,7 @@ public final class McpTaskTools {
default -> Map.of();
};
var result = tools.headless(root(args), task(args), action, args.path("buildId").asText(null), input);
return result.capture() != null ? McpToolResult.capture(mapper, result.capture(), false)
return result.capture() != null ? McpToolResult.capture(mapper, result.capture(), false, result.values())
: McpToolResult.success(mapper, mapper.valueToTree(result.values()));
});
}
@@ -65,9 +65,14 @@ public final class McpTaskTools {
case NOT_GRANTED -> AutomationFailure.Code.NOT_GRANTED;
default -> AutomationFailure.Code.BUSY;
};
return McpToolResult.failure(mapper, new AutomationFailure(code, result.diagnostic()));
var observation = result.observation();
return McpToolResult.failure(mapper, new AutomationFailure(code, result.diagnostic(),
observation != null && observation.failure() != null ? observation.failure().runtimeError() : Map.of(),
observation == null ? Map.of() : Map.of("control", mapper.convertValue(observation, Map.class))));
}
var value = mapper.createObjectNode().put("state", result.task() == null ? "MANUAL" : "AGENT_WORKING");
var value = mapper.createObjectNode().put("state", result.observation() == null
? result.task() == null ? "MANUAL" : "AGENT_WORKING" : result.observation().state().name());
value.set("control", mapper.valueToTree(result.observation()));
if (result.task() != null) value.put("taskId", result.task().value());
return McpToolResult.success(mapper, value);
}
@@ -81,6 +86,8 @@ public final class McpTaskTools {
value.put("workerTerminated", operation.workerTerminated());
value.set("progress", mapper.valueToTree(operation.progress()));
value.set("failure", mapper.valueToTree(operation.failure()));
value.set("observation", mapper.valueToTree(operation.observation()));
value.set("currentObservation", mapper.valueToTree(operation.currentObservation()));
value.putNull("result");
if (operation.buildResult() != null) {
var build = operation.buildResult();
@@ -100,6 +107,7 @@ public final class McpTaskTools {
var result = value.putObject("result").put("kind", "runtime").put("status", runtime.kind().name())
.put("requestedFrames", runtime.requestedFrames()).put("completedFrames", runtime.completedFrames());
result.set("diagnostics", mapper.valueToTree(runtime.diagnostics()));
result.set("observation", mapper.valueToTree(runtime.observation()));
capture = runtime.capture();
}
return McpToolResult.successWithCapture(mapper, value, capture, operation.captureStale());
@@ -22,11 +22,15 @@ public final class McpToolResult {
return envelope(mapper, data, true);
}
public static McpToolResult capture(ObjectMapper mapper, CanonicalCapture capture, boolean stale) {
return capture(mapper, capture, stale, java.util.Map.of());
}
public static McpToolResult capture(ObjectMapper mapper, CanonicalCapture capture, boolean stale, java.util.Map<String, Object> facts) {
Objects.requireNonNull(capture);
var metadata = mapper.createObjectNode().put("sessionId", capture.sessionId()).put("buildId", capture.buildId())
.put("logicalFrameIndex", capture.logicalFrameIndex()).put("frameId", capture.frameId())
.put("width", capture.width()).put("height", capture.height()).put("stridePixels", capture.stridePixels())
.put("pixelFormat", "RGBA8888").put("mimeType", "image/png").put("stale", stale);
facts.forEach((key, item) -> metadata.set(key, mapper.valueToTree(item)));
var result = success(mapper, metadata);
result.wire.withArray("content").addObject().put("type", "image").put("mimeType", "image/png")
.put("data", Base64.getEncoder().encodeToString(capture.png()));
@@ -40,6 +44,12 @@ public final class McpToolResult {
result.wire.withArray("content").add(image.wire.withArray("content").get(1).deepCopy());
return result;
}
public static McpToolResult image(ObjectMapper mapper, ObjectNode metadata, byte[] png) {
var result = success(mapper, metadata);
result.wire.withArray("content").addObject().put("type", "image").put("mimeType", "image/png")
.put("data", Base64.getEncoder().encodeToString(png));
return result;
}
private static McpToolResult envelope(ObjectMapper mapper, JsonNode data, boolean error) {
var wire = mapper.createObjectNode().put("isError", error);
wire.set("structuredContent", data);
@@ -34,6 +34,7 @@ public final class ExternalRuntimeGateway implements RuntimeGateway {
Consumer<RuntimeLogEntry> logs) throws Exception {
final Consumer<RuntimeLogEntry> sink = Objects.requireNonNull(logs, "logs");
final Path executable = resolveExecutable(setup);
new p.studio.app.assets.ManagedAssetGuard(mapper).require(project.rootPath(),project.rootPath().resolve("build"),setup);
final Process process = new ProcessBuilder(command(executable, project, setup))
.directory(project.rootPath().toFile()).start();
stream(process.getInputStream(), false, sink);
@@ -0,0 +1,25 @@
package p.studio.app.runtime;
import com.fasterxml.jackson.databind.ObjectMapper;
import p.studio.api.automation.GuestTests;
import java.util.*;
/** Versioned tagged-event codec; ordinary native game records never reach this decoder. */
public final class GuestEventDecoder implements GuestTests.Decoder {
private final ObjectMapper mapper;
public GuestEventDecoder(ObjectMapper mapper){this.mapper=Objects.requireNonNull(mapper);}
public GuestTests.Event decode(String message) {
try {
com.fasterxml.jackson.databind.JsonNode value=mapper.reader()
.with(com.fasterxml.jackson.core.JsonParser.Feature.STRICT_DUPLICATE_DETECTION)
.with(com.fasterxml.jackson.databind.DeserializationFeature.FAIL_ON_TRAILING_TOKENS).readTree(message);
if(value==null||!value.isObject())throw new IllegalArgumentException("Expected event object");
value.fieldNames().forEachRemaining(name->{if(!Set.of("schemaVersion","suiteId","caseId","eventId","kind","payload").contains(name))throw new IllegalArgumentException("Unknown event field");});
if(!value.path("schemaVersion").isIntegralNumber()||!value.path("schemaVersion").canConvertToInt()
||!value.path("suiteId").isTextual()||!value.path("eventId").isTextual()||!value.path("kind").isTextual()
||!value.path("payload").isObject()||value.has("caseId")&&!value.path("caseId").isNull()&&!value.path("caseId").isTextual())
throw new IllegalArgumentException("Invalid typed event envelope");
return mapper.treeToValue(value,GuestTests.Event.class);
}catch(java.io.IOException invalid){throw new IllegalArgumentException("Invalid tagged JSON event",invalid);}
}
}
@@ -0,0 +1,117 @@
package p.studio.app.runtime;
import com.fasterxml.jackson.databind.ObjectMapper;
import p.studio.api.automation.*;
import p.studio.api.project.ProjectReference;
import p.studio.api.values.ValueMaps;
import p.studio.compiler.messages.BuildingIssueSink;
import p.studio.compiler.utilities.PrometeuManifestUtils;
import p.studio.core.runtime.GuestTestSupport;
import java.nio.file.*;
import java.nio.channels.FileChannel;
import java.nio.ByteBuffer;
import java.security.MessageDigest;
import java.time.Instant;
import java.util.*;
/** Application persistence only: common manifest resolution, owned run media and shared evidence. */
public final class GuestTestSupportAdapter implements GuestTestSupport {
private final ObjectMapper mapper;
private final EvidenceStore evidence;
private final EvidenceStore.Codec pixels;
public GuestTestSupportAdapter(ObjectMapper mapper,EvidenceStore evidence,EvidenceStore.Codec pixels){this.mapper=mapper;this.evidence=evidence;this.pixels=pixels;}
@Override public GuestTests.Catalog targets(ProjectReference project) {
return catalog(manifest(project));
}
private p.studio.compiler.models.PrometeuManifest manifest(ProjectReference project) {
try {
var root=project.rootPath().toRealPath();var issues=BuildingIssueSink.empty();
return PrometeuManifestUtils.buildManifest(root,root.resolve("prometeu.json").toRealPath(),issues)
.orElseThrow(()->new IllegalArgumentException("Invalid project manifest/testTargets: "+issues));
}catch(java.io.IOException failure){throw new IllegalArgumentException("Cannot read project test targets",failure);}
}
private static GuestTests.Catalog catalog(p.studio.compiler.models.PrometeuManifest manifest) {
return new GuestTests.Catalog(manifest.testTargets().schemaVersion(),manifest.testTargets().targets().stream()
.map(t->new GuestTests.Target(t.id(),t.entrypoint(),t.sourceRoots(),t.supportRoots(),t.exclusions(),t.cases(),t.logTag())).toList());
}
@Override public GuestTests.Target targetAtBuild(ProjectReference project,p.studio.api.shipper.ShipperPrepareResult build,String targetId)throws Exception {
var manifest=manifest(project);
Object hashes=build.context().get("configurationSha256");
Object expected=hashes instanceof Map<?,?> map?map.get(project.rootPath().toRealPath().resolve("prometeu.json").toString()):null;
if(!manifest.manifestSha256().equals(expected))throw new IllegalArgumentException("Project test catalog changed since the immutable build");
return catalog(manifest).targets().stream().filter(target->target.id().equals(targetId)).findFirst().orElseThrow(()->new IllegalArgumentException("Built target catalog is unavailable"));
}
@Override public Map<String,Object> media(ProjectReference project,String runId,GuestTestTools.Request request)throws Exception {
Path directory=directory(project.rootPath(),runId);Files.createDirectory(directory);
var descriptor=new LinkedHashMap<String,Object>();descriptor.put("runId",runId);descriptor.put("media",request.media().name());
descriptor.put("reopenRunId",request.reopenRunId());
Map<String,Object> options;
if(request.media()==GuestTestTools.Media.memory_fresh) {
// A cartridge without memcard_slots has no card namespace or boot choice.
// A new process already guarantees fresh RAM; never invent a card declaration.
descriptor.put("memcardApplicable",project.memcardSlots()!=null);
options=project.memcardSlots()==null?Map.of():Map.of("memcardChoice","memory_fresh");
}
else {
if(project.memcardSlots()==null)throw new IllegalArgumentException("Disposable card requires declared memcard_slots");
Path image;
if(request.media()==GuestTestTools.Media.disposable_create)image=directory.resolve("memcard.pmc");
else {
Path owner=directory(project.rootPath(),request.reopenRunId());
var original=mapper.readTree(owner.resolve("media.json").toFile());
if(!original.path("runId").asText().equals(request.reopenRunId())||!original.path("media").asText().equals("disposable_create"))
throw new IllegalArgumentException("Reopen requires a prior owned disposable-create image");
image=owner.resolve("memcard.pmc");
if(Files.isSymbolicLink(image)||!Files.isRegularFile(image)||!image.toRealPath().startsWith(owner.toRealPath()))
throw new IllegalArgumentException("Owned test image unavailable or outside its run");
}
descriptor.put("image",image.toString());
options=Map.of("memcardChoice","persistent","memcard",Map.of("path",image.toString(),"action",
request.media()==GuestTestTools.Media.disposable_create?"create":"open","access","read_write"));
}
atomic(directory.resolve("media.json"),descriptor);return options;
}
@Override public long applicationId(p.studio.api.shipper.ShipperPrepareResult build)throws Exception {
var id=mapper.readTree(build.manifestPath().toFile()).path("app_id");
if(!id.isIntegralNumber()||!id.canConvertToLong()||id.longValue()<0||id.longValue()>0xffff_ffffL)
throw new IllegalArgumentException("Immutable test manifest has no valid application identity");
return id.longValue();
}
@Override public void completed(ProjectReference project,String runId,GuestTests.RunResult result)throws Exception {
Path directory=directory(project.rootPath(),runId);Files.createDirectories(directory);
atomic(directory.resolve("result.json"),result);
}
private Path directory(Path project,String runId)throws Exception {
UUID.fromString(runId);Path root=project.toRealPath();Path parent=root.resolve(".studio/test-runs");
Path ancestor=parent;while(!Files.exists(ancestor))ancestor=ancestor.getParent();
if(!ancestor.toRealPath().startsWith(root))throw new IllegalArgumentException("Test storage escapes project scope");
Files.createDirectories(parent);if(!parent.toRealPath().startsWith(root))throw new IllegalArgumentException("Test storage escapes project scope");
Path directory=parent.resolve(runId);
if(Files.exists(directory)&&(Files.isSymbolicLink(directory)||!directory.toRealPath().startsWith(parent.toRealPath())))
throw new IllegalArgumentException("Test run directory escapes storage scope");
return directory;
}
private void atomic(Path target,Object value)throws Exception {
byte[] bytes=mapper.writeValueAsBytes(value);Path temporary=target.resolveSibling(".staging-"+UUID.randomUUID());
try {
try(var channel=FileChannel.open(temporary,StandardOpenOption.CREATE_NEW,StandardOpenOption.WRITE)){
var buffer=ByteBuffer.wrap(bytes);while(buffer.hasRemaining())channel.write(buffer);channel.force(true);
}
Files.move(temporary,target,StandardCopyOption.ATOMIC_MOVE,StandardCopyOption.REPLACE_EXISTING);
}finally{Files.deleteIfExists(temporary);}
}
@Override public boolean admitsCheckpoint(Path root,String id) {
return evidence.list(root).stream().flatMap(p->p.artifacts().stream()).anyMatch(a->a.id().equals(id));
}
@Override public String retainCapture(Path root,String runId,String operationId,String requestId,CanonicalCapture capture)throws Exception {
var decoded=pixels.decode(capture.png());
if(decoded.width()!=capture.width()||decoded.height()!=capture.height())throw new IllegalArgumentException("Capture metadata mismatch");
String publication=UUID.randomUUID().toString(),id=UUID.randomUUID().toString();
var provenance=ValueMaps.fields("origin","runtime","projectRoot",root.toString(),"runId",runId,"operationId",operationId,
"clientRequestId",requestId,"buildId",capture.buildId(),"sessionId",capture.sessionId(),"logicalFrameIndex",capture.logicalFrameIndex(),"frameId",capture.frameId());
var artifact=new Evidence.Artifact(id,publication,HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(capture.png())),capture.png().length,
"image/png",capture.width(),capture.height(),provenance);
evidence.publish(root,new Evidence.Publication(publication,"guest-test-capture:"+runId,"guest-test:"+runId,root.toString(),Instant.now().toString(),List.of(artifact),null,null),List.of(new Evidence.Blob(artifact,capture.png())));
return id;
}
}
@@ -24,6 +24,12 @@ public final class HeadlessProcessGateway implements HeadlessGateway {
return boot(project, buildId, build, Map.of());
}
@Override public Session boot(ProjectReference project, String buildId, ShipperPrepareResult build, Map<String, Object> options) throws Exception {
return boot(project, buildId, build, options, false);
}
@Override public Session bootTest(ProjectReference project, String buildId, ShipperPrepareResult build, Map<String, Object> options) throws Exception {
return boot(project, buildId, build, options, true);
}
private Session boot(ProjectReference project, String buildId, ShipperPrepareResult build, Map<String, Object> options, boolean test) throws Exception {
var localSetup = setup.apply(project);
String installation = localSetup.prometeuRuntimePath();
if (installation == null) throw new AutomationException(AutomationFailure.Code.RUNTIME_UNAVAILABLE, "Configure the project runtime installation first");
@@ -34,17 +40,27 @@ public final class HeadlessProcessGateway implements HeadlessGateway {
throw new AutomationException(AutomationFailure.Code.BUILD_NOT_FOUND, "Successful build manifest is unavailable");
Path root = project.rootPath().toRealPath(), manifest = build.manifestPath().toRealPath();
if (!manifest.startsWith(root)) throw new AutomationException(AutomationFailure.Code.OUTSIDE_PROJECT_SCOPE, "Build manifest is outside the project");
new p.studio.app.assets.ManagedAssetGuard(mapper).require(root,manifest.getParent(),localSetup);
var command = new ArrayList<String>(); command.add(executable.toString()); command.addAll(limits.arguments());
final Process process;
try { process = new ProcessBuilder(command).directory(root.toFile()).start(); }
catch (java.io.IOException unavailable) { throw new AutomationException(AutomationFailure.Code.RUNTIME_UNAVAILABLE, "Cannot launch the configured runtime"); }
var session = new HeadlessProcessSession(process, mapper, limits, buildId);
session.bootAdmission(() -> new p.studio.app.assets.ManagedAssetGuard(mapper)
.require(root, manifest.getParent(), setup.apply(project)));
try {
session.initializeAndBoot(manifest.getParent(), root, project.memcardSlots() != null || !options.isEmpty(), options,
localSetup.memcardPath() == null ? root.resolve(".studio/memcard.pmc")
: p.studio.core.project.ProjectCartridgeConfiguration.selectedImage(project, localSetup));
: p.studio.core.project.ProjectCartridgeConfiguration.selectedImage(project, localSetup), test);
return session;
}
catch (Exception failure) { session.abort("Headless startup failed"); throw failure; }
catch (Exception failure) {
session.abort("Headless startup failed");
if (failure instanceof AutomationException domain) {
var original = domain.failure();
throw new AutomationException(new AutomationFailure(original.code(), original.message(), original.runtimeError(), original.details(), session.observation()));
}
throw failure;
}
}
}
@@ -22,6 +22,7 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
private final String buildId;
private volatile String sessionId;
private volatile JsonNode hello;
private volatile RuntimeObservation observed;
private Path cartridge;
private Path projectRoot;
private Path selectedImage;
@@ -37,10 +38,15 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
private final AtomicReference<Pending> advance = new AtomicReference<>();
private final Deque<String> stderr = new ArrayDeque<>();
private volatile boolean closing;
private boolean logReadEnabled;
private CompletableFuture<TaskTools.HeadlessReply> shutdown;
private java.util.concurrent.Callable<?> bootAdmission = () -> null;
void bootAdmission(java.util.concurrent.Callable<?> admission) { bootAdmission = java.util.Objects.requireNonNull(admission); }
HeadlessProcessSession(Process process, ObjectMapper source, HeadlessLimits limits, String buildId) {
this.process = process; this.limits = limits; this.buildId = buildId;
observed = RuntimeObservation.unknown(null, buildId);
mapper = source.copy().enable(JsonParser.Feature.STRICT_DUPLICATE_DETECTION).enable(DeserializationFeature.FAIL_ON_TRAILING_TOKENS);
mapper.getFactory().setStreamReadConstraints(StreamReadConstraints.builder().maxStringLength(limits.maxResponseBytes()).build());
timer.scheduleAtFixedRate(() -> { if (process.isAlive()) process.descendants().forEach(descendants::add); }, 0, 20, TimeUnit.MILLISECONDS);
@@ -55,6 +61,9 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
initializeAndBoot(cartridge, projectRoot, memcard, options, projectRoot.resolve(".studio/memcard.pmc"));
}
void initializeAndBoot(Path cartridge, Path projectRoot, boolean memcard, Map<String, Object> options, Path selectedImage) throws Exception {
initializeAndBoot(cartridge, projectRoot, memcard, options, selectedImage, false);
}
void initializeAndBoot(Path cartridge, Path projectRoot, boolean memcard, Map<String, Object> options, Path selectedImage, boolean logRead) throws Exception {
this.cartridge = cartridge;
this.projectRoot = projectRoot;
this.selectedImage = selectedImage;
@@ -64,6 +73,13 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
hello = await(greeting, limits.handshakeTimeoutMs());
version(hello.path("protocolVersion")); text(hello, "runtimeVersion"); capabilities(hello.path("capabilities"));
var required = new HashSet<>(CAPABILITIES);
if (logRead) {
boolean available = false;
for (var capability : hello.path("capabilities")) if (capability.asText().equals("log_read")) available = true;
if (count(hello.path("protocolVersion"), "minor") < 2 || !available)
throw new AutomationException(AutomationFailure.Code.RUNTIME_INCOMPATIBLE, "Structured tests require protocol 1.2/log_read before boot");
required.add("log_read");
}
if (memcard) {
if (count(hello.path("protocolVersion"), "minor") < 1) throw incompatibleMemcard();
boolean available = false;
@@ -77,32 +93,59 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
if (count(hello.path("limits"), field) != expected.path(field).longValue())
throw new AutomationException(AutomationFailure.Code.RUNTIME_INCOMPATIBLE, "Runtime limits do not match launch configuration");
}
var init = mapper.createObjectNode(); init.putObject("protocolVersion").put("major", 1).put("minor", memcard ? 1 : 0);
var init = mapper.createObjectNode(); init.putObject("protocolVersion").put("major", 1).put("minor", logRead ? 2 : memcard ? 1 : 0);
init.set("requiredCapabilities", mapper.valueToTree(required));
var negotiated = request("initialize", init, null, remaining(deadline));
version(negotiated.path("protocolVersion")); capabilities(negotiated.path("capabilities"));
if (logRead) {
boolean available = false;
for (var capability : negotiated.path("capabilities")) if (capability.asText().equals("log_read")) available = true;
if (count(negotiated.path("protocolVersion"), "minor") < 2 || !available)
throw new AutomationException(AutomationFailure.Code.RUNTIME_INCOMPATIBLE, "Runtime did not negotiate log_read");
}
logReadEnabled = logRead;
if (memcard) {
boolean available = false;
for (var capability : negotiated.path("capabilities")) if (capability.asText().equals("memcard")) available = true;
if (count(negotiated.path("protocolVersion"), "minor") < 1 || !available) throw incompatibleMemcard();
}
memcardEnabled = memcard;
state(boot(bootOptions));
updateObservation(value -> value.transition(RuntimeObservation.Lifecycle.UNKNOWN, "initialize", Map.of(
"runtimeVersion", text(hello, "runtimeVersion"), "limits", mapper.convertValue(hello.path("limits"), Object.class),
"capabilities", mapper.convertValue(hello.path("capabilities"), Object.class))));
try { observeState(boot(bootOptions), RuntimeObservation.Lifecycle.BOOTED, "boot"); }
catch (AutomationException failure) { rememberFailure("boot", failure.failure()); throw observedFailure(failure); }
}
private static AutomationException incompatibleMemcard() {
return new AutomationException(AutomationFailure.Code.RUNTIME_INCOMPATIBLE, "Configured runtime requires protocol 1.1 and memcard capability");
}
private JsonNode boot(JsonNode options) throws Exception {
bootAdmission.call();
var params = HeadlessMemcard.boot(mapper, cartridge, options);
if (options.has("memcard")) {
if (!memcardEnabled) throw incompatibleMemcard();
HeadlessMemcard.state(request("memcard_mount", HeadlessMemcard.mount(mapper, projectRoot, options.path("memcard"), selectedImage), null, limits.callTimeoutMs()));
observeMemcard(request("memcard_mount", HeadlessMemcard.mount(mapper, projectRoot, options.path("memcard"), selectedImage), null, limits.callTimeoutMs()), "memcard_mount");
}
if (options.has("memcardChoice") && !memcardEnabled) throw incompatibleMemcard();
return request("boot", params, null, limits.callTimeoutMs());
}
@Override public String sessionId() { return sessionId; }
@Override public RuntimeObservation observation() { return observed; }
@Override public long maxFramesPerAdvance() { return limits.maxFrames(); }
@Override public GuestTests.LogPage logs(java.math.BigInteger afterSequence, int limit) throws Exception {
if (!logReadEnabled) throw new AutomationException(AutomationFailure.Code.RUNTIME_INCOMPATIBLE, "log_read was not negotiated");
if (limit < 1 || limit > 1024 || afterSequence != null && (afterSequence.signum() < 0 || afterSequence.bitLength() > 64))
throw new IllegalArgumentException("Invalid native log cursor/limit");
if (!work.tryLock()) throw new AutomationException(AutomationFailure.Code.BUSY, "Headless operation active");
try {
if (closing) throw new AutomationException(AutomationFailure.Code.BUSY, "Headless shutdown active");
var params = mapper.createObjectNode().put("limit", limit);
if (afterSequence == null) params.putNull("afterSequence"); else params.put("afterSequence", afterSequence);
return HeadlessWire.logs(request("get_logs", params, null, limits.callTimeoutMs()), sessionId, afterSequence, limit);
} catch (AutomationException failure) {
invalidateMalformed(failure); rememberFailure("get_logs", failure.failure()); throw observedFailure(failure);
} finally { work.unlock(); }
}
long pid() { return process.pid(); }
boolean alive() { return process.isAlive() || descendants.stream().anyMatch(ProcessHandle::isAlive); }
@@ -132,22 +175,29 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
var values = new LinkedHashMap<String, Object>(); values.put("sessionId", sessionId); values.put("buildId", buildId);
CanonicalCapture capture = null;
switch (action) {
case CAPTURE -> capture = capture(result, sessionId, buildId);
case CAPTURE -> {
var frame = capture(result, sessionId, buildId); capture = frame;
updateObservation(value -> value.withCapture(frame));
}
case STATE, RESET, BOOT -> {
state(result); values.put("state", mapper.convertValue(result, Object.class));
observeState(result, action == TaskTools.HeadlessAction.RESET ? RuntimeObservation.Lifecycle.UNBOOTED
: action == TaskTools.HeadlessAction.BOOT ? RuntimeObservation.Lifecycle.BOOTED : currentLifecycle(), command);
values.put("state", mapper.convertValue(result, Object.class));
values.put("runtimeVersion", text(hello, "runtimeVersion"));
values.put("limits", mapper.convertValue(hello.path("limits"), Object.class));
values.put("capabilities", mapper.convertValue(hello.path("capabilities"), Object.class));
if (memcardEnabled && action == TaskTools.HeadlessAction.RESET) HeadlessMemcard.state(result.path("memcard"));
if (memcardEnabled && action == TaskTools.HeadlessAction.RESET) observeMemcard(result.path("memcard"), command);
}
case FAULT -> { fault(result); values.put("fault", mapper.convertValue(result, Object.class)); }
case FAULT -> { fault(result); values.put("fault", mapper.convertValue(result, Object.class));
updateObservation(value -> value.transition(value.lifecycle(), command, p.studio.utilities.json.ImmutableJson.fields("fault", mapper.convertValue(result, Object.class)))); }
case MEMCARD_STATE, MEMCARD_MOUNT, MEMCARD_UNMOUNT, MEMCARD_RECONCILE, MEMCARD_CONTINUE_IN_MEMORY -> {
HeadlessMemcard.state(result); values.put("memcard", mapper.convertValue(result, Object.class));
observeMemcard(result, command); values.put("memcard", mapper.convertValue(result, Object.class));
}
default -> { if (!result.isObject()) throw invalid("Invalid acknowledgement"); }
}
values.put("observation", observed);
return new TaskTools.HeadlessReply(values, capture);
} catch (AutomationException failure) { invalidateMalformed(failure); throw failure; }
} catch (AutomationException failure) { invalidateMalformed(failure); rememberFailure(action.name(), failure.failure()); throw observedFailure(failure); }
finally { work.unlock(); }
}
@@ -157,6 +207,7 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
boolean interrupted = false;
try {
if (closing) throw new AutomationException(AutomationFailure.Code.BUSY, "Headless shutdown active");
updateObservation(value -> value.beginAdvance(frames));
var item = new Pending("advance", frames, progress); advance.set(item);
send(item, mapper.createObjectNode().put("frames", frames));
JsonNode result;
@@ -167,11 +218,15 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
} catch (TimeoutException timedOut) {
cancel();
try { awaitUninterruptibly(item.result, limits.shutdownTimeoutMs()); } catch (Exception ignored) { }
abort("Headless advance deadline exceeded"); throw infrastructure("Headless advance deadline exceeded");
var failure = infrastructure("Headless advance deadline exceeded", "deadline");
abort(failure.failure()); throw failure;
}
long requested = count(result, "requested"), completed = count(result, "completed");
final JsonNode nativeResult = result;
if (requested != frames || completed > frames || completed < item.completed) throw invalid("Inconsistent final progress");
updateObservation(value -> value.withProgress(new TrackedOperation.Progress(frames, completed)));
progress.accept(new TrackedOperation.Progress(frames, completed));
updateObservation(value -> value.transition(value.lifecycle(), "advance", Map.of("advance", mapper.convertValue(nativeResult, Object.class))));
var diagnostics = new ArrayList<String>();
var kind = switch (text(result, "stop")) {
case "completed" -> { if (completed != frames) throw invalid("Incomplete completed result"); yield AutomationOutcome.Kind.SUCCEEDED; }
@@ -179,23 +234,42 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
case "terminated" -> AutomationOutcome.Kind.TERMINATED;
case "action_required" -> {
if (!memcardEnabled) throw invalid("Unnegotiated memcard outcome");
var nativeState = request("get_memcard_state", mapper.createObjectNode(), null, limits.callTimeoutMs());
HeadlessMemcard.state(nativeState); diagnostics.add(nativeState.toString());
yield AutomationOutcome.Kind.ACTION_REQUIRED;
}
case "faulted" -> { fault(result.path("fault")); if (result.path("fault").isNull()) throw invalid("Missing fault"); diagnostics.add(result.path("fault").toString()); yield AutomationOutcome.Kind.GUEST_FAULT; }
case "host_error" -> { error(result.path("error")); diagnostics.add(result.path("error").toString()); yield AutomationOutcome.Kind.INFRASTRUCTURE_FAILURE; }
case "faulted" -> {
fault(result.path("fault")); if (result.path("fault").isNull()) throw invalid("Missing fault");
updateObservation(value -> value.transition(value.lifecycle(), "advance", Map.of("fault", mapper.convertValue(nativeResult.path("fault"), Object.class))));
diagnostics.add(result.path("fault").toString()); yield AutomationOutcome.Kind.GUEST_FAULT;
}
case "host_error" -> {
error(result.path("error"));
updateObservation(value -> value.transition(value.lifecycle(), "advance", Map.of("error", mapper.convertValue(nativeResult.path("error"), Object.class))));
diagnostics.add(result.path("error").toString()); yield AutomationOutcome.Kind.INFRASTRUCTURE_FAILURE;
}
default -> throw invalid("Unknown advance stop");
};
CanonicalCapture captured = null;
if (!closing) {
try { captured = capture(request("capture", mapper.createObjectNode(), null, limits.callTimeoutMs()), sessionId, buildId); }
catch (AutomationException noFrame) { if (noFrame.failure().code() != AutomationFailure.Code.NO_FRAME_AVAILABLE) throw noFrame; }
try {
var frame = capture(request("capture", mapper.createObjectNode(), null, limits.callTimeoutMs()), sessionId, buildId);
captured = frame; updateObservation(value -> value.withCapture(frame));
} catch (AutomationException noFrame) {
if (noFrame.failure().code() != AutomationFailure.Code.NO_FRAME_AVAILABLE
&& !closing
&& kind != AutomationOutcome.Kind.INFRASTRUCTURE_FAILURE && kind != AutomationOutcome.Kind.GUEST_FAULT
&& kind != AutomationOutcome.Kind.ACTION_REQUIRED) throw noFrame;
invalidateMalformed(noFrame);
updateObservation(value -> value.unavailable("capture", noFrame.failure()));
}
}
inspectAfterAdvance(kind == AutomationOutcome.Kind.ACTION_REQUIRED);
if (kind != AutomationOutcome.Kind.SUCCEEDED && kind != AutomationOutcome.Kind.CANCELLED)
updateObservation(RuntimeObservation::markCaptureStale);
synchronized (stderr) { diagnostics.addAll(stderr); stderr.clear(); }
return new AutomationOutcome(kind, requested, completed, diagnostics, captured);
} catch (TimeoutException timeout) { abort("Cancellation deadline exceeded"); throw infrastructure("Cancellation deadline exceeded"); }
catch (AutomationException failure) { invalidateMalformed(failure); throw failure; }
return new AutomationOutcome(kind, requested, completed, diagnostics, captured, Map.of(), observed);
} catch (TimeoutException timeout) {
var failure = infrastructure("Cancellation deadline exceeded", "deadline"); abort(failure.failure()); throw failure;
} catch (AutomationException failure) { invalidateMalformed(failure); rememberFailure("advance", failure.failure()); throw observedFailure(failure); }
finally { advance.set(null); work.unlock(); if (interrupted) Thread.currentThread().interrupt(); }
}
@@ -223,7 +297,7 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
// The first forced shutdown reports infrastructure failure. An explicit human
// retry may acknowledge completed cleanup, but never releases a living process.
if (!shutdown.isCompletedExceptionally()) return shutdown;
if (dead.get() && !alive()) return CompletableFuture.completedFuture(new TaskTools.HeadlessReply(Map.of("sessionId", sessionId), null));
if (dead.get() && !alive()) return CompletableFuture.completedFuture(terminatedReply("cleanup_confirmed"));
// A native refusal leaves this channel usable for an explicit retry.
if (closing) return shutdown;
}
@@ -234,24 +308,29 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
if (!dead.get()) {
var response = request("shutdown", params, null, remaining(deadline));
if (!response.path("closed").isBoolean() || !response.path("closed").booleanValue()) throw invalid("Missing shutdown acknowledgement");
if (memcardEnabled) HeadlessMemcard.state(response.path("memcard"));
if (memcardEnabled) observeMemcard(response.path("memcard"), "shutdown");
if (!process.waitFor(remaining(deadline), TimeUnit.MILLISECONDS)) throw new TimeoutException();
terminate();
if (alive()) throw infrastructure("Owned runtime process tree did not terminate");
var values = new LinkedHashMap<String, Object>(); values.put("sessionId", sessionId);
values.putAll(mapper.convertValue(response, new com.fasterxml.jackson.core.type.TypeReference<Map<String, Object>>() {}));
updateObservation(value -> value.transition(RuntimeObservation.Lifecycle.TERMINATED, "shutdown",
Map.of("shutdown", mapper.convertValue(response, Object.class), "processTreeTerminated", true)));
values.put("buildId", buildId); values.put("observation", observed);
return new TaskTools.HeadlessReply(values, null);
}
terminate();
if (alive()) throw infrastructure("Owned runtime process tree did not terminate");
return new TaskTools.HeadlessReply(Map.of("sessionId", sessionId), null);
return terminatedReply("cleanup_confirmed");
} catch (AutomationException refusal) {
rememberFailure("shutdown", refusal.failure());
if (refusal.failure().code() == AutomationFailure.Code.MEMCARD_ERROR) {
closing = false; throw new CompletionException(refusal);
closing = false; throw new CompletionException(observedFailure(refusal));
}
abort("Headless shutdown failed"); throw infrastructure("Headless shutdown failed; owned process tree terminated; save publication outcome unknown");
abort(refusal.failure()); throw new CompletionException(observedFailure(refusal));
} catch (Exception failure) {
abort("Headless shutdown failed"); throw infrastructure("Headless shutdown failed; owned process tree terminated; save publication outcome unknown");
var cause = infrastructure("Headless shutdown failed; save publication outcome unknown", "cleanup");
rememberFailure("shutdown", cause.failure()); abort(cause.failure()); throw cause;
}
});
return shutdown;
@@ -259,7 +338,16 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
private JsonNode request(String command, JsonNode params, Consumer<TrackedOperation.Progress> observer, long timeout) throws Exception {
var item = new Pending(command, null, observer); send(item, params);
try { return await(item.result, timeout); }
catch (InterruptedException interrupted) { abort("Headless request interrupted"); Thread.currentThread().interrupt(); throw infrastructure("Headless request interrupted"); }
catch (InterruptedException interrupted) {
if(Set.of("get_logs","get_state","get_fault","capture","get_memcard_state").contains(command)) {
// Complete an already sent read before cooperative cancellation. It cannot
// mutate the guest; losing this response is never a reason to replay advance.
try { awaitUninterruptibly(item.result,timeout); }
finally { Thread.currentThread().interrupt(); }
throw interrupted;
}
abort("Headless request interrupted"); Thread.currentThread().interrupt(); throw infrastructure("Headless request interrupted");
}
catch (TimeoutException exceeded) {
if (!command.equals("shutdown") && !command.equals("initialize") && !dead.get()) {
closing = true;
@@ -268,11 +356,16 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
awaitUninterruptibly(stop.result, limits.shutdownTimeoutMs());
} catch (Exception ignored) { /* Deadline escalation below always invalidates this process. */ }
}
abort("Headless request deadline exceeded"); throw infrastructure("Headless request deadline exceeded");
var failure = infrastructure("Headless request deadline exceeded", "deadline");
abort(failure.failure()); throw failure;
}
}
private void send(Pending item, JsonNode params) {
private synchronized void send(Pending item, JsonNode params) {
if (dead.get()) throw infrastructure("Headless session lost; create a new session explicitly");
if (closing && Set.of("get_state", "get_memcard_state", "capture").contains(item.command))
throw new AutomationException(AutomationFailure.Code.BUSY, "Observation unavailable during shutdown");
updateObservation(value -> value.withContext(Map.of("runtimeRequestId", item.id, "runtimeCommand", item.command)));
if (item.frames != null) updateObservation(value -> value.withContext(Map.of("advanceRequestId", item.id)));
var envelope = mapper.createObjectNode().put("requestId", item.id).put("command", item.command); envelope.set("params", params);
final byte[] bytes;
try { bytes = mapper.writeValueAsBytes(envelope); } catch (IOException invalid) { throw new IllegalArgumentException(invalid); }
@@ -299,14 +392,21 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
}
if (bytes.size() != 0) throw invalid("Truncated JSONL response");
if (!closing || !pending.isEmpty()) abort("Headless stdout closed");
} catch (Exception failure) { abort("Malformed or lost headless output"); }
} catch (Exception failure) {
var cause = failure instanceof AutomationException domain ? domain.failure()
: new AutomationFailure(AutomationFailure.Code.INFRASTRUCTURE_FAILURE, "Malformed or lost headless output",
Map.of(), Map.of("failureKind", failure instanceof com.fasterxml.jackson.core.JsonProcessingException
|| failure instanceof java.nio.charset.CharacterCodingException ? "protocol" : "transport"));
abort(cause);
}
}
private void receive(JsonNode message) {
process.descendants().forEach(descendants::add);
if (message == null || !message.isObject()) throw invalid("Expected object");
if (sessionId == null) {
if (!text(message, "type").equals("hello")) throw invalid("Expected hello");
sessionId = text(message, "sessionId"); greeting.complete(message); return;
sessionId = text(message, "sessionId"); updateObservation(value -> RuntimeObservation.unknown(sessionId, buildId));
greeting.complete(message); return;
}
if (!text(message, "sessionId").equals(sessionId)) throw invalid("Wrong session identity");
var item = pending.get(text(message, "requestId"));
@@ -314,7 +414,9 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
if (text(message, "type").equals("progress")) {
long requested = count(message, "requested"), completed = count(message, "completed");
if (item.frames == null || requested != item.frames || completed < item.completed || completed > requested) throw invalid("Invalid progress");
item.completed = completed; item.observer.accept(new TrackedOperation.Progress(requested, completed)); return;
item.completed = completed;
updateObservation(value -> value.withProgress(new TrackedOperation.Progress(requested, completed)));
item.observer.accept(new TrackedOperation.Progress(requested, completed)); return;
}
if (!text(message, "type").equals("response") || message.has("result") == message.has("error")) throw invalid("Invalid response envelope");
if (message.has("error")) {
@@ -354,10 +456,15 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
} catch (IOException ignored) { }
}
void abort(String message) {
abort(new AutomationFailure(AutomationFailure.Code.INFRASTRUCTURE_FAILURE, message,
Map.of(), Map.of("failureKind", "transport")));
}
private void abort(AutomationFailure cause) {
if (dead.compareAndSet(false, true)) {
updateObservation(value -> value.transition(RuntimeObservation.Lifecycle.LOST, "process_supervisor", Map.of()));
terminate();
greeting.completeExceptionally(infrastructure(message));
pending.values().forEach(item -> item.result.completeExceptionally(infrastructure(message))); pending.clear();
greeting.completeExceptionally(new AutomationException(cause));
pending.values().forEach(item -> item.result.completeExceptionally(new AutomationException(cause))); pending.clear();
} else terminate();
}
private void terminate() {
@@ -377,9 +484,71 @@ final class HeadlessProcessSession implements HeadlessGateway.Session {
}
}
private void invalidateMalformed(AutomationException failure) {
if (failure.getMessage().startsWith("Invalid headless response:")) abort("Invalid headless response");
if ("protocol".equals(failure.failure().details().get("failureKind"))) abort(failure.failure());
}
private static AutomationException infrastructure(String message) { return infrastructure(message, "transport"); }
private static AutomationException infrastructure(String message, String kind) {
return new AutomationException(new AutomationFailure(AutomationFailure.Code.INFRASTRUCTURE_FAILURE,
message, Map.of(), Map.of("failureKind", kind)));
}
private RuntimeObservation.Lifecycle currentLifecycle() {
return observed.lifecycle() == RuntimeObservation.Lifecycle.UNBOOTED
? RuntimeObservation.Lifecycle.UNBOOTED : RuntimeObservation.Lifecycle.GUEST_OBSERVED;
}
private void observeState(JsonNode result, RuntimeObservation.Lifecycle lifecycle, String source) {
state(result);
updateObservation(value -> value.transition(lifecycle, source, Map.of("state", mapper.convertValue(result, Object.class))));
}
private void observeMemcard(JsonNode result, String source) {
HeadlessMemcard.state(result);
updateObservation(value -> value.transition(value.lifecycle(), source, Map.of("memcard", mapper.convertValue(result, Object.class))));
}
private void rememberFailure(String source, AutomationFailure failure) {
var facts = new LinkedHashMap<String, Object>();
if (!failure.runtimeError().isEmpty()) {
facts.put("error", failure.runtimeError());
var details = failure.runtimeError().get("details");
if (details instanceof Map<?, ?> detail && detail.get("state") instanceof Map<?, ?>)
facts.put("memcard", detail.get("state"));
} else facts.put("consumerFailure", Map.of("code", failure.code().name(), "message", failure.message(), "details", failure.details()));
updateObservation(value -> value.transition(value.lifecycle(), source, facts));
}
private AutomationException observedFailure(AutomationException failure) {
var original = failure.failure();
return new AutomationException(new AutomationFailure(original.code(), original.message(), original.runtimeError(), original.details(), observed));
}
private void inspectAfterAdvance(boolean mediaRequired) {
if (closing) {
var failure = new AutomationFailure(AutomationFailure.Code.BUSY, "Session shutdown is in progress",
Map.of(), Map.of("failureKind", "observation", "phase", "shutdown"));
updateObservation(value -> value.unavailable("get_state", failure));
if (mediaRequired) updateObservation(value -> value.unavailable("get_memcard_state", failure));
return;
}
try {
observeState(request("get_state", mapper.createObjectNode(), null, limits.callTimeoutMs()), currentLifecycle(), "get_state");
} catch (Exception failure) { inspectionFailed("get_state", failure); }
if (mediaRequired) {
try { observeMemcard(request("get_memcard_state", mapper.createObjectNode(), null, limits.callTimeoutMs()), "get_memcard_state"); }
catch (Exception failure) { inspectionFailed("get_memcard_state", failure); }
}
}
private void inspectionFailed(String source, Exception failure) {
if (failure instanceof AutomationException domain) {
invalidateMalformed(domain); updateObservation(value -> value.unavailable(source, domain.failure()));
} else updateObservation(value -> value.unavailable(source, infrastructure("Observation unavailable", "observation").failure()));
}
private TaskTools.HeadlessReply terminatedReply(String source) {
updateObservation(value -> value.transition(RuntimeObservation.Lifecycle.TERMINATED, source, Map.of("processTreeTerminated", true)));
return new TaskTools.HeadlessReply(Map.of("sessionId", sessionId, "buildId", buildId, "observation", observed), null);
}
private synchronized void updateObservation(java.util.function.UnaryOperator<RuntimeObservation> update) {
var next = update.apply(observed);
// Progress/state completion can race process exit. A late observation cannot
// resurrect availability; confirmed cleanup is a separate explicit transition.
observed = dead.get() && next.lifecycle() != RuntimeObservation.Lifecycle.TERMINATED
? next.transition(RuntimeObservation.Lifecycle.LOST, next.source(), Map.of()) : next;
}
private static AutomationException infrastructure(String message) { return new AutomationException(AutomationFailure.Code.INFRASTRUCTURE_FAILURE, message); }
private static <T> T await(CompletableFuture<T> future, long timeout) throws Exception {
try { return future.get(timeout, TimeUnit.MILLISECONDS); }
catch (ExecutionException error) { if (error.getCause() instanceof Exception cause) throw cause; throw error; }
@@ -33,6 +33,30 @@ final class HeadlessWire {
for (var item : value) { if (!item.isTextual()) throw invalid("Invalid capability"); actual.add(item.textValue()); }
if (!actual.containsAll(CAPABILITIES)) throw new AutomationException(AutomationFailure.Code.RUNTIME_INCOMPATIBLE, "Required headless capability unavailable");
}
static GuestTests.LogPage logs(JsonNode value, String session, BigInteger after, int limit) {
try {
if (!text(value, "sessionId").equals(session) || !value.path("events").isArray()
|| value.path("events").size() > limit || !value.path("gap").isBoolean() || !value.path("overflow").isBoolean())
throw invalid("Invalid native log page identity/types");
var events = new ArrayList<GuestTests.LogEvent>();
for (var event : value.path("events")) {
Long app = event.path("appId").isNull() ? null : uint(event.path("appId")).longValueExact();
if (!event.has("appId") || !event.path("message").isTextual()) throw invalid("Invalid native log source/message");
events.add(new GuestTests.LogEvent(uint(event.path("sequence")), uint(event.path("frame")), uint(event.path("timestampMs")),
text(event,"level"), text(event,"source"), app, uint(event.path("tag")).intValueExact(), event.path("message").textValue()));
}
var next = nullableUint(value, "nextAfterSequence");
if (!Objects.equals(next, events.isEmpty() ? after : events.getLast().sequence())
|| !events.isEmpty() && after != null && events.getFirst().sequence().compareTo(after) <= 0)
throw invalid("Native log cursor did not advance correctly");
return new GuestTests.LogPage(session, uint(value.path("logEpoch")), events, nullableUint(value,"oldestSequence"),
nullableUint(value,"newestSequence"), next, value.path("gap").booleanValue(), value.path("overflow").booleanValue());
} catch (IllegalArgumentException | ArithmeticException malformed) { throw invalid("Invalid lossless native log values"); }
}
private static BigInteger nullableUint(JsonNode value, String key) {
if (!value.has(key)) throw invalid("Missing " + key);
return value.path(key).isNull() ? null : uint(value.path(key));
}
static void state(JsonNode value) {
for (var key : List.of("pc", "logicalFrameIndex", "tickIndex", "appId")) uint(value.path(key));
if (!Set.of("running", "paused", "terminated", "faulted").contains(text(value, "status")) || !value.path("stackTop").isArray()) throw invalid("Invalid state");
@@ -104,5 +128,7 @@ final class HeadlessWire {
if (number < 1 || number > Integer.MAX_VALUE) throw invalid("Invalid dimension");
return (int) number;
}
static AutomationException invalid(String message) { return new AutomationException(AutomationFailure.Code.INFRASTRUCTURE_FAILURE, "Invalid headless response: " + message); }
static AutomationException invalid(String message) { return new AutomationException(new AutomationFailure(
AutomationFailure.Code.INFRASTRUCTURE_FAILURE, "Invalid headless response: " + message,
Map.of(), Map.of("failureKind", "protocol"))); }
}
@@ -0,0 +1,38 @@
{
"schemaVersion": 1,
"profiles": [
{
"profile": {
"contractVersion": 1,
"profileId": "macos-arm64-cli-0.1.0-18423f7-glyph-scene-v1",
"runtimeVersion": "0.1.0",
"executableSha256": "bb245dd057bbc910053b63c55b75a573ab4e9c9a02b7c79ba89e659bea8e85c3",
"limits": {
"glyph": 16,
"scene": 16
},
"evidence": [
{
"bankType": "glyph",
"acceptedPreloads": 16,
"rejectedPreloads": 17,
"evidencePath": "asset-capacity/evidence/native-capacity-boundaries.json",
"evidenceSha256": "d5b4576e697f6bcc489ce1795a86d2a365c03cd98ba73b88649ee5e2abaf4cd6"
},
{
"bankType": "scene",
"acceptedPreloads": 16,
"rejectedPreloads": 17,
"evidencePath": "asset-capacity/evidence/native-capacity-boundaries.json",
"evidenceSha256": "d5b4576e697f6bcc489ce1795a86d2a365c03cd98ba73b88649ee5e2abaf4cd6"
}
]
},
"executables": {
"prometeu": "bb245dd057bbc910053b63c55b75a573ab4e9c9a02b7c79ba89e659bea8e85c3",
"prometeu-headless": "18423f798ab28bbd38c12a7ee46459f3ef3d08876cc64327952f57be041fc5df",
"prometeu-runtime": "ee00a587eb48030d1455d3c9bedd784ab620309a09877b50fe3641ae502635df"
}
}
]
}
File diff suppressed because it is too large Load Diff