@synopackageland/cli 0.4.1 → 0.5.3

package/templates/native-go/backend/internal/helper/sdk_background_store_linux_test.go

@@ -0,0 +1,261 @@
+//go:build linux && synopkgland_sdk_workers
+
+package helper
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"testing"
+	"time"
+)
+
+func sdkDiskBackgroundFixture(t *testing.T, dir string) (*sdkBackgroundFixture, *FileGrantRepository, string) {
+	t.Helper()
+	if os.Geteuid() != 0 {
+		t.Skip("requires disposable root Linux VM")
+	}
+	f := newSDKBackgroundFixture(t)
+	if dir == "" {
+		var e error
+		dir, e = os.MkdirTemp("/run", "sdk-background-")
+		if e != nil {
+			t.Fatal(e)
+		}
+		t.Cleanup(func() { os.RemoveAll(dir) })
+	}
+	inv := f.c.inventory
+	record := Record{Schema: 2, Inventory: inv, Enabled: true, Lifecycle: &Lifecycle{Schema: 2, Epoch: f.c.epoch, Phase: "running", Binding: Binding{Entered: 1, Boot: "fixture-boot", Install: grantRef('7')}}}
+	if e := writeProtected(dir, "approval.json", record); e != nil {
+		t.Fatal(e)
+	}
+	r := openRootGrantRepository(t, dir, inv)
+	if _, c := NewGrantAuthority(r, nil, nil, nil); c != "" {
+		t.Fatal(c)
+	}
+	policy, _ := diskGrantSnapshot(t, r)
+	f.s.authority.policy = policy
+	f.repo.policy = policy
+	g := cloneAuthorityGrant(f.g)
+	g.Inventory = inv
+	g.ApprovalBinding = policy.ApprovalBinding
+	g.CapabilityDigest = policy.CapabilityDigest
+	if c := r.Transact(func(_ GrantPolicy, s *GrantStore) (bool, Code) {
+		s.Grants = append(s.Grants, g)
+		s.Revision++
+		return true, ""
+	}); c != "" {
+		t.Fatal(c)
+	}
+	f.g = g
+	f.s.authority.repository = r
+	journal, c := newSDKFileJobJournal(r)
+	if c != "" {
+		t.Fatal(c)
+	}
+	f.bg.journal = journal
+	f.o.services.Journal = journal
+	return f, r, dir
+}
+func sdkDiskConfirm(t *testing.T, f *sdkBackgroundFixture, r *FileGrantRepository) (string, Code) {
+	t.Helper()
+	intent := f.prepare(t, time.Hour)
+	_, s := diskGrantSnapshot(t, r)
+	record, c := f.bg.confirm(context.Background(), f.carriers, intent.ID, intent.SummaryDigest, s.Revision)
+	if c != "" {
+		return "", c
+	}
+	return record.Binding.Binding.Delegation.ID, ""
+}
+func TestSDKBackgroundDiskSharedStoreAndRestart(t *testing.T) {
+	f, r, dir := sdkDiskBackgroundFixture(t, "")
+	id, c := sdkDiskConfirm(t, f, r)
+	if c != "" {
+		t.Fatal(c)
+	}
+	reservation, c := f.bg.consume(context.Background(), id)
+	if c != "" {
+		t.Fatal(c)
+	}
+	if reservation.Record.ExecutionKey == "" {
+		t.Fatal("missing execution key")
+	}
+	_, s := diskGrantSnapshot(t, r)
+	if s.Schema != 2 || len(s.Grants) != 1 || len(s.Background) != 1 || s.Background[0].State != "consumed" {
+		t.Fatal(s)
+	}
+	inv := r.expected
+	r.Close()
+	r = openRootGrantRepository(t, dir, inv)
+	if _, c := NewGrantAuthority(r, nil, nil, nil); c != "" {
+		t.Fatal(c)
+	}
+	_, s = diskGrantSnapshot(t, r)
+	if s.Grants[0].State != GrantSuspended || s.Background[0].State != "suspended" || s.Background[0].ExecutionKey == "" {
+		t.Fatal("restart revived authority", s)
+	}
+	journal, c := newSDKFileJobJournal(r)
+	if c != "" {
+		t.Fatal(c)
+	}
+	rs, c := journal.Records()
+	if c != "" || len(rs) != 1 || rs[0].State != "interrupted" {
+		t.Fatal(rs, c)
+	}
+}
+func TestSDKBackgroundDiskConsumptionFailureBurnsMemorySlot(t *testing.T) {
+	for _, stage := range []string{"write", "file-sync", "rename", "after-rename", "directory-sync"} {
+		t.Run(stage, func(t *testing.T) {
+			f, r, _ := sdkDiskBackgroundFixture(t, "")
+			id, c := sdkDiskConfirm(t, f, r)
+			if c != "" {
+				t.Fatal(c)
+			}
+			r.fault = func(s string) error {
+				if s == stage {
+					return errors.New("fixture")
+				}
+				return nil
+			}
+			if _, c := f.bg.consume(context.Background(), id); c == "" {
+				t.Fatal("uncertain consume")
+			}
+			r.fault = nil
+			if _, c := f.bg.consume(context.Background(), id); c == "" {
+				t.Fatal("replayed uncertain consume")
+			}
+			if !f.s.authority.fenced || len(f.children) != 0 || len(f.c.operations) != 0 {
+				t.Fatal("failed write leaked authority")
+			}
+		})
+	}
+}
+func TestSDKBackgroundDiskCrashGaps(t *testing.T) {
+	if os.Getenv("SDK_S3_CRASH_CHILD") != "" {
+		t.Skip("parent only")
+	}
+	for _, publication := range []int{1, 2} {
+		for _, stage := range []string{"file-sync", "rename", "after-rename", "directory-sync"} {
+			t.Run(strconv.Itoa(publication)+"-"+stage, func(t *testing.T) {
+				dir, _, _ := rootGrantFixture(t)
+				cmd := exec.Command(os.Args[0], "-test.run=^TestSDKBackgroundDiskCrashChild$", "-test.v")
+				cmd.Env = append(os.Environ(), "SDK_S3_CRASH_CHILD="+dir, "SDK_S3_PUBLICATION="+strconv.Itoa(publication), "SDK_S3_STAGE="+stage)
+				out, e := cmd.CombinedOutput()
+				var exit *exec.ExitError
+				if !errors.As(e, &exit) || exit.ExitCode() != 81 {
+					t.Fatalf("crash fixture: %v %s", e, out)
+				}
+				raw, e := os.ReadFile(filepath.Join(dir, "approval.json"))
+				if e != nil {
+					t.Fatal(e)
+				}
+				var approval Record
+				if e = json.Unmarshal(raw, &approval); e != nil {
+					t.Fatal(e)
+				}
+				r := openRootGrantRepository(t, dir, approval.Inventory)
+				if _, c := NewGrantAuthority(r, nil, nil, nil); c != "" {
+					t.Fatal(c)
+				}
+				_, s := diskGrantSnapshot(t, r)
+				for _, g := range s.Grants {
+					if g.State == GrantActive {
+						t.Fatal("active migration")
+					}
+				}
+				for _, bg := range s.Background {
+					if bg.State != "suspended" {
+						t.Fatal("active restart", bg)
+					}
+				}
+				journal, c := newSDKFileJobJournal(r)
+				if c != "" {
+					t.Fatal(c)
+				}
+				rs, c := journal.Records()
+				if c != "" {
+					t.Fatal(c)
+				}
+				expected := 0
+				if publication == 2 || stage == "after-rename" || stage == "directory-sync" {
+					expected = 1
+				}
+				if len(rs) != expected {
+					t.Fatal("lost or invented journal", len(rs), expected)
+				}
+				for _, rec := range rs {
+					if rec.State != "interrupted" {
+						t.Fatal("orphan dispatchable", rec.State)
+					}
+					if c := journal.Reserve(rec.Intent); c != ErrReplay {
+						t.Fatal("execution key reused", c)
+					}
+				}
+			})
+		}
+	}
+}
+func TestSDKBackgroundDiskCrashChild(t *testing.T) {
+	dir := os.Getenv("SDK_S3_CRASH_CHILD")
+	if dir == "" {
+		t.Skip("subprocess only")
+	}
+	f, r, _ := sdkDiskBackgroundFixture(t, dir)
+	publication, _ := strconv.Atoi(os.Getenv("SDK_S3_PUBLICATION"))
+	stage := os.Getenv("SDK_S3_STAGE")
+	count := 0
+	r.fault = func(s string) error {
+		if s == stage {
+			count++
+			if count == publication {
+				os.Exit(81)
+			}
+		}
+		return nil
+	}
+	sdkDiskConfirm(t, f, r)
+	t.Fatal("crash point not reached")
+}
+func TestSDKAuthorityDiskUnknownAndDowngradeNeverOverwrite(t *testing.T) {
+	for _, schema := range []int{3, 99} {
+		t.Run(strconv.Itoa(schema), func(t *testing.T) {
+			dir, inv, _ := rootGrantFixture(t)
+			raw := []byte(`{"grantSchema":` + strconv.Itoa(schema) + `,"storeRevision":7,"grants":[]}`)
+			if e := os.WriteFile(filepath.Join(dir, "grants.json"), raw, 0600); e != nil {
+				t.Fatal(e)
+			}
+			r := openRootGrantRepository(t, dir, inv)
+			if _, c := NewGrantAuthority(r, nil, nil, nil); c == "" {
+				t.Fatal("unknown schema accepted")
+			}
+			if c := r.Transact(func(_ GrantPolicy, s *GrantStore) (bool, Code) {
+				*s = GrantStore{Schema: 2, Revision: 1, Grants: []Grant{}}
+				return true, ""
+			}); c != ErrFenced {
+				t.Fatal("unknown overwritten", c)
+			}
+			after, e := os.ReadFile(filepath.Join(dir, "grants.json"))
+			if e != nil || !bytes.Equal(raw, after) {
+				t.Fatal("unknown bytes rewritten", e)
+			}
+		})
+	}
+	f, r, dir := sdkDiskBackgroundFixture(t, "")
+	_ = f
+	before, e := os.ReadFile(filepath.Join(dir, "grants.json"))
+	if e != nil {
+		t.Fatal(e)
+	}
+	if c := r.Transact(func(_ GrantPolicy, s *GrantStore) (bool, Code) { s.Schema = 1; s.Revision++; return true, "" }); c == "" {
+		t.Fatal("downgrade accepted")
+	}
+	after, e := os.ReadFile(filepath.Join(dir, "grants.json"))
+	if e != nil || !bytes.Equal(before, after) {
+		t.Fatal("downgrade overwrote", e)
+	}
+}

