Release 1.0.10: validated execution, planning and runtime corrections

.github/ai/AGENTS.md

@@ -1,5 +1,13 @@
 # Akoflow Agent Guide
 
+## Required Contribution Workflow
+
+- Every repository change follows `ISSUE -> BRANCH -> PR`.
+- Create or identify the GitHub issue before implementation.
+- Create a dedicated branch linked to that issue; do not implement directly on `main`.
+- Open a pull request from that branch and link it to the issue.
+- Do not bypass this sequence unless the user explicitly instructs otherwise for a specific change.
+
 ## Core Shape
 
 - Go project with CLI and server binaries.

.github/workflows/docs-checks.yaml

@@ -54,6 +54,8 @@ jobs:
         run: npm ci --prefix docs
       - name: Type-check documentation code
         run: npm run typecheck --prefix docs
+      - name: Test API handler contract extraction
+        run: npm run test:api-generator --prefix docs
       - name: Build the documentation site
         run: npm run build --prefix docs
       - name: Verify repository-owned documentation links

.gitignore

@@ -1,4 +1,5 @@
 db.sqlite
+/server
 storage/database.sqlite
 storage/*
 */.DS_Store

AGENTS.md

@@ -1,5 +1,19 @@
 # AkôFlow repository guidance
 
+## Auxiliary tooling language
+
+- Use Go for repository tooling, scientific analysis, calibration, data exports, and their tests.
+- Do not introduce new Ruby scripts or require Ruby to run these tools. Maintain or migrate existing functionality in Go while preserving scientific contracts, provenance, and safety checks.
+- This is the user's persistent repository preference; do not replace Go tooling with Ruby in future work.
+
+## Contribution workflow
+
+- Every repository change follows `ISSUE -> BRANCH -> PR`.
+- Create or identify the GitHub issue before implementation.
+- Create a dedicated branch linked to that issue; do not implement directly on `main`.
+- Open a pull request from that branch and link it to the issue.
+- Do not bypass this sequence unless the user explicitly instructs otherwise for a specific change.
+
 ## Documentation diagrams
 
 - Use Mermaid for architecture, lifecycle, hierarchy, relationship, state, and flow diagrams in the documentation.

cmd/montage-hpc-budget/main.go

@@ -0,0 +1,84 @@
+// montage-hpc-budget versions simulation inputs after an explicit user decision.
+// It never changes a live catalog, provisions resources, or submits executions.
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+	"time"
+)
+
+func removeCap(request map[string]any, at string) (int, error) {
+	run, ok := request["Run"].(map[string]any)
+	if !ok || run["mode"] != "simulation" {
+		return 0, fmt.Errorf("simulation-only request required")
+	}
+	resources, ok := request["Resources"].([]any)
+	if !ok {
+		return 0, fmt.Errorf("resources missing")
+	}
+	count := 0
+	for _, raw := range resources {
+		r, ok := raw.(map[string]any)
+		if !ok || r["type"] != "hpc_machine" {
+			continue
+		}
+		m, ok := r["metadata"].(map[string]any)
+		if !ok {
+			m = map[string]any{}
+			r["metadata"] = m
+		}
+		previous := m["workspaceStorageBudget"]
+		delete(m, "workspaceStorageBudget")
+		m["workspaceStorageBudgetDecision"] = map[string]any{
+			"status": "cap-removed", "source": "explicit-user-decision-20261011",
+			"recordedAt": at, "previousBudget": previous,
+			"meaning": "No enforced HPC storage cap in this forecast; not a measurement of unlimited physical capacity.",
+		}
+		count++
+	}
+	if count == 0 {
+		return 0, fmt.Errorf("no HPC resources")
+	}
+	return count, nil
+}
+
+func main() {
+	in := flag.String("request", "", "existing simulation input")
+	out := flag.String("output", "", "new input; refuses overwrite")
+	flag.Parse()
+	err := func() error {
+		data, err := os.ReadFile(*in)
+		if err != nil {
+			return err
+		}
+		var request map[string]any
+		if err := json.Unmarshal(data, &request); err != nil {
+			return err
+		}
+		n, err := removeCap(request, time.Now().UTC().Format(time.RFC3339))
+		if err != nil {
+			return err
+		}
+		data, err = json.MarshalIndent(request, "", "  ")
+		if err != nil {
+			return err
+		}
+		f, err := os.OpenFile(*out, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0600)
+		if err != nil {
+			return err
+		}
+		defer f.Close()
+		if _, err := f.Write(data); err != nil {
+			return err
+		}
+		fmt.Printf("Versioned simulation input: %d HPC caps explicitly removed; other resources unchanged.\n", n)
+		return nil
+	}()
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}

