Model template as an instance state instead of a separate registry

Adds StateTemplate to the instance state machine. A Standby instance is
auto-promoted to Template the first time it's forked from a snapshot,
and ForkCount is bumped on each subsequent fork. Templates can't wake
while ForkCount > 0; un-promote (Template -> Standby) and delete
(Template -> Stopped) are both refused until forks drain.

Fork bookkeeping lives on StoredMetadata (IsTemplate, ForkCount,
ForkOfTemplate, plus a reserved HotPagesPath for the prefetch path).
Deleting a fork decrements the parent template's ForkCount under the
parent's lock; deletion of the fork's own data has already happened, so
worst case is refcount drift that a future reconciliation pass fixes.

The running-fork flow keeps skipping promotion: it restores the source
back to Running afterward, and a template can't wake.

Author: sjmiller609

lib/instances/delete.go

@@ -35,6 +35,11 @@ func (m *manager) deleteInstance(
 	stored := &meta.StoredMetadata
 	log.DebugContext(ctx, "loaded instance", "instance_id", id, "state", inst.State)
 
+	if inst.State == StateTemplate && stored.ForkCount > 0 {
+		return fmt.Errorf("%w: cannot delete template %s with %d live fork(s); delete forks first", ErrInvalidState, id, stored.ForkCount)
+	}
+	parentTemplateID := stored.ForkOfTemplate
+
 	target, err := m.cancelAndWaitCompressionJob(ctx, m.snapshotJobKeyForInstance(id))
 	if err != nil {
 		return fmt.Errorf("wait for instance compression to stop: %w", err)
@@ -136,10 +141,41 @@ func (m *manager) deleteInstance(
 		return fmt.Errorf("delete instance data: %w", err)
 	}
 
+	if parentTemplateID != "" {
+		m.decrementTemplateForkCount(ctx, parentTemplateID)
+	}
+
 	log.InfoContext(ctx, "instance deleted successfully", "instance_id", id)
 	return nil
 }
 
+// decrementTemplateForkCount drops the parent template's ForkCount by one under
+// the parent's lock. Logs but does not return errors: the fork is already gone,
+// so the worst case is refcount drift that a future reconciliation pass fixes.
+func (m *manager) decrementTemplateForkCount(ctx context.Context, parentID string) {
+	log := logger.FromContext(ctx)
+	lock := m.getInstanceLock(parentID)
+	lock.Lock()
+	defer lock.Unlock()
+
+	parent, err := m.loadMetadata(parentID)
+	if err != nil {
+		log.WarnContext(ctx, "failed to load parent template for refcount decrement",
+			"parent_template_id", parentID, "error", err)
+		return
+	}
+	if parent.ForkCount <= 0 {
+		log.WarnContext(ctx, "parent template fork count is non-positive at decrement; leaving as-is",
+			"parent_template_id", parentID, "fork_count", parent.ForkCount)
+		return
+	}
+	parent.ForkCount--
+	if err := m.saveMetadata(parent); err != nil {
+		log.WarnContext(ctx, "failed to save parent template after refcount decrement",
+			"parent_template_id", parentID, "error", err)
+	}
+}
+
 // killHypervisor force kills the hypervisor process without graceful shutdown
 // Used only for delete operations where we're removing all data anyway.
 // For operations that need graceful shutdown (like standby), use the hypervisor API directly.

lib/instances/fork.go

@@ -66,7 +66,9 @@ func (m *manager) forkInstance(ctx context.Context, id string, req ForkInstanceR
 			return nil, "", fmt.Errorf("standby source instance: %w", err)
 		}
 
-		forked, forkErr := m.forkInstanceFromStoppedOrStandby(ctx, id, req, true)
+		// Running fork is a one-shot clone that restores the source afterward;
+		// promoting to Template would block the restore (templates can't wake).
+		forked, forkErr := m.forkInstanceFromStoppedOrStandby(ctx, id, req, true, true)
 		if forkErr == nil {
 			if err := m.rotateSourceVsockForRestore(ctx, id, forked.Id); err != nil {
 				forkErr = fmt.Errorf("prepare source snapshot for restore: %w", err)
@@ -104,14 +106,14 @@ func (m *manager) forkInstance(ctx context.Context, id string, req ForkInstanceR
 			return nil, "", forkErr
 		}
 		return forked, targetState, nil
-	case StateStopped, StateStandby:
-		forked, err := m.forkInstanceFromStoppedOrStandby(ctx, id, req, false)
+	case StateStopped, StateStandby, StateTemplate:
+		forked, err := m.forkInstanceFromStoppedOrStandby(ctx, id, req, false, false)
 		if err != nil {
 			return nil, "", err
 		}
 		return forked, targetState, nil
 	default:
-		return nil, "", fmt.Errorf("%w: cannot fork from state %s (must be Stopped or Standby, or Running with from_running=true)", ErrInvalidState, source.State)
+		return nil, "", fmt.Errorf("%w: cannot fork from state %s (must be Stopped, Standby, or Template, or Running with from_running=true)", ErrInvalidState, source.State)
 	}
 }
 
@@ -193,7 +195,7 @@ func generateForkSourceVsockCID(sourceID, forkID string, current int64) int64 {
 	return cid
 }
 
-func (m *manager) forkInstanceFromStoppedOrStandby(ctx context.Context, id string, req ForkInstanceRequest, supportValidated bool) (*Instance, error) {
+func (m *manager) forkInstanceFromStoppedOrStandby(ctx context.Context, id string, req ForkInstanceRequest, supportValidated, skipTemplatePromotion bool) (*Instance, error) {
 	log := logger.FromContext(ctx)
 
 	meta, err := m.loadMetadata(id)
@@ -205,10 +207,10 @@ func (m *manager) forkInstanceFromStoppedOrStandby(ctx context.Context, id strin
 	stored := &meta.StoredMetadata
 
 	switch source.State {
-	case StateStopped, StateStandby:
+	case StateStopped, StateStandby, StateTemplate:
 		// allowed
 	default:
-		return nil, fmt.Errorf("%w: cannot fork from state %s (must be Stopped or Standby)", ErrInvalidState, source.State)
+		return nil, fmt.Errorf("%w: cannot fork from state %s (must be Stopped, Standby, or Template)", ErrInvalidState, source.State)
 	}
 
 	if !supportValidated {
@@ -250,7 +252,9 @@ func (m *manager) forkInstanceFromStoppedOrStandby(ctx context.Context, id strin
 	})
 	defer cu.Clean()
 
-	if source.State == StateStandby {
+	fromSnapshot := source.State == StateStandby || source.State == StateTemplate
+
+	if fromSnapshot {
 		if err := m.ensureSnapshotMemoryReady(ctx, m.paths.InstanceSnapshotLatest(id), m.snapshotJobKeyForInstance(id), stored.HypervisorType); err != nil {
 			return nil, fmt.Errorf("prepare standby snapshot for fork: %w", err)
 		}
@@ -286,17 +290,23 @@ func (m *manager) forkInstanceFromStoppedOrStandby(ctx context.Context, id strin
 	// phase (Standby for snapshot forks, Stopped for stopped forks) will be
 	// recorded by the appropriate operation when the fork is acted on.
 	forkMeta.Phases.Reset()
-	switch source.State {
-	case StateStandby:
+	if fromSnapshot {
 		forkMeta.Phases.Record(phasetracking.PhaseStandby, now)
-	case StateStopped:
+	} else {
 		forkMeta.Phases.Record(phasetracking.PhaseStopped, now)
 	}
 
+	// Template-only fields don't carry forward to the fork; the fork is a fresh
+	// instance regardless of whether the parent is a template.
+	forkMeta.IsTemplate = false
+	forkMeta.ForkCount = 0
+	forkMeta.HotPagesPath = ""
+	forkMeta.ForkOfTemplate = ""
+
 	// Keep the original CID for snapshot-based forks.
 	// Rewriting CID in restored memory snapshots is not reliable across
 	// hypervisors.
-	if source.State == StateStandby {
+	if fromSnapshot {
 		forkMeta.VsockCID = stored.VsockCID
 	} else {
 		forkMeta.VsockCID = generateVsockCID(forkID)
@@ -309,7 +319,7 @@ func (m *manager) forkInstanceFromStoppedOrStandby(ctx context.Context, id strin
 		forkMeta.MAC = ""
 	}
 
-	if source.State == StateStandby {
+	if fromSnapshot {
 		snapshotConfigPath := m.paths.InstanceSnapshotConfig(forkID)
 		netCfg := (*hypervisor.ForkNetworkConfig)(nil)
 		if forkMeta.NetworkEnabled {
@@ -331,6 +341,25 @@ func (m *manager) forkInstanceFromStoppedOrStandby(ctx context.Context, id strin
 		}
 	}
 
+	// Promote source to Template (or bump existing template ForkCount) so the
+	// snapshot we just cloned can't be woken or deleted while this fork lives.
+	// Skipped for the running-fork flow, where the source is restored afterward.
+	if fromSnapshot && !skipTemplatePromotion {
+		priorIsTemplate := stored.IsTemplate
+		priorForkCount := stored.ForkCount
+		stored.IsTemplate = true
+		stored.ForkCount = priorForkCount + 1
+		if err := m.saveMetadata(meta); err != nil {
+			return nil, fmt.Errorf("promote source to template: %w", err)
+		}
+		cu.Add(func() {
+			stored.IsTemplate = priorIsTemplate
+			stored.ForkCount = priorForkCount
+			_ = m.saveMetadata(meta)
+		})
+		forkMeta.ForkOfTemplate = stored.Id
+	}
+
 	newMeta := &metadata{StoredMetadata: forkMeta}
 	if err := m.saveMetadata(newMeta); err != nil {
 		return nil, fmt.Errorf("save fork metadata: %w", err)
@@ -384,6 +413,10 @@ func resolveForkTargetState(requested State, sourceState State) (State, error) {
 		switch sourceState {
 		case StateRunning, StateStandby, StateStopped:
 			return sourceState, nil
+		case StateTemplate:
+			// Forks of a template are plain Standby instances; the fork itself
+			// is never a template.
+			return StateStandby, nil
 		default:
 			return "", fmt.Errorf("%w: cannot derive fork target state from source state %s", ErrInvalidState, sourceState)
 		}

lib/instances/fork_test.go

@@ -266,7 +266,7 @@ func TestForkInstanceFromStandbyCancelsCompressionJobAndCopiesRawMemory(t *testi
 	forked, err := manager.forkInstanceFromStoppedOrStandby(ctx, sourceID, ForkInstanceRequest{
 		Name:        "fork-standby-compressed-copy",
 		TargetState: StateStopped,
-	}, true)
+	}, true, false)
 	require.NoError(t, err)
 	require.NotNil(t, forked)
 

lib/instances/manager.go

@@ -447,13 +447,39 @@ func (m *manager) RestoreInstance(ctx context.Context, id string) (*Instance, er
 	if current.State == StateRunning || current.State == StateInitializing {
 		return current, nil
 	}
+	if current.State == StateTemplate {
+		if err := m.demoteTemplate(ctx, id); err != nil {
+			return nil, err
+		}
+	}
 	inst, err := m.restoreInstance(ctx, id)
 	if err == nil {
 		m.notifyLifecycleEvent(ctx, LifecycleEventRestore, inst)
 	}
 	return inst, err
 }
 
+// demoteTemplate un-promotes a Template back to Standby so it can be restored.
+// Requires ForkCount==0. Must be called with the instance lock held.
+func (m *manager) demoteTemplate(ctx context.Context, id string) error {
+	meta, err := m.loadMetadata(id)
+	if err != nil {
+		return err
+	}
+	if meta.ForkCount > 0 {
+		return fmt.Errorf("%w: cannot un-promote template %s with %d live fork(s); delete forks first", ErrInvalidState, id, meta.ForkCount)
+	}
+	if err := StateTemplate.CanTransitionTo(StateStandby); err != nil {
+		return err
+	}
+	meta.IsTemplate = false
+	meta.HotPagesPath = ""
+	if err := m.saveMetadata(meta); err != nil {
+		return fmt.Errorf("save metadata after template un-promote: %w", err)
+	}
+	return nil
+}
+
 func (m *manager) RestoreSnapshot(ctx context.Context, id string, snapshotID string, req RestoreSnapshotRequest) (*Instance, error) {
 	lock := m.getInstanceLock(id)
 	lock.Lock()

lib/instances/manager_test.go

@@ -1497,12 +1497,17 @@ func TestStateTransitions(t *testing.T) {
 		{"Standby to Paused", StateStandby, StatePaused, false},
 		{"Shutdown to Stopped", StateShutdown, StateStopped, false},
 		{"Standby to Stopped", StateStandby, StateStopped, false},
+		{"Standby to Template", StateStandby, StateTemplate, false},
+		{"Template to Standby", StateTemplate, StateStandby, false},
+		{"Template to Stopped", StateTemplate, StateStopped, false},
 		// Invalid transitions
 		{"Running to Standby", StateRunning, StateStandby, true},
 		{"Stopped to Running", StateStopped, StateRunning, true},
 		{"Stopped to Initializing", StateStopped, StateInitializing, true},
 		{"Standby to Running", StateStandby, StateRunning, true},
 		{"Initializing to Paused", StateInitializing, StatePaused, true},
+		{"Template to Running", StateTemplate, StateRunning, true},
+		{"Template to Paused", StateTemplate, StatePaused, true},
 	}
 
 	for _, tt := range tests {

lib/instances/query.go

@@ -72,9 +72,12 @@ func (m *manager) deriveStateWithOptions(ctx context.Context, stored *StoredMeta
 
 	// 1. Check if socket exists
 	if _, err := os.Stat(stored.SocketPath); err != nil {
-		// No socket - check for snapshot to distinguish Stopped vs Standby
+		// No socket - check for snapshot to distinguish Stopped vs Standby/Template
 		m.invalidateCachedHypervisorState(stored.Id)
 		if m.hasSnapshot(stored.DataDir) {
+			if stored.IsTemplate {
+				return stateResult{State: StateTemplate}
+			}
 			return stateResult{State: StateStandby}
 		}
 		return stateResult{State: StateStopped}

lib/instances/state.go

@@ -34,8 +34,13 @@ var ValidTransitions = map[State][]State{
 		StateCreated, // start VMM process
 	},
 	StateStandby: {
-		StatePaused,  // start VMM + restore (atomic operation)
-		StateStopped, // delete snapshot + cleanup (terminal)
+		StatePaused,   // start VMM + restore (atomic operation)
+		StateStopped,  // delete snapshot + cleanup (terminal)
+		StateTemplate, // promote to fork-only parent (gated by fork intent)
+	},
+	StateTemplate: {
+		StateStandby, // un-promote (allowed only when ForkCount==0)
+		StateStopped, // delete (allowed only when ForkCount==0)
 	},
 	// StateUnknown means we failed to determine state - no transitions allowed.
 	// Operations on instances in Unknown state should fail with an error
@@ -75,7 +80,7 @@ func (s State) RequiresVMM() bool {
 	switch s {
 	case StateCreated, StateInitializing, StateRunning, StatePaused, StateShutdown:
 		return true
-	case StateStopped, StateStandby, StateUnknown:
+	case StateStopped, StateStandby, StateTemplate, StateUnknown:
 		return false
 	default:
 		return false