family-instance-domain-actions

Family Instance Domain Actions

See also: ADR 204 — Domain actions vs composable primitives in the control plane. ADR 204 establishes the broader principle this rule applies inside family instances: action methods compose primitives; compound actions never call peer actions.

Overview

Family instances implement control-plane domain actions (emitContract, verify, schemaVerify, sign) and expose composable primitives (introspect, readMarker, validateContract) as methods. Distinguish them by return shape: actions return CLI/audit envelopes (...Result types with summary, code, meta, timings); primitives return raw data. Both should be self-contained and own their implementation logic.

Pattern: Inline Core Logic, Import Helper Functions

When implementing domain actions on family instances:

✅ CORRECT: Import helper functions, inline orchestration logic

// Import pure helper functions from core
import { canonicalizeContract } from '@internal/core-control-plane/emission/canonicalization';
import { computeExecutionHash, computeProfileHash, computeStorageHash } from '@internal/core-control-plane/emission/hashing';
import { format } from 'prettier';

// Inline the domain action orchestration
async emitContract({ contractIR }): Promise<EmitContractResult> {
  const ir = contractIR as ContractIR;

  // Validate structure
  // ... validation logic ...

  // Use helper functions
  const storageHash = computeStorageHash(contractJson);
  const executionHash = computeExecutionHash(contractJson);
  const profileHash = computeProfileHash(contractJson);
  const contractJsonString = JSON.stringify(
    { ...JSON.parse(canonicalizeContract(contractWithHashes)), _generated: {...} },
    null,
    2
  );

  // Generate types via hook
  const contractDts = await format(
    sqlTargetFamilyHook.generateContractTypes(ir, codecTypeImports, operationTypeImports),
    { parser: 'typescript', ... }
  );

  return { contractJson: contractJsonString, contractDts, storageHash, executionHash, profileHash };
}