cmd/montage-hpc-budget/main_test.go

@@ -0,0 +1,25 @@
+package main
+
+import (
+	"github.com/stretchr/testify/require"
+	"testing"
+)
+
+func TestRemoveOnlyHPCCapAndPreserveDecision(t *testing.T) {
+	hpc := map[string]any{"type": "hpc_machine", "metadata": map[string]any{"workspaceStorageBudget": 123, "runtime": "sif"}}
+	cloud := map[string]any{"type": "cloud_vm", "metadata": map[string]any{"workspaceStorageBudget": 456}}
+	r := map[string]any{"Run": map[string]any{"mode": "simulation"}, "Resources": []any{hpc, cloud}}
+	n, err := removeCap(r, "2026-10-11")
+	require.NoError(t, err)
+	require.Equal(t, 1, n)
+	m := hpc["metadata"].(map[string]any)
+	require.NotContains(t, m, "workspaceStorageBudget")
+	require.Equal(t, "sif", m["runtime"])
+	require.Equal(t, 123, m["workspaceStorageBudgetDecision"].(map[string]any)["previousBudget"])
+	require.Equal(t, 456, cloud["metadata"].(map[string]any)["workspaceStorageBudget"])
+}
+
+func TestRejectReal(t *testing.T) {
+	_, err := removeCap(map[string]any{"Run": map[string]any{"mode": "real"}}, "now")
+	require.ErrorContains(t, err, "simulation-only")
+}

cmd/montage-storage-check/main.go

@@ -0,0 +1,63 @@
+// Offline storage bound diagnostic. No API submission or filesystem deletion.
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"github.com/UFFeScience/akoflow/internal/application/ports"
+	"github.com/UFFeScience/akoflow/internal/domain/storagebudget"
+	"github.com/UFFeScience/akoflow/internal/domain/workflow"
+	"os"
+)
+
+func main() {
+	if len(os.Args) != 2 {
+		panic("request path required")
+	}
+	b, err := os.ReadFile(os.Args[1])
+	if err != nil {
+		panic(err)
+	}
+	var r ports.ExecutionRequest
+	if err = json.Unmarshal(b, &r); err != nil {
+		panic(err)
+	}
+	for i := range r.Resources {
+		if string(r.Resources[i].Type) != "hpc_machine" {
+			continue
+		}
+		m := r.Resources[i].Metadata
+		decision, _ := m["workspaceStorageBudgetDecision"].(map[string]any)
+		if previous := decision["previousBudget"]; previous != nil {
+			m["workspaceStorageBudget"] = previous
+		}
+		m["workspaceStorageLifecycle"] = "consumer-barrier-v1"
+	}
+	t := []storagebudget.Timing{}
+	for _, a := range r.Plan.Assignments {
+		t = append(t, storagebudget.Timing{ActivityID: a.ActivityID, ResourceID: a.ResourceID, Start: a.PredictedStartAt, Finish: a.PredictedFinishAt})
+	}
+	rows, missing, err := storagebudget.CheckScheduled(r.Workflow, r.Resources, t)
+	result := map[string]any{"reservations": rows, "missing": missing}
+	types := map[string]string{}
+	for _, a := range r.Plan.Assignments {
+		for _, resource := range r.Resources {
+			if resource.ID == a.ResourceID {
+				types[a.ActivityID] = string(resource.Type)
+			}
+		}
+	}
+	projected, projectionErr := workflow.ProjectWorkspaceDependenciesForResourceTypes(r.Workflow, types)
+	if projectionErr == nil {
+		volumes := []map[string]any{}
+		for _, a := range projected.Activities {
+			volumes = append(volumes, map[string]any{"activityId": a.ID, "volumes": a.Metadata["workspaceProjectionVolumes"]})
+		}
+		result["projectedVolumes"] = volumes
+	}
+	if err != nil {
+		result["error"] = err.Error()
+	}
+	b, _ = json.MarshalIndent(result, "", "  ")
+	fmt.Println(string(b))
+}

