feat: Add InternalAccount resource type to manifest pipeline (#1688)

Add InternalAccountDefinition as a distinct resource type in the manifest
pipeline, separate from AccountType (which is reference data). Internal
accounts represent the chart of accounts -- structural accounts owned by
the economy.

- Proto: Add InternalAccountDefinition message with code, account_type,
  instrument, owner_organization, and description fields
- Differ: Implement diffInternalAccounts with create/update/delete/no-change
  detection and change description
- Planner: Add PhaseInternalAccounts (phase 12) after organizations,
  map to InitiateInternalAccount/UpdateInternalAccount/ControlInternalAccount
- Validator: Add duplicate code detection and cross-reference validation
  for account_type, instrument, and owner_organization references

Co-authored-by: Ben Coombs <bjcoombs@users.noreply.github.com>

Author: bjcoombs

api/jsonschema/manifest.v1.schema.json

@@ -16,7 +16,8 @@
                 "mappings",
                 "operationalGateway",
                 "marketData",
-                "organizations"
+                "organizations",
+                "internalAccounts"
             ],
             "properties": {
                 "version": {
@@ -106,6 +107,14 @@
                     "additionalProperties": false,
                     "type": "array",
                     "description": "organizations defines the organization entities (parties) for this tenant."
+                },
+                "internalAccounts": {
+                    "items": {
+                        "$ref": "#/definitions/meridian.control_plane.v1.InternalAccountDefinition"
+                    },
+                    "additionalProperties": false,
+                    "type": "array",
+                    "description": "internal_accounts defines the chart of accounts — structural accounts owned by the economy. Each internal account references an account type, an instrument, and optionally an owner organization."
                 }
             },
             "additionalProperties": false,
@@ -487,6 +496,41 @@
             "title": "Instrument Dimensions",
             "description": "InstrumentDimensions describes the unit and precision of an instrument's quantities."
         },
