export type ComponentVersionSource =
  | 'package-manifest'
  | 'webapp-registry'
  | 'daemon-package'
  | 'runtime-props'
  | 'static-class'
  | 'undeclared';

export type ComponentSourceKind =
  | 'runtime-direct'
  | 'runtime-child'
  | 'daemon-bundled'
  | 'installed-package'
  | 'folder-package'
  | 'installed-webapp'
  | 'external-webapp';

export type ComponentRegistrationSource =
  | 'package-manifest'
  | 'daemon-config'
  | 'deployment-spec';

export type ComponentArtifactFreshness =
  | 'current'
  | 'stale'
  | 'incomplete'
  | 'missing-manifest'
  | 'invalid-manifest'
  | 'unverifiable'
  | 'missing-output';

/**
 * Runtime-detectable provenance for a mounted component.
 *
 * This is intentionally explicit:
 * - when a version is declared, `versionSource` tells us exactly where it came from
 * - when a version is absent, `versionSource = "undeclared"` tells us we do not know
 *
 * We never invent or infer a version silently.
 */
export interface IComponentRuntimeMetadata {
  readonly packageName?: string;
  readonly version?: string;
  readonly versionSource: ComponentVersionSource;
  readonly sourceKind: ComponentSourceKind;
  readonly registrationSource?: ComponentRegistrationSource;
  readonly deploymentInstanceId?: string;
  readonly componentType?: string;
  readonly componentExport?: string;
  readonly manifestSource?: string;
  readonly appName?: string;
  readonly distPath?: string;
  readonly entryFile?: string;
  readonly modulePath?: string;
  readonly activationGeneration?: number;
  readonly buildGitSha?: string;
  readonly artifactBuiltAt?: string;
  readonly artifactSignature?: string;
  readonly artifactFreshness?: ComponentArtifactFreshness;
  readonly artifactFreshnessReason?: string;
}

export const COMPONENT_RUNTIME_METADATA = Symbol.for('matrix.component.runtimeMetadata');