cmd/montage-tools/README.md

@@ -0,0 +1,43 @@
+# Montage tooling in Go
+
+Run from the repository root:
+
+```sh
+go run ./cmd/montage-tools <command> <arguments>
+go test -race ./internal/montagetools ./cmd/montage-tools
+```
+
+Alternatively, build once with `go build -o /tmp/akoflow-montage-tools ./cmd/montage-tools`.
+
+The migrated commands preserve the positional arguments of the former scripts;
+use the former basename without `.rb` as the command:
+
+- `audit_montage_results`
+- `build_montage_execution_calibration`
+- `build_montage_workspace_projection`
+- `build_montage_work_features`
+- `extract_montage_compute_work`
+- `freeze_montage_compute_profiles`
+- `freeze_montage_materialization`
+- `prepare_montage_measured_requests`
+- `supplement_montage_root_compute`
+- `validate_montage_transfer_model`
+- `export_cloud_workspace`
+
+Missing or invalid arguments produce a usage error and nonzero exit status.
+Validation modes are `calibrate`, `supplement`, `request`, `compare`,
+`shared-capacity`, and `report`. Request generation accepts simulation requests
+only; it does not submit a real execution.
+
+Scientific JSON exports are private (0600). Historical evidence and predictions
+are not rewritten. Newly serialized JSON may have a different SHA256 because Go
+orders object keys deterministically; source-file digests remain provenance of
+the original input bytes. Numerical equivalence tests allow only floating-point
+rounding tolerance, not changes to routes, volumes, or model contracts.
+
+Only the explicitly requested cloud workspace export calls the daemon API,
+using `AKOFLOW_API_TOKEN` without printing it. It verifies chunk lengths and the
+archive checksum and refuses to overwrite an existing archive. Compute-input
+extraction reads an existing container image via Docker; it does not execute a
+workflow. None of these tools accesses the database directly or restarts the
+daemon. Ruby is no longer required for these repository tools or their tests.

cmd/montage-tools/main.go

@@ -0,0 +1,14 @@
+package main
+
+import (
+	"fmt"
+	"github.com/UFFeScience/akoflow/internal/montagetools"
+	"os"
+)
+
+func main() {
+	if err := montagetools.Run(os.Args[1:]); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}

cmd/server/api.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"os"
+	"path/filepath"
 	"strings"
 	"time"
 
@@ -48,7 +49,7 @@ func buildCloudProvisioner(
 		sshKeys,
 		terraformcloud.Runner{Root: settings.TerraformWorkspace, Binary: settings.TerraformBinary},
 		ansiblecloud.Runner{Root: settings.TerraformWorkspace, Binary: settings.AnsiblePlaybookBinary},
-	)
+	).WithHostTrustVerifier(gcpcloud.HostVerifier{Catalog: gcpcloud.New(nil), Root: filepath.Join("storage", "credentials", "ssh", "cloud-generations")})
 }
 
 func buildAPI(
@@ -75,7 +76,7 @@ func buildAPI(
 		}
 		browsers[domain.StorageLocal], browsers[domain.StoragePVC], browsers[domain.StorageNFS], browsers[domain.StorageLustre] = fs, fs, fs, fs
 	}