package/templates/native-go/backend/internal/helper/sdk_background_store_test.go

@@ -0,0 +1,58 @@
+//go:build synopkgland_sdk_workers
+
+package helper
+
+import (
+	"bytes"
+	"encoding/json"
+	"testing"
+)
+
+func TestSDKAuthorityMigrationAndUnknownSchema(t *testing.T) {
+	for _, state := range []GrantState{GrantActive, GrantSuspended, GrantRevoked} {
+		t.Run(string(state), func(t *testing.T) {
+			a, r, _, _, _, _, _, _ := grantAuthorityFixture(t)
+			old, c := DecodeGrantStore(bytes.NewReader(dataFixture(t, "grant-store")))
+			if c != "" {
+				t.Fatal(c)
+			}
+			g := old.Grants[0]
+			g.State = state
+			if state != GrantActive {
+				g.Reason = ErrSuspended
+			}
+			if state == GrantRevoked {
+				g.Reason = ErrRevoked
+				g.RevokedAt = g.CreatedAt
+			}
+			r.store = GrantStore{Schema: 1, Revision: 10, Grants: []Grant{g}}
+			if _, c := NewGrantAuthority(r, nil, nil, nil); c != "" {
+				t.Fatal(c)
+			}
+			if r.store.Schema != 2 || r.store.Revision != 11 || r.store.Grants[0].Schema != 1 || r.store.Grants[0].State == GrantActive {
+				t.Fatal("unsafe migration", r.store)
+			}
+			if state != GrantActive && r.store.Grants[0].Revision != g.Revision {
+				t.Fatal("rewrote tombstone")
+			}
+			_ = a
+		})
+	}
+	for _, schema := range []int{0, 3, 999} {
+		b, _ := json.Marshal(GrantStore{Schema: schema, Revision: 1, Grants: []Grant{}})
+		if _, c := DecodeGrantStore(bytes.NewReader(b)); c == "" {
+			t.Fatal("unknown schema accepted", schema)
+		}
+	}
+}
+func TestSDKAuthorityEnvelopeCannotDowngrade(t *testing.T) {
+	a, r, _, _, _, _, _, _ := grantAuthorityFixture(t)
+	old := cloneAuthorityStore(r.store)
+	old.Schema = 2
+	next := cloneAuthorityStore(old)
+	next.Schema = 1
+	next.Revision++
+	if c := validateGrantTransition(old, next, a.policy); c == "" {
+		t.Fatal("downgrade accepted")
+	}
+}