+        "meridian.control_plane.v1.InternalAccountDefinition": {
+            "required": [
+                "code",
+                "accountType",
+                "instrument",
+                "ownerOrganization",
+                "description"
+            ],
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "description": "code is the unique identifier for this internal account (e.g., \"REVENUE_GBP\", \"SETTLEMENT_KWH\"). Must be uppercase alphanumeric with underscores."
+                },
+                "accountType": {
+                    "type": "string",
+                    "description": "account_type references the account type classification for this account. Must match a code from the manifest's account_types list."
+                },
+                "instrument": {
+                    "type": "string",
+                    "description": "instrument references the instrument (asset type) this account holds. Must match a code from the manifest's instruments list."
+                },
+                "ownerOrganization": {
+                    "type": "string",
+                    "description": "owner_organization optionally references the organization that owns this account. If set, must match a code from the manifest's organizations list."
+                },
+                "description": {
+                    "type": "string",
+                    "description": "description provides additional context about this internal account's purpose."
+                }
+            },
+            "additionalProperties": false,
+            "type": "object",
+            "title": "========================================\n Internal Account Definitions\n ========================================",
+            "description": "======================================== Internal Account Definitions ========================================  InternalAccountDefinition declares a structural account in the chart of accounts. Internal accounts are owned by the economy (not by external parties) and are provisioned via the Internal Account Service. The code field is the immutable primary key."
+        },
         "meridian.control_plane.v1.MTLSAuthConfig": {
             "required": [
                 "clientCertSecretRef",

api/proto/meridian/control_plane/v1/manifest.proto

@@ -70,6 +70,11 @@ message Manifest {
 
   // organizations defines the organization entities (parties) for this tenant.
   repeated OrganizationDefinition organizations = 13;
+
+  // internal_accounts defines the chart of accounts — structural accounts
+  // owned by the economy. Each internal account references an account type,
+  // an instrument, and optionally an owner organization.
+  repeated InternalAccountDefinition internal_accounts = 14;
 }
 
 // ========================================
@@ -889,3 +894,46 @@ message OrganizationDefinition {
   // Keys and values are validated against the party type's attribute_schema if defined.
   map<string, string> attributes = 4;
 }
+
+// ========================================
+// Internal Account Definitions
+// ========================================
+
+// InternalAccountDefinition declares a structural account in the chart of accounts.
+// Internal accounts are owned by the economy (not by external parties) and are
+// provisioned via the Internal Account Service. The code field is the immutable primary key.
+message InternalAccountDefinition {
+  // code is the unique identifier for this internal account (e.g., "REVENUE_GBP", "SETTLEMENT_KWH").
+  // Must be uppercase alphanumeric with underscores.
+  string code = 1 [(buf.validate.field).string = {
+    min_len: 1
+    max_len: 64
+    pattern: "^[A-Z][A-Z0-9_]*$"
+  }];
+
+  // account_type references the account type classification for this account.
+  // Must match a code from the manifest's account_types list.
+  string account_type = 2 [(buf.validate.field).string = {
+    min_len: 1
+    max_len: 50
+    pattern: "^[A-Z0-9_]{1,50}$"
+  }];
+
+  // instrument references the instrument (asset type) this account holds.
+  // Must match a code from the manifest's instruments list.
+  string instrument = 3 [(buf.validate.field).string = {
+    min_len: 1
+    max_len: 50
+    pattern: "^[A-Z0-9_]{1,50}$"
+  }];
+
+  // owner_organization optionally references the organization that owns this account.
+  // If set, must match a code from the manifest's organizations list.
+  string owner_organization = 4 [(buf.validate.field).string = {
+    max_len: 64
+    pattern: "^$|^[A-Z][A-Z0-9_]*$"
+  }];
+
+  // description provides additional context about this internal account's purpose.
+  string description = 5 [(buf.validate.field).string.max_len = 1024];
+}

services/control-plane/internal/differ/manifest_differ.go

@@ -81,6 +81,7 @@ func (d *ManifestDiffer) Diff(ctx context.Context, lastApplied, newManifest *con
 	d.diffMarketDataSources(lastApplied, newManifest, plan)
 	d.diffMarketDataSets(lastApplied, newManifest, plan)
 	d.diffOrganizations(lastApplied, newManifest, plan)
+	d.diffInternalAccounts(lastApplied, newManifest, plan)
 
 	// Run safety checks on all DELETE actions (skip when validating for a new tenant)
 	if !cfg.skipSafetyChecks {
@@ -361,7 +362,8 @@ func (d *ManifestDiffer) runSafetyChecks(ctx context.Context, plan *DiffPlan) er
 			ResourceInstructionRoute,
 			ResourceMarketDataSource,
 			ResourceMarketDataSet,
-			ResourceOrganization:
+			ResourceOrganization,
+			ResourceInternalAccount:
 			// No downstream dependency checks for these resource types.
 		}
 		if err != nil {
@@ -643,6 +645,50 @@ func (d *ManifestDiffer) diffOrganizations(lastApplied, newManifest *controlplan
 	}
 }
 
+func (d *ManifestDiffer) diffInternalAccounts(lastApplied, newManifest *controlplanev1.Manifest, plan *DiffPlan) {
+	oldMap := internalAccountMap(getInternalAccounts(lastApplied))
+	newMap := internalAccountMap(newManifest.GetInternalAccounts())
+
+	for code, updated := range newMap {
+		prev, exists := oldMap[code]
+		if !exists {
+			plan.Actions = append(plan.Actions, PlannedAction{
+				ResourceType: ResourceInternalAccount,
+				ResourceCode: code,
+				Action:       ActionCreate,
+				Description:  fmt.Sprintf("Create internal account %s (type: %s, instrument: %s)", code, updated.GetAccountType(), updated.GetInstrument()),
+			})
+			continue
+		}
+		if !proto.Equal(prev, updated) {
+			plan.Actions = append(plan.Actions, PlannedAction{
+				ResourceType: ResourceInternalAccount,
+				ResourceCode: code,
+				Action:       ActionUpdate,
+				Description:  describeInternalAccountChanges(code, prev, updated),
+			})
+		} else {
+			plan.Actions = append(plan.Actions, PlannedAction{
+				ResourceType: ResourceInternalAccount,
+				ResourceCode: code,
+				Action:       ActionNoChange,
+				Description:  fmt.Sprintf("Internal account %s unchanged", code),
+			})
+		}
+	}
+
+	for code := range oldMap {
+		if _, exists := newMap[code]; !exists {
+			plan.Actions = append(plan.Actions, PlannedAction{
+				ResourceType: ResourceInternalAccount,
+				ResourceCode: code,
+				Action:       ActionDelete,
+				Description:  fmt.Sprintf("Delete internal account %s", code),
+			})
+		}
+	}
+}
+
 // Helper functions to safely extract slices from possibly-nil manifests.
 
 func getInstruments(m *controlplanev1.Manifest) []*controlplanev1.InstrumentDefinition {
@@ -823,6 +869,21 @@ func organizationMap(orgs []*controlplanev1.OrganizationDefinition) map[string]*
 	return m
 }
 
+func getInternalAccounts(m *controlplanev1.Manifest) []*controlplanev1.InternalAccountDefinition {
+	if m == nil {
+		return nil
+	}
+	return m.GetInternalAccounts()
+}
+
+func internalAccountMap(accounts []*controlplanev1.InternalAccountDefinition) map[string]*controlplanev1.InternalAccountDefinition {
+	m := make(map[string]*controlplanev1.InternalAccountDefinition, len(accounts))
+	for _, a := range accounts {
+		m[a.GetCode()] = a
+	}
+	return m
+}
+
 // Change description helpers.
 
 func describeInstrumentChanges(code string, prev, updated *controlplanev1.InstrumentDefinition) string {
@@ -967,6 +1028,26 @@ func describeOrganizationChanges(code string, prev, updated *controlplanev1.Orga
 	return fmt.Sprintf("Update organization %s (%s)", code, strings.Join(changes, "; "))
 }
 
+func describeInternalAccountChanges(code string, prev, updated *controlplanev1.InternalAccountDefinition) string {
+	var changes []string
+	if prev.GetAccountType() != updated.GetAccountType() {
+		changes = append(changes, fmt.Sprintf("account_type: %q -> %q", prev.GetAccountType(), updated.GetAccountType()))
+	}
+	if prev.GetInstrument() != updated.GetInstrument() {
+		changes = append(changes, fmt.Sprintf("instrument: %q -> %q", prev.GetInstrument(), updated.GetInstrument()))
+	}
+	if prev.GetOwnerOrganization() != updated.GetOwnerOrganization() {
+		changes = append(changes, fmt.Sprintf("owner_organization: %q -> %q", prev.GetOwnerOrganization(), updated.GetOwnerOrganization()))
+	}
+	if prev.GetDescription() != updated.GetDescription() {
+		changes = append(changes, "description changed")
+	}
+	if len(changes) == 0 {
+		return fmt.Sprintf("Update internal account %s", code)
+	}
+	return fmt.Sprintf("Update internal account %s (%s)", code, strings.Join(changes, "; "))
+}
+
 // attributesEqual compares two string-keyed maps for equality.
 func attributesEqual(a, b map[string]string) bool {
 	if len(a) != len(b) {

services/control-plane/internal/differ/manifest_differ_test.go

@@ -1222,3 +1222,78 @@ func TestDiff_OrganizationUnchanged_NoChange(t *testing.T) {
 	assert.Len(t, noChanges, 1)
 	assert.Equal(t, "ACME_ENERGY", noChanges[0].ResourceCode)
 }
+
+// --- Internal Account differ tests ---
+
+func TestDiff_InternalAccountAdded_Create(t *testing.T) {
+	d := New(nil, nil)
+	oldManifest := testManifest()
+
+	newManifest := testManifest()
+	newManifest.InternalAccounts = []*controlplanev1.InternalAccountDefinition{
+		{Code: "REVENUE_GBP", AccountType: "REVENUE", Instrument: "GBP"},
+	}
+
+	plan, err := d.Diff(context.Background(), oldManifest, newManifest)
+	require.NoError(t, err)
+
+	creates := filterActionsByResource(plan.Actions, ActionCreate, ResourceInternalAccount)
+	assert.Len(t, creates, 1)
+	assert.Equal(t, "REVENUE_GBP", creates[0].ResourceCode)
+	assert.Contains(t, creates[0].Description, "REVENUE")
+	assert.Contains(t, creates[0].Description, "GBP")
+}
+
+func TestDiff_InternalAccountRemoved_Delete(t *testing.T) {
+	d := New(nil, nil)
+	oldManifest := testManifest()
+	oldManifest.InternalAccounts = []*controlplanev1.InternalAccountDefinition{
+		{Code: "SETTLEMENT_KWH", AccountType: "SETTLEMENT", Instrument: "KWH"},
+	}
+
+	newManifest := testManifest()
+
+	plan, err := d.Diff(context.Background(), oldManifest, newManifest)
+	require.NoError(t, err)
+
+	deletes := filterActionsByResource(plan.Actions, ActionDelete, ResourceInternalAccount)
+	assert.Len(t, deletes, 1)
+	assert.Equal(t, "SETTLEMENT_KWH", deletes[0].ResourceCode)
+}
+
+func TestDiff_InternalAccountModified_Update(t *testing.T) {
+	d := New(nil, nil)
+	oldManifest := testManifest()
+	oldManifest.InternalAccounts = []*controlplanev1.InternalAccountDefinition{
+		{Code: "REVENUE_GBP", AccountType: "REVENUE", Instrument: "GBP"},
+	}
+
+	newManifest := testManifest()
+	newManifest.InternalAccounts = []*controlplanev1.InternalAccountDefinition{
+		{Code: "REVENUE_GBP", AccountType: "CURRENT", Instrument: "GBP", OwnerOrganization: "ACME"},
+	}
+
+	plan, err := d.Diff(context.Background(), oldManifest, newManifest)
+	require.NoError(t, err)
+
+	updates := filterActionsByResource(plan.Actions, ActionUpdate, ResourceInternalAccount)
+	assert.Len(t, updates, 1)
+	assert.Equal(t, "REVENUE_GBP", updates[0].ResourceCode)
+	assert.Contains(t, updates[0].Description, "account_type:")
+	assert.Contains(t, updates[0].Description, "owner_organization:")
+}
+
+func TestDiff_InternalAccountUnchanged_NoChange(t *testing.T) {
+	d := New(nil, nil)
+	manifest := testManifest()
+	manifest.InternalAccounts = []*controlplanev1.InternalAccountDefinition{
+		{Code: "REVENUE_GBP", AccountType: "REVENUE", Instrument: "GBP"},
+	}
+
+	plan, err := d.Diff(context.Background(), manifest, manifest)
+	require.NoError(t, err)
+
+	noChanges := filterActionsByResource(plan.Actions, ActionNoChange, ResourceInternalAccount)
+	assert.Len(t, noChanges, 1)
+	assert.Equal(t, "REVENUE_GBP", noChanges[0].ResourceCode)
+}

services/control-plane/internal/differ/types.go

@@ -39,6 +39,7 @@ const (
 	ResourceMarketDataSource   ResourceType = "market_data_source"
 	ResourceMarketDataSet      ResourceType = "market_data_set"
 	ResourceOrganization       ResourceType = "organization"
+	ResourceInternalAccount    ResourceType = "internal_account"
 )
 
 // PlannedAction represents a single action in the diff plan.

services/control-plane/internal/planner/manifest_planner.go

@@ -121,6 +121,8 @@ func phaseForResource(rt differ.ResourceType) Phase {
 		return PhaseMarketDataSets
 	case differ.ResourceOrganization:
 		return PhaseOrganizations
+	case differ.ResourceInternalAccount:
+		return PhaseInternalAccounts
 	default:
 		return PhaseSeedData
 	}
@@ -208,6 +210,11 @@ var grpcMethodMap = map[methodKey]GRPCMethod{
 	{differ.ResourceOrganization, differ.ActionCreate}: MethodRegisterOrganization,
 	{differ.ResourceOrganization, differ.ActionUpdate}: MethodRegisterOrganization,
 	// No delete method: organizations are deactivated, not deleted.
+
+	// Internal Accounts
+	{differ.ResourceInternalAccount, differ.ActionCreate}: MethodInitiateAccount,
+	{differ.ResourceInternalAccount, differ.ActionUpdate}: MethodUpdateInternalAccount,
+	{differ.ResourceInternalAccount, differ.ActionDelete}: MethodControlInternalAccount,
 }
 
 // GenerateIdempotencyKey produces a deterministic SHA-256 based idempotency key.