-	ssh := sshfilesystem.New(storage.environments, provider.OSCommandExecutor{})
+	ssh := sshfilesystem.New(storage.environments, provider.OSCommandExecutor{}).WithCloudStore(storage.cloud)
 	browsers[domain.StorageSSH] = ssh
 	manager := appbuild.Manager{Root: settings.ArtifactStoreRoot, MaxBytes: settings.BuildContextMaxBytes, Catalog: storage.data}
 	manager.Executor = appbuild.Executor{Catalog: storage.data, Contexts: manager, Runner: provider.OSCommandExecutor{}, Buildctl: settings.Buildctl, Apptainer: settings.Apptainer, ArtifactStoreRoot: settings.ArtifactStoreRoot}
@@ -118,7 +119,7 @@ func buildAPI(
 		Audit:               storage.audit,
 		Console:             console,
 		Terminal:            terminal,
-		Storage:             appstorage.NewBrowserCoordinator(storage.storage, browsers),
+		Storage:             appstorage.NewBrowserCoordinator(appstorage.CloudWorkspaceCatalog{Catalog: storage.storage, Cloud: storage.cloud}, browsers),
 		Build:               manager,
 		Planning:            planning,
 		PlanningStore:       storage.plans,

cmd/server/events.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"os"
+	"strconv"
 	"time"
 
 	applicationexecution "github.com/UFFeScience/akoflow/internal/application/execution"
@@ -84,7 +85,11 @@ func registerExecutionHandlers(
 	}
 	verifiedArtifacts := &applicationtransfer.VerifiedArtifactCache{}
 	kubernetesTransfer := &infratransfer.KubernetesExec{BufferSize: bufferSize}
-	preparer := applicationtransfer.Coordinator{Catalog: data, WorkspaceSyncer: infratransfer.WorkspaceRsync{Resolver: resolver}, Materializer: applicationtransfer.Materializer{Resolver: resolver, Progress: data, VerifiedArtifacts: verifiedArtifacts, Connectors: []ports.TransferConnector{
+	parallelism, err := strconv.Atoi(os.Getenv("AKOFLOW_WORKSPACE_TRANSFER_PARALLELISM"))
+	if err != nil || parallelism <= 0 {
+		parallelism = 8
+	}
+	preparer := applicationtransfer.Coordinator{Catalog: data, WorkspaceSyncer: infratransfer.WorkspaceRsync{Resolver: resolver, Parallelism: parallelism}, Materializer: applicationtransfer.Materializer{Resolver: resolver, Progress: data, VerifiedArtifacts: verifiedArtifacts, Connectors: []ports.TransferConnector{
 		infratransfer.ArtifactStore{Root: artifactStoreRoot}, infratransfer.LocalFilesystem{BufferSize: bufferSize}, infratransfer.RsyncSSH{BufferSize: bufferSize}, kubernetesTransfer, infratransfer.HTTPDownload{}, infratransfer.S3Compatible{BufferSize: bufferSize}, infratransfer.GCS{},
 	}}}
 	supervisor, err := controlexecution.New(

cmd/simgrid-case/README.md

@@ -0,0 +1,26 @@
+# Offline planning and simulation export
+
+Export an existing simulation request without submitting it:
+
+```sh
+go run ./cmd/simgrid-case --request private-request.json --output new-case-dir
+```
+
+Generate experimental PRISM-time candidates first, requiring measured compute
+profiles, then export the first time-ranked candidate for native SimGrid:
+
+```sh
+go run ./cmd/simgrid-case --prism-time --request private-request.json --output new-case-dir
+```
+
+Input must be simulation-only. The caller supplies the complete resource scope,
+topology, evidenced materialization profiles, compute profiles and runtimes.
+Missing materialization route profiles do not acquire guessed rates. Both the
+planner and simulation exporter consume the same request model. Timeout is ten
+minutes; beam width and candidate count use PRISM defaults (120 and 25).
+Private exports include candidates, selected request, platform and native input.
+The output directory must not exist. This tool does not contact the daemon,
+access the database, provision cloud resources or start a real execution.
+
+Model agreement is not independent real validation. This command does not
+estimate missing physical interference or validate unobserved route classes.