package/templates/native-go/backend/internal/helper/sdk_bindings.go

@@ -0,0 +1,60 @@
+//go:build synopkgland_sdk_workers
+
+package helper
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"dsmapp/internal/helper/jobcontract"
+	"embed"
+	"encoding/binary"
+	"encoding/hex"
+	"encoding/json"
+)
+
+// The actual fixed handler and its admission/attach/dispatch sources, not only
+// the historical refusal stub. Other payload sources remain payloadDigest-bound.
+//
+//go:embed jobcontract/stub.go sdk_job_child_linux.go sdk_job_process_linux.go sdk_job.go sdk_attach.go sdk_rpc.go sdk_session.go sdk_session_contract.go
+var sdkHandlerSources embed.FS
+
+func SDKWorkerBindings() jobcontract.WorkerSourceBindings {
+	b := jobcontract.CompiledBindings()
+	h := sha256.New()
+	h.Write([]byte("synopkgland/m3/handler/source-v2\x00"))
+	for _, name := range []string{"jobcontract/stub.go", "sdk_job_child_linux.go", "sdk_job_process_linux.go", "sdk_job.go", "sdk_attach.go", "sdk_rpc.go", "sdk_session.go", "sdk_session_contract.go"} {
+		raw, err := sdkHandlerSources.ReadFile(name)
+		if err != nil {
+			panic("missing fixed SDK handler source")
+		}
+		for _, part := range [][]byte{[]byte(name), raw} {
+			var n [4]byte
+			binary.BigEndian.PutUint32(n[:], uint32(len(part)))
+			h.Write(n[:])
+			h.Write(part)
+		}
+	}
+	b.HandlerBinding = hex.EncodeToString(h.Sum(nil))
+	return b
+}
+func DecodeSDKRegistry(raw []byte) (jobcontract.Registry, jobcontract.SafeReason) {
+	return jobcontract.DecodeRegistryWithBindings(bytes.NewReader(raw), SDKWorkerBindings())
+}
+
+var sdkCompiledRegistry []byte
+
+// Called solely from cmd/helper's compiled registry initializer. No environment,
+// request, or package-writable file can supply this value to a shipped binary.
+func InstallSDKRegistry(i Inventory, raw string) Code {
+	if len(sdkCompiledRegistry) != 0 {
+		return ErrBusy
+	}
+	r, why := DecodeSDKRegistry([]byte(raw))
+	canonical, err := json.Marshal(r)
+	sum := sha256.Sum256([]byte(raw))
+	if why != "" || err != nil || !bytes.Equal(canonical, []byte(raw)) || i.Protocol != DataProtocol || i.DataAccess != "relaxed" || i.RegistryDigest != hex.EncodeToString(sum[:]) {
+		return ErrIncompatible
+	}
+	sdkCompiledRegistry = []byte(raw)
+	return ""
+}

