Add control APIs, control-plane binary, and close the CLI gate bypass

Completes FLUID-WP-0004. The Revision and Intent APIs (Blueprint 44.1
and 44.5) are served by fluid-control, which is deliberately off the
request path and must never be reachable by interface consumers: it is
the mechanism that evolves the interface in response to their behaviour.

Intent amendment is a proposal, never an edit. Rewriting a recorded
version returns 409, because changing what a version says would change
what already-published revisions were governed by.

A rejected candidate comes back as 422 with its full stage report rather
than as a server fault. Rejection is a normal outcome (invariant 14) and
the reasons are the evidence a later hypothesis needs.

Also closes a real hole this workplan opened: `fluid revision publish`
previously wrote straight into the evidence store, which was a way
around the deterministic policy gate for anyone with shell access. It
now runs the same pipeline the control plane does and requires a signing
key.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014KmVxhJ35tCo7rE7UnLwWu

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 1116572@bnt-lap001
Assistant-Session: 8ba9bb93-a72a-4883-b189-2499cce5c400

cmd/fluid/commands.go

@@ -2,6 +2,8 @@ package main
 
 import (
 	"context"
+	"crypto/ed25519"
+	"encoding/base64"
 	"encoding/json"
 	"errors"
 	"fmt"
@@ -17,6 +19,9 @@ import (
 	"github.com/tegwick/fluid-core/internal/contract"
 	"github.com/tegwick/fluid-core/internal/evidence"
 	"github.com/tegwick/fluid-core/internal/intent"
+	"github.com/tegwick/fluid-core/internal/policy"
+	"github.com/tegwick/fluid-core/internal/publish"
+	"github.com/tegwick/fluid-core/internal/signing"
 )
 
 // open connects to the evidence store for this invocation.
@@ -127,6 +132,13 @@ func runRevision(ctx context.Context, g globals, args []string) error {
 	case "publish":
 		fs := newFlagSet("revision publish")
 		file := fs.String("file", "", "path to the revision descriptor (YAML or JSON)")
+		keyFile := fs.String("key-file", os.Getenv("FLUID_SIGNING_KEY"), "base64 ed25519 signing key file")
+		keyID := fs.String("key-id", envOr("FLUID_SIGNING_KEY_ID", "dev"), "signing key identifier")
+		ephemeral := fs.Bool("ephemeral-key", false, "sign with a throwaway key (development only)")
+		classes := fs.String("adaptation-classes", "", "comma-separated adaptation classes")
+		complexity := fs.Float64("complexity-delta", 0, "measured complexity impact")
+		share := fs.Float64("traffic-share", 0, "requested traffic share")
+		approvedBy := fs.String("approved-by", "", "authorizing operator; required by the default gate")
 		if err := fs.Parse(args[1:]); err != nil {
 			return err
 		}
@@ -150,43 +162,54 @@ func runRevision(ctx context.Context, g globals, args []string) error {
 		if d.ID == "" {
 			return errors.New("descriptor has no revision id")
 		}
-		// The router refuses unsigned descriptors at runtime; refusing them here
-		// as well means an operator finds out at publish time rather than when
-		// traffic starts failing.
-		if d.Signature == nil {
-			fmt.Fprintln(os.Stderr,
-				"warning: descriptor is unsigned; the router will refuse it once signature enforcement is enabled")
-		}
 
-		body, err := json.Marshal(d)
+		// Publishing goes through the same pipeline the control plane uses.
+		// A CLI that could write a revision straight into the store would be a
+		// way around the deterministic policy gate, which would make the gate
+		// decorative for anyone with shell access.
+		signer, err := loadSigner(*keyID, *keyFile, *ephemeral)
 		if err != nil {
 			return err
 		}
-		if err := store.PutRecord(ctx, contract.KindRevision, string(d.ID), body); err != nil {
+
+		intents := intent.New(store, contract.InterfaceID(iface))
+		pipeline, err := publish.New(publish.Options{
+			Gate:    policy.NewGate(policy.DefaultLimits()),
+			Signer:  signer,
+			Store:   store,
+			Intents: intents,
+		})
+		if err != nil {
 			return err
 		}
 
-		if err := store.AppendEvent(ctx, contract.FluidEvent{
-			SchemaVersion: "0.1",
-			ID:            contract.EventID(fmt.Sprintf("EV-pub-%s-%d", d.ID, time.Now().UnixNano())),
-			OccurredAt:    time.Now().UTC(),
-			EntityType:    contract.FluidEventEntityTypeRevision,
-			EntityID:      string(d.ID),
-			EventType:     "REVISION_PUBLISHED",
-			Actor:         contract.Actor{Type: contract.ActorTypeHuman, ID: operator()},
-			Reason:        fmt.Sprintf("published %s in state %s", d.ID, d.State),
-		}); err != nil {
+		var approver *contract.Actor
+		if *approvedBy != "" {
+			approver = &contract.Actor{Type: contract.ActorTypeHuman, ID: *approvedBy}
+		}
+
+		candidate := publish.NewCandidate(d, contract.Actor{
+			Type: contract.ActorTypeHuman, ID: operator(),
+		})
+
+		verified, report, err := pipeline.Run(ctx, candidate, publish.PromotionRequest{
+			AdaptationClasses:     parseClasses(*classes),
+			ComplexityDelta:       *complexity,
+			RequestedTrafficShare: *share,
+			Approved:              approver != nil,
+			ApprovedBy:            approver,
+		})
+		if err != nil {
+			printReport(report)
+			return err
+		}
+		if err := pipeline.Publish(ctx, verified); err != nil {
 			return err
 		}
 
-		// Binding the revision to its governing intent is what makes the later
-		// audit question answerable (Blueprint 27).
-		is := intent.New(store, contract.InterfaceID(iface))
-		if err := is.Bind(ctx, d.ID, d.Intent.Version); err != nil {
-			return fmt.Errorf("published, but binding to intent %s failed: %w", d.Intent.Version, err)
-		}
-
-		fmt.Printf("published %s (%s), governed by %s\n", d.ID, d.State, d.Intent.Version)
+		printReport(report)
+		fmt.Printf("\npublished %s (%s), governed by %s, signed by %s\n",
+			d.ID, d.State, d.Intent.Version, verified.Descriptor().Signature.KeyID)
 		return nil
 
 	case "list":
@@ -508,3 +531,64 @@ func operator() string {
 	}
 	return "unknown"
 }
+
+// parseClasses splits a comma-separated adaptation class list.
+func parseClasses(s string) []contract.AdaptationClass {
+	if strings.TrimSpace(s) == "" {
+		return nil
+	}
+	var out []contract.AdaptationClass
+	for _, part := range strings.Split(s, ",") {
+		if p := strings.TrimSpace(part); p != "" {
+			out = append(out, contract.AdaptationClass(p))
+		}
+	}
+	return out
+}
+
+// printReport renders the pipeline outcome stage by stage, so a rejection says
+// which gate refused and why rather than only that it failed.
+func printReport(r publish.Report) {
+	if len(r.Stages) == 0 {
+		return
+	}
+	w := out()
+	fmt.Fprintln(w, "STAGE\tRESULT\tDETAIL")
+	for _, s := range r.Stages {
+		verdict := "pass"
+		if !s.Passed {
+			verdict = "FAIL"
+		}
+		fmt.Fprintf(w, "%s\t%s\t%s\n", s.Stage, verdict, oneLine(s.Detail))
+	}
+	_ = w.Flush()
+}
+
+// loadSigner resolves the signing key for a publish.
+//
+// An ephemeral key must be requested explicitly: signing with a key nobody
+// trusts produces revisions the router will refuse, and finding that out at
+// publish time is far better than at traffic time.
+func loadSigner(keyID, keyFile string, ephemeral bool) (*signing.Signer, error) {
+	if keyFile != "" {
+		raw, err := os.ReadFile(keyFile)
+		if err != nil {
+			return nil, fmt.Errorf("read signing key: %w", err)
+		}
+		decoded, err := base64.StdEncoding.DecodeString(strings.TrimSpace(string(raw)))
+		if err != nil {
+			return nil, fmt.Errorf("signing key is not valid base64: %w", err)
+		}
+		return signing.NewSigner(keyID, ed25519.PrivateKey(decoded))
+	}
+	if ephemeral {
+		signer, _, err := signing.GenerateKey(keyID)
+		if err != nil {
+			return nil, err
+		}
+		fmt.Fprintln(os.Stderr,
+			"warning: signing with an ephemeral key; this revision will not verify after the key is gone")
+		return signer, nil
+	}
+	return nil, errors.New("no signing key: pass --key-file, or --ephemeral-key for development")
+}

cmd/fluid/flags.go

@@ -20,4 +20,7 @@ func (f *flagSet) Bool(name string, value bool, usage string) *bool {
 	return f.fs.Bool(name, value, usage)
 }
 func (f *flagSet) Int(name string, value int, usage string) *int { return f.fs.Int(name, value, usage) }
-func (f *flagSet) Parse(args []string) error                     { return f.fs.Parse(args) }
+func (f *flagSet) Float64(name string, value float64, usage string) *float64 {
+	return f.fs.Float64(name, value, usage)
+}
+func (f *flagSet) Parse(args []string) error { return f.fs.Parse(args) }