fix(agent): refuse completion submit and cancellation signal at Load and generation

Core admits both values, and the generated harness honours neither. A
submit package owes an acceptance, a status route and callbacks, and the
harness answers a bare output in the reply. A signal package promises an
explicit interrupted outcome, and a handler runs on a thread Python cannot
interrupt. Each is now refused by contract.Supported, called from
Builder.Load and from generation, before any package exists.

The generated contract also carries the declared concurrency, which the
harness now enforces.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: antoinetoussaint-byte

pkg/agent/builder.go

@@ -19,6 +19,7 @@ import (
 	"google.golang.org/protobuf/encoding/protojson"
 	"google.golang.org/protobuf/proto"
 
+	"github.com/codefly-dev/runnable-python/pkg/contract"
 	"github.com/codefly-dev/runnable-python/pkg/generate"
 	"github.com/codefly-dev/runnable-python/pkg/pack"
 	"github.com/codefly-dev/runnable-python/pkg/prepare"
@@ -89,6 +90,9 @@ func (b *Builder) Load(ctx context.Context, request *builderv0.LoadRequest) (*bu
 	if _, err := generate.HandlerModule(r.Entrypoint.Handler); err != nil {
 		return nil, status.Errorf(codes.InvalidArgument, "%v", err)
 	}
+	if err := contract.Supported(r); err != nil {
+		return nil, status.Errorf(codes.InvalidArgument, "%v", err)
+	}
 	b.runnable, b.identity = r, proto.Clone(id).(*basev0.RunnableIdentity)
 	return &builderv0.LoadResponse{State: &builderv0.LoadStatus{State: builderv0.LoadStatus_READY}}, nil
 }

pkg/agent/builder_load_test.go

@@ -0,0 +1,97 @@
+package agent
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	builderv0 "github.com/codefly-dev/core/generated/go/codefly/services/builder/v0"
+	"github.com/codefly-dev/core/resources"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+)
+
+// TestLoadRefusesWhatTheHarnessCannotHonour holds both refusals at the first
+// call that sees a declaration. Core admits each value, and a package built
+// for either would claim what its harness never does when called: a submit
+// package would answer a bare output where an acceptance is owed, and a signal
+// package would promise an interrupted outcome no Python thread can report.
+func TestLoadRefusesWhatTheHarnessCannotHonour(t *testing.T) {
+	for _, test := range []struct {
+		name    string
+		declare func(*resources.RunnableExecution)
+		refused string
+	}{
+		{"call completion and no cancellation", func(*resources.RunnableExecution) {}, ""},
+		{"submit completion", func(e *resources.RunnableExecution) {
+			e.Recovery, e.Completion = resources.RunnableRecoveryReceipt, resources.RunnableCompletionSubmit
+		}, `completion "submit"`},
+		{"signal cancellation", func(e *resources.RunnableExecution) {
+			e.Cancellation = resources.RunnableCancellationSignal
+		}, `cancellation "signal"`},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			ctx := context.Background()
+			builder, request := declared(t, test.declare)
+
+			loaded, err := builder.Load(ctx, request)
+
+			if test.refused == "" {
+				if err != nil {
+					t.Fatalf("a declaration the harness honours was refused: %v", err)
+				}
+				if loaded.GetState().GetState() != builderv0.LoadStatus_READY {
+					t.Fatalf("state = %v", loaded.GetState().GetState())
+				}
+				return
+			}
+			if status.Code(err) != codes.InvalidArgument || !strings.Contains(err.Error(), test.refused) {
+				t.Fatalf("Load = %v, want InvalidArgument naming %s", err, test.refused)
+			}
+			if builder.runnable != nil {
+				t.Fatal("a refused declaration stayed loaded")
+			}
+		})
+	}
+}
+
+func declared(t *testing.T, declare func(*resources.RunnableExecution)) (*Builder, *builderv0.LoadRequest) {
+	t.Helper()
+	ctx := context.Background()
+	manifest, err := resources.LoadFromPath[resources.Agent](ctx, filepath.Join("..", "..", "agent.codefly.yaml"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "workspace.codefly.yaml"),
+		[]byte("kind: workspace\nname: proof\nlayout: flat\nservices: []\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	workspace, err := resources.LoadWorkspaceFromDir(ctx, dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	module, err := workspace.LoadModuleFromName(ctx, "proof")
+	if err != nil {
+		t.Fatal(err)
+	}
+	r, err := module.NewRunnable(ctx, "word-count", manifest, "handler.py")
+	if err != nil {
+		t.Fatal(err)
+	}
+	declare(r.Execution)
+	if err := r.Save(ctx); err != nil {
+		t.Fatal(err)
+	}
+	location, err := workspace.RunnableLocationOf(r)
+	if err != nil {
+		t.Fatal(err)
+	}
+	wire, err := location.Proto()
+	if err != nil {
+		t.Fatal(err)
+	}
+	return NewBuilder(manifest), &builderv0.LoadRequest{Runnable: wire}
+}

pkg/contract/contract.go

@@ -40,6 +40,24 @@ type Generated struct {
 	// a call carrying no deadline header is bounded by the author's own
 	// statement of how long the operation may run.
 	TimeoutNanoseconds int64 `json:"timeout-nanoseconds"`
+	// Concurrency is the declared bound on simultaneous calls, which the
+	// harness enforces before a handler runs; 0 is the facility default.
+	Concurrency uint32 `json:"concurrency"`
+}
+
+// Supported refuses a declaration the generated harness cannot honour. Both
+// are values core admits, and a package built for either would claim in its
+// configuration what it never does when called.
+func Supported(runnable *resources.Runnable) error {
+	if completion := runnable.Execution.GetCompletion(); completion != resources.RunnableCompletionCall {
+		return fmt.Errorf("completion %q is not served by the Python harness: it answers in the reply to the call (%q) and serves no acceptance, status route or callback",
+			completion, resources.RunnableCompletionCall)
+	}
+	if runnable.Execution.Cancellation == resources.RunnableCancellationSignal {
+		return fmt.Errorf("cancellation %q is not honoured by the Python harness: a handler runs on a thread Python cannot interrupt, so the interrupted outcome it promises could never be reported; declare %q",
+			resources.RunnableCancellationSignal, resources.RunnableCancellationNone)
+	}
+	return nil
 }
 
 // Handler locates the author entrypoint inside the generated package.
@@ -77,6 +95,7 @@ func Generate(runnable *resources.Runnable, handlerModule string) *Generated {
 		MaxInputBytes:      runnable.Execution.MaxInputBytes(),
 		MaxOutputBytes:     runnable.Execution.MaxOutputBytes(),
 		TimeoutNanoseconds: runnable.Execution.GetTimeout().Nanoseconds(),
+		Concurrency:        runnable.Execution.Concurrency,
 		// The whole release identity, not the half a declaration states: the
 		// harness hands it to the handler, and a field missing from the
 		// document is a field the handler cannot read. Standalone generation

pkg/generate/generate.go

@@ -61,6 +61,9 @@ func Generate(runnable *resources.Runnable, dir string) error {
 // Standalone generation checks the declaration's name and version; the Builder
 // always supplies the complete identity resolved during Load.
 func GenerateForRelease(runnable *resources.Runnable, dir string, identity *basev0.RunnableIdentity) error {
+	if err := contract.Supported(runnable); err != nil {
+		return err
+	}
 	module, err := HandlerModule(runnable.Entrypoint.Handler)
 	if err != nil {
 		return err
@@ -205,6 +208,10 @@ def %s(context: Context, input: Input) -> %s | None:
     None is not an error and never means the effect did not happen: it is the
     answer a caller reads as inconclusive, which is what sends it looking again
     rather than invoking a second time.
+
+    Authorize the lookup here: answer only for an effect the caller's
+    context.invocation.work_context may read. The harness requires a Work
+    Context but neither verifies it nor binds the effect id to it.
     """
     raise NotImplementedError("implement the receipt lookup of %s")
 `, contract.ReceiptAttribute, OutputType, runnable.Name)

pkg/generate/generate_test.go

@@ -57,6 +57,7 @@ execution:
   timeout: 1m
   cancellation: none
   recovery: recompute
+  concurrency: 3
   payload:
     max-input-bytes: 4096
     max-output-bytes: 2048
@@ -127,6 +128,9 @@ func TestTheGeneratedContractCarriesTheDeclaredBounds(t *testing.T) {
 	if document["recovery"] != "recompute" {
 		t.Errorf("recovery = %v", document["recovery"])
 	}
+	if document["concurrency"] != 3.0 {
+		t.Errorf("the declared concurrency, which the harness enforces, was not generated: %v", document["concurrency"])
+	}
 	handler, _ := document["handler"].(map[string]any)
 	if handler["module"] != "handler" || handler["attribute"] != "handle" {
 		t.Errorf("handler = %v", handler)
@@ -136,6 +140,33 @@ func TestTheGeneratedContractCarriesTheDeclaredBounds(t *testing.T) {
 	}
 }
 
+// TestGenerationRefusesWhatTheHarnessCannotHonour: core admits both values,
+// and a package generated for either would claim what its harness never does.
+func TestGenerationRefusesWhatTheHarnessCannotHonour(t *testing.T) {
+	for name, change := range map[string][2]string{
+		`completion "submit"`:   {"recovery: recompute", "recovery: receipt\n  completion: submit"},
+		`cancellation "signal"`: {"cancellation: none", "cancellation: signal"},
+	} {
+		t.Run(name, func(t *testing.T) {
+			dir := t.TempDir()
+			write(t, filepath.Join(dir, resources.RunnableConfigurationName), strings.Replace(declaration, change[0], change[1], 1))
+			runnable, err := resources.LoadRunnableFromDir(context.Background(), dir)
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			err = generate.Generate(runnable, dir)
+
+			if err == nil || !strings.Contains(err.Error(), name) {
+				t.Fatalf("Generate = %v, want a refusal naming %s", err, name)
+			}
+			if _, err := os.Stat(filepath.Join(dir, generate.GeneratedDirectory)); !os.IsNotExist(err) {
+				t.Errorf("a refused declaration still generated a harness: %v", err)
+			}
+		})
+	}
+}
+
 func TestRegeneratingProducesTheSameBytes(t *testing.T) {
 	dir := t.TempDir()
 	runnable := load(t, dir)

pkg/pack/pack_test.go

@@ -41,7 +41,7 @@ entrypoint:
 execution:
   facilities: [generated-service]
   timeout: 30s
-  cancellation: signal
+  cancellation: none
   recovery: receipt
 workspace-configuration-dependencies: [stripe]
 `

qualification_test.go

@@ -72,7 +72,7 @@ entrypoint:
 execution:
   facilities: [generated-service, kubernetes]
   timeout: 2m
-  cancellation: signal
+  cancellation: none
   recovery: recompute
   payload:
     max-input-bytes: 65536