package/templates/native-go/backend/internal/helper/sdk_data_contract.go

@@ -0,0 +1,251 @@
+//go:build synopkgland_sdk_workers
+
+package helper
+
+import (
+	"dsmapp/internal/helper/jobcontract"
+	"time"
+)
+
+// These are S0 contracts only. No data operation is served by the M1 socket.
+const (
+	DataProtocol         = 2
+	GrantSchema          = 1
+	MaxHealthBytes       = 4096
+	MaxControlBytes      = 16 * 1024
+	MaxGrants            = 256 // includes revoked tombstones
+	MaxGrantStoreBytes   = 1 << 20
+	MaxPageEntries       = 200
+	MaxMetadataBytes     = 256 * 1024
+	MaxLiveIntents       = 8 // per native subject
+	MaxPathBytes         = 4096
+	MaxPathSegments      = 32
+	MaxSegmentBytes      = 255
+	MaxBoundedBytes      = 1 << 20
+	MaxTransferBytes     = 64 << 20
+	MaxChunkBytes        = 64 << 10
+	MaxOutstandingLeases = 1 // per transfer
+	MaxPackageOperations = 4
+	MaxSubjectOperations = 2
+	MaxReplayEntries     = 256 // per epoch/session window; full means busy, never eviction
+	ControlTimeout       = time.Second
+	MetadataTimeout      = 5 * time.Second
+	BoundedTimeout       = 10 * time.Second
+	CandidateTTL         = 60 * time.Second
+	IntentTTL            = 30 * time.Second
+	StreamIdleTimeout    = 10 * time.Second
+	StreamTotalTimeout   = 120 * time.Second
+	NativeProofFreshness = 2 * time.Second
+	RevokeDrainTimeout   = 2 * time.Second
+	TerminateGrace       = time.Second
+)
+
+type Action string
+
+const (
+	ActionList        Action = "nas.files.list"
+	ActionStat        Action = "nas.files.stat"
+	ActionRead        Action = "nas.files.read"
+	ActionReadStream  Action = "nas.files.read-stream"
+	ActionCreate      Action = "nas.files.create"
+	ActionWriteStream Action = "nas.files.write-stream"
+	ActionPublish     Action = "nas.files.publish"
+)
+
+func (a Action) ReadOnly() bool {
+	return a == ActionList || a == ActionStat || a == ActionRead || a == ActionReadStream
+}
+
+// Code deliberately has no underlying native error, path, credential or stderr.
+type Code string
+
+const (
+	ErrInvalid         Code = "invalid-request"
+	ErrIncompatible    Code = "incompatible"
+	ErrUnsupported     Code = "unsupported"
+	ErrReplay          Code = "replay"
+	ErrStale           Code = "stale"
+	ErrExpired         Code = "expired"
+	ErrDenied          Code = "denied"
+	ErrUnavailable     Code = "unavailable"
+	ErrSuspended       Code = "suspended"
+	ErrRevoked         Code = "revoked"
+	ErrFenced          Code = "fenced"
+	ErrBusy            Code = "busy"
+	ErrLimit           Code = "limit-exceeded"
+	ErrCanceled        Code = "canceled"
+	ErrTimeout         Code = "timeout"
+	ErrPartial         Code = "partial"
+	ErrCommitUncertain Code = "commit-uncertain"
+	ErrCleanupRequired Code = "cleanup-required"
+	ErrInternal        Code = "internal"
+)
+
+// Presentation-only refusal: admission stays closed during bounded observer recovery.
+const ErrRevalidating Code = "revalidating"
+
+func (c Code) Error() string { return string(c) }
+func (c Code) Valid() bool {
+	switch c {
+	case ErrInvalid, ErrIncompatible, ErrUnsupported, ErrReplay, ErrStale, ErrExpired,
+		ErrDenied, ErrUnavailable, ErrSuspended, ErrRevoked, ErrFenced, ErrRevalidating, ErrBusy, ErrLimit,
+		ErrCanceled, ErrTimeout, ErrPartial, ErrCommitUncertain, ErrCleanupRequired, ErrInternal:
+		return true
+	}
+	return false
+}
+
+type SafeError struct {
+	Code        Code   `json:"code"`
+	OperationID string `json:"operationId,omitempty"`
+}
+
+type ScopeKind string
+
+const (
+	ScopeShared   ScopeKind = "app-shared"
+	ScopePersonal ScopeKind = "user-personal"
+)
+
+// Principal and Scope are root-derived authority records, never caller claims.
+// Strict proof references require S1 validation; the opt-in managed pilot uses
+// a separately labeled SDK enrollment and the SAME S3 admission guard. It never
+// claims native incarnation. Name/UID/dev/inode are not continuity.
+type Principal struct {
+	Kind        string `json:"kind"` // local only
+	SubjectRef  string `json:"subjectRef"`
+	InstanceRef string `json:"instanceRef"`
+	// Explicit S1R discriminator. Omitted legacy fields remain strict/managed;
+	// no decoder may reinterpret their references as UID/username evidence.
+	IdentityBasis string `json:"identityBasis,omitempty"`
+	UID           uint32 `json:"uid,omitempty"`
+	Username      string `json:"username,omitempty"`
+}
+
+type Scope struct {
+	Kind       ScopeKind `json:"kind"`
+	TargetKind string    `json:"targetKind"` // directory only
+	AnchorRef  string    `json:"anchorRef"`  // trusted share or own-home anchor
+	Segments   []string  `json:"segments"`
+	ObjectRef  string    `json:"objectRef"`
+	MountRef   string    `json:"mountRef"` // validated local mount identity, not just st_dev
+}
+
+type ContinuityBinding struct {
+	Epoch        string `json:"epoch"`
+	SubjectProof string `json:"subjectProof"`
+	ScopeProof   string `json:"scopeProof"`
+}
+
+type GrantState string
+
+const (
+	GrantActive    GrantState = "active"
+	GrantSuspended GrantState = "suspended"
+	GrantRevoked   GrantState = "revoked"
+)
+
+type Grant struct {
+	Schema           int               `json:"grantSchema"`
+	ID               string            `json:"grantId"`
+	Revision         uint64            `json:"grantRevision"`
+	Inventory        Inventory         `json:"inventory"`
+	ApprovalBinding  string            `json:"approvalBinding"`
+	CapabilityDigest string            `json:"capabilityDigest"`
+	Owner            Principal         `json:"owner"`
+	Issuer           Principal         `json:"issuer"`
+	Scope            Scope             `json:"scope"`
+	Actions          []Action          `json:"actions"`
+	State            GrantState        `json:"state"`
+	CreatedAt        int64             `json:"createdAt"` // Unix milliseconds
+	RevokedAt        int64             `json:"revokedAt,omitempty"`
+	Reason           Code              `json:"reason,omitempty"`
+	LastValidated    ContinuityBinding `json:"lastValidatedBinding"`
+}
+
+// EffectiveState never restores a revoked or suspended grant. Restart callers
+// must pass continuous=false even if a restored epoch happens to match.
+func (g Grant) EffectiveState(current ContinuityBinding, continuous bool) GrantState {
+	if g.State == GrantRevoked {
+		return GrantRevoked
+	}
+	if g.State != GrantActive || !continuous || !validContinuity(current) || g.LastValidated != current {
+		return GrantSuspended
+	}
+	return GrantActive
+}
+
+type GrantStore struct {
+	Background []jobcontract.BackgroundRecord `json:"background,omitempty"`
+	Schema     int                            `json:"grantSchema"`
+	Revision   uint64                         `json:"storeRevision"`
+	Grants     []Grant                        `json:"grants"`
+}
+
+// Intent is ephemeral and server-derived. Confirmation consumes it only after
+// fresh native identity/role/ACL and exact summary/epoch/candidate revalidation.
+type Intent struct {
+	ID            string    `json:"intentId"`
+	Inventory     Inventory `json:"inventory"`
+	Epoch         string    `json:"epoch"`
+	SubjectRef    string    `json:"subjectRef"`
+	SessionRef    string    `json:"sessionRef"`
+	CandidateID   string    `json:"candidateId"`
+	ScopeKind     ScopeKind `json:"scopeKind"`
+	Actions       []Action  `json:"actions"`
+	SummaryDigest string    `json:"summaryDigest"`
+	ExpiresAt     int64     `json:"expiresAt"` // Unix milliseconds; at most IntentTTL
+}
+
+type ListArgs struct {
+	Segments []string `json:"segments"`
+	Limit    uint32   `json:"limit"`
+	Cursor   string   `json:"cursor,omitempty"`
+}
+type StatArgs struct {
+	Segments []string `json:"segments"`
+}
+type ReadArgs struct {
+	Segments []string `json:"segments"`
+	MaxBytes uint64   `json:"maxBytes"` // no caller offsets/ranges/resume
+}
+type CreateArgs struct {
+	Segments  []string `json:"segments"`
+	Bytes     uint64   `json:"bytes"` // bulk data never carried in JSON
+	Exclusive bool     `json:"exclusive"`
+}
+type WriteStreamArgs struct {
+	Segments []string `json:"segments"`
+	MaxBytes uint64   `json:"maxBytes"`
+}
+type PublishArgs struct {
+	StageID     string `json:"stageId"`
+	NoOverwrite bool   `json:"noOverwrite"`
+}
+
+type Entry struct {
+	EntryID string `json:"entryId"`
+	Name    string `json:"name"` // visible only after actor ACL
+	Kind    string `json:"kind"` // directory or regular
+	Bytes   uint64 `json:"bytes"`
+}
+type ListResult struct {
+	Entries []Entry `json:"entries"`
+	Cursor  string  `json:"cursor,omitempty"` // opaque, bound to actor/grant/revision/epoch
+}
+type ReadResult struct {
+	Bytes uint64 `json:"bytes"`
+} // separate bounded binary relay
+type MutationReceipt struct {
+	EffectsUnknown bool   `json:"effectsUnknown,omitempty"`
+	Created        bool   `json:"created"`
+	Published      bool   `json:"published"`
+	BytesWritten   uint64 `json:"bytesWritten"`
+	Committed      bool   `json:"committed"`
+}
+type RevokeResult struct {
+	GrantID  string `json:"grantId"`
+	Revision uint64 `json:"grantRevision"`
+	Revoked  bool   `json:"revoked"` // R: durable tombstone, deny new admissions
+	Drained  bool   `json:"drained"` // Q: child/relay/lease/FD completion proof
+}